{"id":11787,"library":"react-native-onesignal","title":"React Native OneSignal SDK","description":"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.","status":"active","version":"5.4.3","language":"javascript","source_language":"en","source_url":"https://github.com/OneSignal/react-native-onesignal","tags":["javascript","android","apns","fcm","gcm","ios","notifications","onesignal","push","typescript"],"install":[{"cmd":"npm install react-native-onesignal","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-onesignal","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-onesignal","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React Native application integration.","package":"react-native","optional":false}],"imports":[{"note":"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.","wrong":"const OneSignal = require('react-native-onesignal');","symbol":"OneSignal","correct":"import OneSignal from 'react-native-onesignal';"},{"note":"For types and interfaces, it's best practice to use `import type` to ensure they are stripped from the JavaScript bundle.","wrong":"import { NotificationWillDisplayEvent, Notification } from 'react-native-onesignal';","symbol":"NotificationWillDisplayEvent, Notification","correct":"import type { NotificationWillDisplayEvent, Notification } from 'react-native-onesignal';"},{"note":"As with other types, always use `import type` for event interfaces to avoid potential runtime errors or unnecessary bundle size increases.","wrong":"import { InAppMessageClickEvent } from 'react-native-onesignal';","symbol":"InAppMessageClickEvent","correct":"import type { InAppMessageClickEvent } from 'react-native-onesignal';"}],"quickstart":{"code":"import React, { useEffect } from 'react';\nimport { View, Text, Alert, Platform } from 'react-native';\nimport OneSignal from 'react-native-onesignal';\n\nconst ONESIGNAL_APP_ID = process.env.ONESIGNAL_APP_ID ?? 'YOUR_ONESIGNAL_APP_ID';\n\nconst App = () => {\n  useEffect(() => {\n    // OneSignal Init Code\n    OneSignal.setAppId(ONESIGNAL_APP_ID);\n\n    // Method for setting the External User Id\n    OneSignal.setExternalUserId('your-user-id-from-your-system');\n\n    // Method for handling notifications received while app in foreground\n    OneSignal.setNotificationWillShowInForegroundHandler(notificationReceivedEvent => {\n      console.log(\"OneSignal: notification will show in foreground: \", notificationReceivedEvent);\n      let notification = notificationReceivedEvent.get ;();\n      Alert.alert(\"Notification Received\", notification.body || '');\n      notificationReceivedEvent.complete(notification);\n    });\n\n    // Method for handling notification clicks\n    OneSignal.setNotificationOpenedHandler(notification => {\n      console.log(\"OneSignal: notification opened: \", notification);\n      Alert.alert(\"Notification Clicked\", notification.notification.body || '');\n    });\n\n    // Prompt for push notifications (iOS) and Android 13+ permission\n    if (Platform.OS === 'ios' || (Platform.OS === 'android' && parseFloat(Platform.Version) >= 33)) {\n      OneSignal.promptForPushNotificationsWithProvisionalNotification();\n    }\n\n    return () => {\n      // Clean up listeners if necessary\n    };\n  }, []);\n\n  return (\n    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>\n      <Text>OneSignal React Native Example</Text>\n      <Text>Check console for OneSignal logs</Text>\n    </View>\n  );\n};\n\nexport default App;","lang":"typescript","description":"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+."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=5.4.0"},{"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.","message":"The `LiveActivities.Exit` method was deprecated in version 5.4.2 as it is currently unsupported by the underlying native SDKs.","severity":"deprecated","affected_versions":">=5.4.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.0.0"},{"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.","message":"Strict CodeGen rules for React Native and Expo apps can prevent builds, as fixed in version 5.4.3.","severity":"gotcha","affected_versions":">=5.4.0 <5.4.3"},{"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.","message":"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.","severity":"breaking","affected_versions":">=5.4.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Incorrectly accessing properties on the `notificationReceivedEvent` object in the `setNotificationWillShowInForegroundHandler` callback.","error":"OneSignal: notification will show in foreground:  { is and is not a valid Notification object }"},{"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.","cause":"Mismatch between the installed `react-native-onesignal` version and the `react-native` peer dependency requirement.","error":"Error: `react-native-onesignal` requires `react-native` version `>=0.76.0`."},{"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.","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.","error":"Error: Could not find `OneSignal.h` or `OneSignal.m` for iOS build."},{"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.","cause":"Migration of Android namespace from AndroidManifest.xml to build.gradle, which was addressed in older versions like 5.3.4.","error":"Build failed due to 'Namespace declaration' in AndroidManifest.xml after updating."}],"ecosystem":"npm"}