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 @userpilot/react-native 1.2.0 or later 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

During prebuild, the plugin adds android:host="sdk" alongside your configured scheme in the Android intent filter. Userpilot validates this host for preview and push-notification URLs; no separate host option is needed in the plugin configuration.

1. Install the Userpilot expo config plugin

 npx expo install @userpilot/expo-config

2. Add @userpilot/expo-config to the plugin list in your app.json file, and register the same value as your app's scheme:

 {
  "expo": {
    ...
    "scheme": "userpilot-APP_TOKEN",
    "plugins": [
      [
        "@userpilot/expo-config",
        {
          "scheme": "userpilot-APP_TOKEN"
        }
      ]
    ]
    ...
   }
 }

🔴 The scheme must be userpilot- followed by the Userpilot app token your app is initialized with, lowercased. That is the scheme the SDK builds its push notification deep links with, so a different value means notification taps never reach your app. The top-level scheme registers the URL type on iOS; the plugin prop adds the matching Android intent-filter.

3. Capture deep links with didHandleURL (custom URL scheme / experience previews):

 npx expo install expo-linking

const url = useURL();
useEffect(() => {
  if (!url) return;
  Userpilot.didHandleURL(url).then((userpilotDidHandleURL) => {
    if (!userpilotDidHandleURL) {
      // Handle a non-Userpilot URL
    }
  });
}, [url]);

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

This one handler covers push notification taps too. On Android the Userpilot SDK posts the notification itself and its tap opens userpilot-APP_TOKEN://sdk/notification?…, which arrives here as a normal deep link. On iOS taps are handled natively by the AppDelegate subscriber this plugin registers. You do not need expo-notifications.

Android delivers an FCM message to only one messaging service, so UserpilotFirebaseMessagingService must be the one that receives it. If your app registers another FirebaseMessagingService — expo-notifications, OneSignal, or a custom service — it may consume Userpilot messages and the notification will not appear.

4. 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());
}, []);

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.