Userpilot Expo Module

Userpilot Expo Module allows you to integrate Userpilot push notifications into your Expo app alongside the Userpilot React Native Module.

• Userpilot Expo Module
  • 🚀 Getting Started
    • Prerequisites
    • Usage
  • 🎬 Examples
  • 📄 License

🚀 Getting Started

Prerequisites

1. Ensure the Userpilot React Native Module is installed in your app and the SDK is initialized:

import * as Userpilot from '@userpilot/react-native'

await Userpilot.setup('<APP_TOKEN>', { logging: true });

2. It is recommended to have configured your Android and iOS push settings in Userpilot Studio.

3. Copy your Firebase configuration file into your project and set the path to the file in your app.json file, in the android.googleServicesFile (doc) property:

{
  "expo": {
    ...
    "android": {
      "googleServicesFile": "./google-services.json",
    }
  }
}

Note that Userpilot iOS push notifications do not use Firebase.

Usage

1. Install the Userpilot expo config plugin

 npm install @userpilot/expo-config

2. Add @userpilot/expo-config to the plugin list in your app.json file:

 {
  "expo": {
    ...
    "plugins": [
      [
        "../app.plugin.js",
        {
          "scheme": "userpilot_push_notification"
        }
      ]
    ]
    ...
   }
 }

The Userpilot Expo plugin injects the necessary configuration to properly handle push notifications. Make sure to set the scheme key in your plugin configuration.

3. SDK callbacks

To handle deep link triggers from push notifications, you can listen to SDK events as shown below. For more information, refer to the Userpilot React Native SDK.

useEffect(() => {
  const eventEmitter = new NativeEventEmitter(
    NativeModules.UserpilotReactNative
  );
  const listeners = [
    eventEmitter.addListener('UserpilotAnalyticsEvent', (event) =>
      console.log('Analytics Event:', event)
    ),
    eventEmitter.addListener('UserpilotExperienceEvent', (event) =>
      console.log('Experience Event:', event)
    ),
    eventEmitter.addListener('UserpilotNavigationEvent', (event) => {
      console.log('Navigation Event', event);
    }),
  ];
  return () => listeners.forEach((listener) => listener.remove());
}, []);

4. Configure push notification for Android:

npx expo install expo-notifications

Add notification.ts file to your project which is responsible for handling push notification in Android

  // notifications.ts
  import { useEffect, useRef } from 'react';
  import { Platform } from 'react-native';
  import * as Notifications from 'expo-notifications';
  import * as Userpilot from '@userpilot/react-native';

  /**
  * Notification handlers for Android platform.
  * 
  * Thanks for Swizzling in iOS, Userpilot's iOS SDK handles notifications automatically.
  * this hook sets up listeners for notification events from Android devices.
  * It listens for notifications received while the app is in the foreground,
  * and for responses when the user taps on a notification.
  * It also checks if the app was launched from a notification.
  * 
  * Pass the data from the notification to the `handleNotificationData` and `handleNotificationResponse` functions,
  * which call Userpilot SDK API.
  * If its Userpilot's SDK, it will return true, otherwise it will return false.
  * 
  * Listen for deep link triggering from NativeEventEmitter
  */
  export function useNotificationHandlers() {
    const responseListener = useRef<Notifications.Subscription>();

    useEffect(() => {
      if (Platform.OS !== 'android') return;

      // Request permission on mount
      requestNotificationPermissions();

      // This is for when the user taps on the notification
      responseListener.current = Notifications.addNotificationResponseReceivedListener(response => {
        console.log('Notification response:', response);
        const data = response.notification.request.content.data;
        handleNotificationResponse(data);
      });

      // Check if app was launched via notification
      checkInitialNotification();

      return () => {
        if (responseListener.current) {
          Notifications.removeNotificationSubscription(responseListener.current);
        }
      };
    }, []);
  }

  async function requestNotificationPermissions() {
    const { status } = await Notifications.getPermissionsAsync();
    if (status !== 'granted') {
      const { status: newStatus } = await Notifications.requestPermissionsAsync();
      console.log('Notification permission status:', newStatus);
    } else {
      console.log('Notification permission already granted');
    }
  }

  async function checkInitialNotification() {
    if (Platform.OS !== 'android') return;

    const response = await Notifications.getLastNotificationResponseAsync();
    if (response) {
      console.log('App opened from notification:', response);
      const data = response.notification.request.content.data;
      handleNotificationResponse(data);
    }
  }

  function handleNotificationResponse(data: Record<string, any>) {
    console.log('Handling notification response:', data);
    // Pass intent data to Userpilot SDK to handle it, return false incase
    // it's not Userpilot push notification
    Userpilot.didHandleIntent(data);
  }

No iOS configuration needed, thanks for Swizzling in iOS, Userpilot's iOS SDK handles notifications automatically.

5. Test locally with a new development or EAS build:

npx expo prebuild

🎬 Examples

The example directory in this repository contains full example Expo app to providing references for correct installation of the Userpilot Expo Module.

📄 License

This project is licensed under the MIT License. See LICENSE for more information.