DOCSEARCHbyAlgolia
Submit Docs

OneSignal Expo Plugin

repository·main·Indexed 41 days ago

https://github.com/onesignal/onesignal-expo-plugin

An Expo Config Plugin for integrating OneSignal push notification capabilities into Expo managed workflow projects. It automates native code configuration for iOS and Android, supporting features such as Live Activities, custom notification sounds, and the ability to disable the native location module. Version 2.7.1.

Tokens
9.3K
Snippets
27
Records
49
Agent score
50%

What's inside OneSignal Expo Plugin

  1. Overview of the OneSignal Expo plugin

    main

    The onesignal-expo-plugin is an Expo Config Plugin that enables the use of OneSignal within the Expo managed workflow. It automates the generation and configuration of the native code required for the OneSignal React-Native SDK to function, eliminating the need to eject to a bare workflow.

    This plugin is compatible with:

    • Expo run commands (expo run:android, expo run:ios)
    • Custom development clients
    • EAS Build (Expo Application Services)

  2. Project Structure of the OneSignal Expo Demo

    main

    The demo project follows a structured layout for managing OneSignal features and UI components:

    • src/hooks/useOneSignal.ts: The primary hook for interacting with the OneSignal SDK.
    • src/services/OneSignalApiService.ts: Handles REST API calls (e.g., for Live Activities) using EXPO_PUBLIC_ONESIGNAL_API_KEY.
    • src/components/sections/: Contains feature-specific UI modules like PushSection.tsx, InAppSection.tsx, and LiveActivitySection.tsx.
    • customWidget/LiveActivity.swift: Hand-authored Swift code for iOS Live Activity widgets.
    • customNSE/NSE.m: Native code for Notification Service Extensions.

    Note: Native ios/ and android/ folders are generated via npx expo prebuild. The ios/OneSignalWidget directory is specifically tracked in git to prevent loss of hand-authored Swift files.

  3. Resolve conflicts between OneSignal and expo-notifications

    main

    When using onesignal-expo-plugin alongside expo-notifications, a conflict can occur regarding notification response listeners. To allow both libraries to function together, you must ensure specific configuration ordering during the Expo prebuild process.

    Configuration Requirements

    • Plugin Ordering: In app.config.ts, expo-notifications must be listed in the plugins array before onesignal-expo-plugin.
    • Compatibility Plugin: Use a config plugin (like withExpoNotificationsDelegate) that updates the generated AppDelegate.swift. This plugin sets Expo's NotificationCenterManager as the UNUserNotificationCenter delegate before OneSignal initializes.

    Important Notes

    • This is a workaround to allow Expo's local notification listeners and OneSignal's notification callbacks to coexist; it is not a guaranteed compatibility contract.
    • Do not commit the ios directory. If you need to re-apply the workaround, run the clean command to re-trigger the prebuild process.
    • The goal is for the OneSignal SDK to eventually support local notifications directly to remove the need for this overlapping plugin setup.

  4. Determine if you need a Simple or Complex iOS setup

    main

    The complexity of your iOS credential setup depends on whether your app uses capabilities other than 'Push Notifications'.

    Simple Setup

    Condition: Your app only requires the 'Push Notifications' capability. Behavior: OneSignal automatically adds the capability and necessary App Groups. You can use Managed credentials on EAS without issues.

    Complex Setup

    Condition: Your app has multiple capabilities (e.g., Location, Bluetooth, etc.). Behavior: Because EAS may struggle to sync multiple entitlement files across the main app target and the OneSignalNotificationServiceExtension target, you must use Local credentials to ensure all capabilities are correctly applied to both targets.

    How to check: Run expo prebuild and inspect the native entitlements file in the ios directory to see if other plugins or manual configurations have added capabilities.

  5. How to enable and configure OneSignal Live Activities

    main

    To use OneSignal Live Activities on iOS, you must add the liveActivities property to your plugin configuration. This scaffolds the necessary iOS Widget Extension target.

    Configuration:

    To use the default OneSignalWidget target:

    {
  "plugins": [
    [
      "onesignal-expo-plugin",
      {
        "mode": "development",
        "liveActivities": {}
      }
    ]
  ]
}

    To customize the widget:

    {
  "liveActivities": {
    "targetName": "MyWidget",
    "bundleIdentifierSuffix": "widget",
    "widgetFilePath": "./widgets/MyWidgetLiveActivity.swift",
    "deploymentTarget": "16.2"
  }
}

    Implementation Requirements:

    1. iOS Version: Requires iOS 16.2+.
    2. APNs Key: You must use a .p8 APNs key (p12 is not supported for Live Activities).
    3. Initialization: You must call OneSignal.LiveActivities.setupDefault() in your app code after initializing OneSignal.

    Code Example:

    import { OneSignal } from 'react-native-onesignal';

OneSignal.initialize('YOUR-ONESIGNAL-APP-ID');
OneSignal.LiveActivities.setupDefault();
    import { OneSignal } from 'react-native-onesignal';

OneSignal.initialize('YOUR-ONESIGNAL-APP-ID');
OneSignal.LiveActivities.setupDefault();

  7. Run an iOS EAS-built app in a custom development client

    main

    For development or internal distribution builds, you must use an Expo development client. Follow these steps to run your app after a successful EAS build:

    1. Install the client: Scan the QR code provided in your terminal after the EAS build completes to install the development client application on your iOS device.
    2. Start the bundler: In your terminal, run expo start --dev-client to serve the application.
    3. Fetch the bundle: Scan the newly generated QR code in the terminal to open the dev client and fetch the app bundle from your local Expo process.
    4. Network Permissions: If prompted to allow the app to find devices on your local area network, select Approve.
    5. Launch: Rescan the QR code and open the app. Once the Metro bundler completes the bundle, your application will launch.
    expo start --dev-client

  8. Setup the OneSignal + expo-notifications Example

    main

    To set up this example project, you must configure your OneSignal App ID in a .env file and install the project dependencies.

    1. Copy the example environment file:
      cp .env.example .env
    2. Open .env and set your OneSignal App ID:
      EXPO_PUBLIC_ONESIGNAL_APP_ID=your-onesignal-app-id
    3. Install dependencies using the project's package manager:
      vp install
    cp .env.example .env
# Edit .env to set EXPO_PUBLIC_ONESIGNAL_APP_ID

vp install

  9. Get started with the demo project

    main

    To run the provided demo project, install the dependencies and start the Expo development server.

    Note: This project uses file-based routing and the code is located in the app directory. You can run the app in a development build, Android emulator, iOS simulator, or Expo Go.

    npm install
npx expo start