Registry / communication / react-native-onesignal

react-native-onesignal

library5.4.3jsnpmunverified

The React Native OneSignal SDK facilitates the integration of OneSignal's push notification, in-app messaging, email, and SMS services into iOS and Android applications built with React Native. The current stable version is 5.4.3. This library is actively maintained with frequent minor and patch releases, often addressing native SDK updates, bug fixes, and new features like the recent support for React Native's New Architecture (TurboModules) introduced in v5.4.0. Key differentiators include its comprehensive cross-platform support for various notification types and its user-centric APIs for managing user data across channels, distinguishing it from lower-level notification APIs provided by mobile OS platforms.

communication

npm install react-native-onesignal

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-NATIVE-ONESI

react-native-onesignal

communicationjavascriptv5.4.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

OneSignal

✓ import OneSignal from 'react-native-onesignal';

✗ const OneSignal = require('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

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

✗ import { 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

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

✗ import { 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.

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;

Debug

Known issues

breakingVersion 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.

affects: >=5.4.0

deprecatedThe `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.

affects: >=5.4.2

gotchaOneSignal'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.

affects: >=5.0.0

gotchaStrict 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.

affects: >=5.4.0 <5.4.3

breakingUpdate 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.

affects: >=5.4.2

Errors

Common errors & fixes

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

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`.

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.

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.

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.

Upgrade

Version history

5.4.3latest on npm

Audit

Dependencies

react-nativerequiredPeer dependency for React Native application integration.

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/OneSignal/react-native-onesignal ↗

packagehttps://www.npmjs.com/package/react-native-onesignal ↗

homepagehttps://onesignal.com ↗