Expo SDK Setup
Instructions for adding the OneSignal React Native & Expo SDK to your app for iOS, Android, and derivatives like Amazon.
Expo Managed Workflow
This documentation shows how to use our SDK with your Expo Managed Workflow application.
If you are using the Bare Workflow, please review the React Native + Expo SDK Setup instead.
Requirements
- OneSignal Account
- OneSignal App ID, available in Settings > Keys & IDs
iOS Requirements
- iOS 11+ or iPadOS 11+ device (iPhone, iPad, iPod Touch) to test on. Xcode 14+ simulator works running iOS 16+
- mac with Xcode 12+
- p8 Authentication Token or p12 Push Notification Certificate
- Your
app.json
oreas.json
orapp.config.js
file needs the iOSbundleIdentifier
property set. See Expo > Configure development and production variants.
Android Requirements
- Android 5.0+ device or emulator with "Google Play Store (Services)" installed
- Set up your Android Firebase Credentials
Amazon & Huawei Requirements
Follow these instructions if your app is distributed on the Amazon AppStore and/or the Huawei AppGallery.
1. Add the OneSignal package to your app
OneSignal Expo Sample App
Sample repo containing the sample app for running OneSignal with Expo.
Make sure you have the Expo CLI installed on your computer.
1.1 Install the OneSignal Expo plugin using the Expo CLI
npx expo install onesignal-expo-plugin
1.2 Install the SDK using Yarn or NPM
- Yarn:
yarn add react-native-onesignal
- NPM
npm install --save react-native-onesignal
1.3 Configure your app.json/app.config.js
Add the plugin to the plugin array:
app.json
{
"plugins": [
[
"onesignal-expo-plugin",
{
"mode": "development",
}
]
]
}
or
app.config.js
export default {
...
plugins: [
[
"onesignal-expo-plugin",
{
mode: "development",
}
]
]
};
Plugin Prop
You can pass props to the plugin config object to configure:
Plugin Prop | ||
---|---|---|
mode | required | Used to configure APNs environment entitlement. "development" or "production" |
devTeam | optional | Used to configure Apple Team ID. You can find your Apple Team ID by running expo credentials:manager e.g: "91SW8A37CR" |
iPhoneDeploymentTarget | optional | Target IPHONEOS_DEPLOYMENT_TARGET value to be used when adding the iOS NSE. A deployment target is nothing more than the minimum version of the operating system the application can run on. This value should match the value in your Podfile e.g: "12.0" . |
smallIcons | optional | An array of local paths to small notification icons for Android. Image should be white, transparent, and 96x96 in size. Input images will be automatically scaled down and placed in the appropriate resource folders. e.g: ["./assets/ic_stat_onesignal_default.png"] . See https://documentation.onesignal.com/docs/customize-notification-icons#small-notification-icons. |
largeIcons | optional | An array of local paths to large notification icons for Android. Image should be white, transparent, and 256x256 in size. e.g: ["./assets/ic_onesignal_large_icon_default.png"] . See https://documentation.onesignal.com/docs/customize-notification-icons#large-notification-icons. |
iosNSEFilePath | optional | The local path to a custom Notification Service Extension (NSE), written in Objective-C. The NSE will typically start as a copy of the default NSE, then altered to support any custom logic required. e.g: "./assets/NotificationService.m" . |
1.4 Adding the OneSignal App ID
Add your OneSignal App ID to your Expo constants via the extra param:
{
"extra": {
"oneSignalAppId": "<YOUR APP ID HERE>"
}
}
You can then access the value to pass to the initialize function:
import { LogLevel, OneSignal } from 'react-native-onesignal';
import Constants from "expo-constants";
OneSignal.Debug.setLogLevel(LogLevel.Verbose);
OneSignal.initialize(Constants.expoConfig.extra.oneSignalAppId);
// Also need enable notifications to complete OneSignal setup
OneSignal.Notifications.requestPermission(true);
Alternatively, pass the OneSignal app ID directly to the function:
OneSignal.initialize("YOUR-ONESIGNAL-APP-ID");
1.5 Run your Expo app
You need to create a development build for your app.
$ npx expo prebuild
# Build your native iOS project
$ npx expo run:ios
# Build your native Android project
$ npx expo run:android
2. Testing
Run your app on a physical device to make sure it builds correctly.
If you used the provided code, then the requestPermission
method, should prompt you to subscribe to push notifications. You can change this later.
Check your OneSignal Dashboard Audience > Subscriptions to see your User & Subscription Record.
Then head over to Messages > New Push to Send your first Push Notification from OneSignal.
Please note that Identity Verification is coming soon to v5 of the Expo SDK.
Troubleshooting
If running into issues, see our Mobile Troubleshooting Guide.
Try our example projects on our Github repository.
If stuck, contact support directly or email [email protected] for help.
For faster assistance, please provide:
- Your OneSignal App ID
- Details, logs, and/or screenshots of the issue.
- Steps to reproduce
Recommended
Push permission with In-App Message
You can continue to opt-in users to push via the requestPermission
method. However, Apple's Human Interface Guidelines recommends that apps "Create an alert, modal view, or other interface that describes the types of information they want to send and gives people a clear way to opt in or out."
OneSignal provides In-App Messages to meet this recommendation and have a better user experience. This also permits you to ask for permission again in the future, since the native permission prompt is limited to how many times it can show and cannot be shown again if the user clicks deny.
See How to Prompt for Push Permissions with In-App Messages for details on implementing this.
Identify Users
Required if using integrations.
Recommended for messaging across multiple channels (push, email, sms).
OneSignal creates subscription-level records under a unique ID called the subscription_id
. A single user can have multiple subscription_id
records based on how many devices, email addresses, and phone numbers they use to interact with your app.
If your app has its own login system to track users, call login
at any time to link all channels to a single user. For more details, see Aliases & External ID.
let externalId = "123456789" // You will supply the external id to the OneSignal SDK
OneSignal.login(externalId);
Set Email & Phone Number
Recommended for messaging across multiple channels (push, email, sms).
Use the provided SDK methods to capture one or more email/phone numbers for the user. Follow the channel quickstart guides for setup:
// Pass in email provided by customer
OneSignal.User.addEmail("[email protected]");
// Pass in phone number provided by customer
OneSignal.User.addSms("+11234567890");
Add Data Tags
Optional
Tags are custom key : value
pairs of String data used for tracking user events and properties. Setting tags is required for more complex segmentation and message personalization.
- See Data Tags for more details.
OneSignal.User.addTag("key", "value");
Updated 5 months ago