DOCSEARCHbyAlgolia
Submit Docs

React Native OneSignal SDK

repository·main·Indexed 23 days ago

https://github.com/onesignal/react-native-onesignal

SDK for integrating OneSignal's email, SMS, push notification, and in-app messaging services into React Native applications for iOS and Android. Version 5.5.6 supports TurboModules for React Native >=0.79.0, while version 5.3.x is compatible with React Native 0.76–0.78 and Expo SDK 52.

Tokens
15.3K
Snippets
33
Records
75
Agent score
79%

What's inside react-native-onesignal

  1. Understand the User-Centered Model (v5.x.x)

    main

    OneSignal v5.x.x shifts from a device-centered model to a user-centered model. This replaces the legacy "player" concept with three core abstractions:

    • Users: Represents the end-user. A user can have zero or more subscriptions and can be identified by one or more aliases (key-value pairs). Users can also have data tags for attribution.
    • Subscriptions: The method by which a user receives communications (Push, SMS, or Email). A single user can own one Push Subscription and multiple Email/SMS subscriptions. The subscription_id is the new term for the legacy player_id.
    • Aliases: Evolved from "external user ids". An alias consists of an alias label (the key) and an alias id (the value). OneSignal uses a built-in label external_id to support existing external user ID workflows.

  2. Understand device-scoped users and identity

    main

    A device-scoped user is an anonymous user with no aliases. Upon app installation, the OneSignal SDK is initialized with a device-scoped user.

    To upgrade a device-scoped user to an identified user, use the OneSignal.login("USER_EXTERNAL_ID") method. This associates the device with a specific external user ID.

  4. How OneSignal State Management works in React Native

    main

    The recommended architecture for managing OneSignal state in a React Native application involves a OneSignalProvider and a useOneSignal hook.

    • OneSignalProvider: Wraps the application tree to provide access to the SDK state.
    • useOneSignal Hook: Provides access to the SDK and manages internal state via useState. All SDK initialization, event listeners, and state restoration (from AsyncStorage) should occur within a useEffect inside this hook.
    • Persistence: Use AsyncStorage (via a wrapper like PreferencesService) to persist consent flags and user identifiers.
    • Restoration Flow:
      1. Read consent flags from storage.
      2. Set consent flags on the SDK.
      3. Call OneSignal.initialize().
      4. Restore In-App Message (IAM) paused status and Location sharing.
      5. Restore user session via OneSignal.login() if an external ID is available.

  5. Configure Environment Variables for OneSignal

    main

    The demo project uses react-native-dotenv to load environment variables from a .env file at build time. You can import these variables using the @env module.

    Required keys for the demo implementation:

    • ONESIGNAL_APP_ID: The OneSignal App ID passed to OneSignal.initialize(...).
    • ONESIGNAL_API_KEY: The REST API key used for sending notifications and managing Live Activities.
    • ONESIGNAL_ANDROID_CHANNEL_ID: The Android channel ID used when sending notifications with sound (android_channel_id).

    Example import:

    import { ONESIGNAL_APP_ID } from '@env';

  6. Build and run the iOS app

    main

    To run the application on iOS, you must first ensure CocoaPods dependencies are installed.

    1. Install CocoaPods via Ruby bundler (if first time): bundle install.
    2. Install native dependencies: bundle exec pod install.
    3. Run the app using npm or Yarn.
    # Install CocoaPods dependencies
bundle install
bundle exec pod install

# Run the app
# Using npm
npm run ios

# OR using Yarn
yarn ios

  8. Disable the OneSignal Location Module

    main

    By default, the SDK includes a native location module. If your app does not use location features, you can exclude it from iOS and Android builds to reduce footprint.

    iOS (CocoaPods)

    Set ONESIGNAL_DISABLE_LOCATION=true before running pod install from the ios directory.

    Android (Gradle)

    Set ONESIGNAL_DISABLE_LOCATION=true before running Gradle commands, or persist the setting in android/gradle.properties using onesignal.disableLocation=true.

    Behavior when disabled

    • OneSignal.Location.requestPermission() and OneSignal.Location.setShared() become no-ops.
    • OneSignal.Location.isShared() will always resolve to false.

    Applying changes to existing projects

    Because CocoaPods pins dependencies in Podfile.lock, you must clear the cache and reinstall pods after changing the environment variable:

    cd ios
pod deintegrate
rm -rf Pods Podfile.lock
ONESIGNAL_DISABLE_LOCATION=true pod install
    # iOS
ONESIGNAL_DISABLE_LOCATION=true pod install

# Android
ONESIGNAL_DISABLE_LOCATION=true ./gradlew assembleDebug
    # Android (android/gradle.properties)
onesignal.disableLocation=true
    # GitHub Actions
env:
  ONESIGNAL_DISABLE_LOCATION: true

  9. Configure Android Permissions for Location

    main

    If your application uses location-based features (such as OneSignal Location triggers), ensure the following permissions are declared in your android/app/src/main/AndroidManifest.xml:

    <uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

  11. Configure Live Activities (iOS only)

    main

    OneSignal supports iOS Live Activities. To use them, you must configure the SDK and manage activity lifecycles via the OneSignal API.

    Setup:

    1. SDK Initialization: Call OneSignal.LiveActivities.setupDefault({ enablePushToStart: true, enablePushToUpdate: true }) during app initialization.
    2. Starting an Activity: Use OneSignal.LiveActivities.startDefault(activityId, attributes, content).
    3. Updating/Ending: Updates and endings are performed via a REST API service against https://api.onesignal.com/apps/{appId}/live_activities/{activityId}/notifications, authenticated with your ONESIGNAL_API_KEY.

    iOS Project Requirements: Your ios/Podfile must include the following targets to support rich media and Live Activities:

    • OneSignalNotificationServiceExtension (for NSE/rich media)
    • OneSignalWidgetExtension (for Live Activity widgets)

    Both targets should pin OneSignalXCFramework '>= 5.0.0', '< 6.0'.

  12. Reload the application

    main

    If you need to perform a full reload to reset the app state, use the following platform-specific shortcuts:

    • Android: Press the <kbd>R</kbd> key twice, or open the Dev Menu via <kbd>Ctrl</kbd> + <kbd>M</kbd> (Windows/Linux) or <kbd>Cmd ⌘</kbd> + <kbd>M</kbd> (macOS) and select "Reload".
    • iOS: Press <kbd>R</kbd> in the iOS Simulator.