React Native OneSignal SDK

Common errors

• OneSignal: notification will show in foreground:  { is and is not a valid Notification object }

  cause Incorrectly accessing properties on the `notificationReceivedEvent` object in the `setNotificationWillShowInForegroundHandler` callback.
  fix Access the `Notification` object using `notificationReceivedEvent.getNotification()` and then its properties (e.g., `notification.body`). The `notificationReceivedEvent` itself is not the `Notification` object directly.

• Error: `react-native-onesignal` requires `react-native` version `>=0.76.0`.

  cause Mismatch between the installed `react-native-onesignal` version and the `react-native` peer dependency requirement.
  fix Update your `react-native` package to a compatible version (e.g., `>=0.76.0`) or downgrade `react-native-onesignal` to a version that supports your current `react-native` version. Check the `package.json` for specific peer dependency ranges.

• Error: Could not find `OneSignal.h` or `OneSignal.m` for iOS build.

  cause Common CocoaPods or native module linking issue, often after upgrading React Native or `react-native-onesignal`, or when clearing `node_modules` and not reinstalling pods.
  fix Navigate to your `ios` directory and run `pod install`. Ensure `OneSignal` is correctly linked in your `Podfile`. Clean your Xcode build folder (`Product > Clean Build Folder`) and delete derived data.

• Build failed due to 'Namespace declaration' in AndroidManifest.xml after updating.

  cause Migration of Android namespace from AndroidManifest.xml to build.gradle, which was addressed in older versions like 5.3.4.
  fix Ensure you are on `react-native-onesignal@5.3.4` or newer. Manually move the `namespace` declaration from `AndroidManifest.xml` to your `app/build.gradle` file, if it still exists there, following modern Android Gradle Plugin conventions.

Warnings

• breaking Version 5.4.0 introduced support for React Native's New Architecture (TurboModules). Old architecture may not work correctly anymore. Existing projects must update their builds and clean old build artifacts.
  Fix: For Android: `rm -rf android/app/build android/app/.cxx android/build`. For iOS: `rm -rf ios/build ios/Pods && cd ios && pod install`. Ensure your React Native project is configured for the New Architecture if you intend to use it, or continue with compatibility modes carefully.
• deprecated The `LiveActivities.Exit` method was deprecated in version 5.4.2 as it is currently unsupported by the underlying native SDKs.
  Fix: Avoid using `LiveActivities.Exit`. If you have existing code relying on this, remove it or find alternative solutions outside the OneSignal SDK for managing Live Activities.
• gotcha OneSignal's new user-centric APIs and v5.x.x SDKs offer an improved user and data management experience but may not have 1:1 feature parity with previous versions. Migrating existing apps requires careful testing.
  Fix: When migrating an existing app, follow the migration advisory from OneSignal. Utilize iOS Phased Rollout and Google Play Staged Rollouts to ensure no unexpected issues. Contact OneSignal support if challenges arise.
• gotcha Strict CodeGen rules for React Native and Expo apps can prevent builds, as fixed in version 5.4.3.
  Fix: Update to `react-native-onesignal@5.4.3` or newer to resolve issues with strict CodeGen rules that might prevent your app from building correctly.
• breaking Update Android SDK from 5.7.6 to 5.7.7 in v5.4.2 includes a downgrade of Kotlin from 2.2.0 to 1.9.25. This could cause build issues if your project explicitly uses or relies on Kotlin 2.2.0 or newer.
  Fix: Ensure your project's Kotlin version is compatible with 1.9.25 or is managed correctly to avoid conflicts. Clean Android build caches after updating.

Install

• npm install react-native-onesignal npm
• yarn add react-native-onesignal yarn
• pnpm add react-native-onesignal pnpm

Imports

• OneSignal
  wrong:

  const OneSignal = require('react-native-onesignal');

  correct:

  import OneSignal from 'react-native-onesignal';

  While CommonJS `require` might work in some older setups, modern React Native and TypeScript projects strongly prefer ES module imports. OneSignal is typically imported as a default export.
• NotificationWillDisplayEvent, Notification
  wrong:

  import { NotificationWillDisplayEvent, Notification } from 'react-native-onesignal';

  correct:

  import type { NotificationWillDisplayEvent, Notification } from 'react-native-onesignal';

  For types and interfaces, it's best practice to use `import type` to ensure they are stripped from the JavaScript bundle.
• InAppMessageClickEvent
  wrong:

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

  correct:

  import type { InAppMessageClickEvent } from 'react-native-onesignal';

  As with other types, always use `import type` for event interfaces to avoid potential runtime errors or unnecessary bundle size increases.

Quickstart

This quickstart code initializes the OneSignal SDK, sets an external user ID, and registers handlers for incoming notifications (foreground) and notification clicks. It also prompts for push notification permissions on iOS and Android 13+.

import React, { useEffect } from 'react';
import { View, Text, Alert, Platform } from 'react-native';
import OneSignal from 'react-native-onesignal';

const ONESIGNAL_APP_ID = process.env.ONESIGNAL_APP_ID ?? 'YOUR_ONESIGNAL_APP_ID';

const App = () => {
  useEffect(() => {
    // OneSignal Init Code
    OneSignal.setAppId(ONESIGNAL_APP_ID);

    // Method for setting the External User Id
    OneSignal.setExternalUserId('your-user-id-from-your-system');

    // Method for handling notifications received while app in foreground
    OneSignal.setNotificationWillShowInForegroundHandler(notificationReceivedEvent => {
      console.log("OneSignal: notification will show in foreground: ", notificationReceivedEvent);
      let notification = notificationReceivedEvent.get ;();
      Alert.alert("Notification Received", notification.body || '');
      notificationReceivedEvent.complete(notification);
    });

    // Method for handling notification clicks
    OneSignal.setNotificationOpenedHandler(notification => {
      console.log("OneSignal: notification opened: ", notification);
      Alert.alert("Notification Clicked", notification.notification.body || '');
    });

    // Prompt for push notifications (iOS) and Android 13+ permission
    if (Platform.OS === 'ios' || (Platform.OS === 'android' && parseFloat(Platform.Version) >= 33)) {
      OneSignal.promptForPushNotificationsWithProvisionalNotification();
    }

    return () => {
      // Clean up listeners if necessary
    };
  }, []);

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text>OneSignal React Native Example</Text>
      <Text>Check console for OneSignal logs</Text>
    </View>
  );
};

export default App;