Cordova SDK Setup
Instructions for adding the OneSignal SDK to your Cordova app for iOS, Android, and derivatives like Amazon
Looking for Ionic setup?
See our Ionic SDK Setup guide instead. This includes Ionic Cordova.
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
- Cordova [email protected] or newer
- CocoaPods version 1.12.1+ Install with the following from the Terminal:
sudo gem install cocoapods
pod repo update
Android Requirements
- Android 5.0+ device or emulator with "Google Play Store (Services)" installed
- Set up your Android Firebase Credentials
- Cordova [email protected] or newer
- compileSDKVersion 33 or higher
Amazon & Huawei Requirements
- Generate an Amazon API Key
- Place your
api_key.txt
file into your<project-dir>/platforms/android/assets/
folder.
- Place your
- Huawei Cordova SDK Setup
Setup
1. Add SDK
You should remove any other push SDKs that you are not using – otherwise, you may see duplicate notifications being sent to your users.
Run the following from your project directory:
cordova plugin add onesignal-cordova-plugin@^5.0.0 --save
2. Initialization
Add the following to the bottom of the first Javascript file that loads with your app. This is <project-dir>/www/js/index.js
for most Cordova projects.
// Add to index.js or the first page that loads with your app.
document.addEventListener('deviceready', OneSignalInit, false);
function OneSignalInit() {
// Uncomment to set OneSignal device logging to VERBOSE
// window.plugins.OneSignal.Debug.setLogLevel(6);
// Uncomment to set OneSignal visual logging to VERBOSE
// window.plugins.OneSignal.Debug.setAlertLevel(6);
// NOTE: Update the init value below with your OneSignal AppId.
window.plugins.OneSignal.initialize("YOUR_ONESIGNAL_APP_ID");
//Adds an event listener for clicks on notifications
const listener = (event: NotificationClickEvent) => {
const notificationData = JSON.stringify(event);
};
window.plugins.OneSignal.Notifications.addEventListener("click", listener);
//Prompts the user for notification permissions.
// * Since this shows a generic native prompt, we recommend instead using an In-App Message to prompt for notification permission (See step 6) to better communicate to your users what notifications they will get.
window.plugins.OneSignal.Notifications.requestPermission(true).then((accepted) => {
console.log("User accepted notifications: " + accepted);
});
}
Update initialization parameters. Replace YOUR_ONESIGNAL_APP_ID
with your OneSignal App ID, available in the OneSignal dashboard under Settings > Keys & IDs.
3. Android Settings
Validate your target SDK version is at least version 33.
Requirements:
- Cordova Android Platform 9.1.0 or higher
android {
compileSdkVersion 33
...
defaultConfig {
...
targetSdkVersion 33
}
}

Set the Compile Sdk Version to 33.

In Default Config, set the Target SDK Version to 33.
4. iOS Settings
4.1 In /platforms/ios
open the .wcworkspace
project in Xcode.
- Run
xed platforms/ios
from your project directory to do this.
4.2 Select the root project, and underSigning & Capabilities
, enablePush Notifications
.
4.3 Next, enableBackground Modes
and checkRemote Notifications
.
iOS Service Extensions
Highly recommended: This step is optional but highly recommended. The OneSignalNotificationServiceExtension
allows your application (in iOS) to receive rich notifications with images and/or buttons, along with Badges and advanced analytics like Outcomes.
4.4 Please follow the Notification Service Extension guide (only Step 4).
4.5 Select the new OneSignalNotificationServiceExtension
Target, select Build Settings
, then search for Code Signing Entitlements
.
4.6 Delete both Debug
and Release
entries so they are blank.
4.7 In the Project Navigator, select the top-level project directory and select the OneSignalNotificationServiceExtension
target.
Ensure the Deployment Target
is set to the same value as your Main Application Target. Unless you have a specific reason not to, you should set the Deployment Target
to be iOS 10 which is the version of iOS that Apple released Rich Media for push. iOS versions under 10 will not be able to get Rich Media.

This should be the same value as your Main Application Target.
4.8 Close Xcode and open platform/ios/Podfile
4.9 Add the following to the bottom of the file.
target 'OneSignalNotificationServiceExtension' do
pod 'OneSignalXCFramework', '>= 5.0', '< 6.0'
end
4.10 Open your terminal to platform/ios
and run pod install
iOS - Add App Groups (Recommended)
In order for your application to use Confirmed Deliveries and increment/decrement Badges through push notifications, you need to setup an App Group for your application.
Please follow the iOS SDK App Groups setup guide to add the OneSignal App Group in your app.
iOS Automatic Builds (Optional)
If you are using an automated build system, you may run into issues where the Push Notification capability is not enabled for your project. In order to resolve this problem, you can follow these steps:
4.11 In your Xcode project, make sure the Push Notifications capability (as well as any other capabilities your app needs).
4.12 Close the Xcode project. In the /platforms/ios
folder you will see a {yourProjectName}.entitlements
file. Copy this file to the root of your Cordova project.
4.13 Edit your config.xml
file to include the following. Make sure to replace [yourProjectName]
with the name of your project.
<platform name="ios">
<resource-file src="[yourProjectName].entitlements" />
</platform>
5. 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 Cordova SDK.
Troubleshooting
If you run into any issues please see our Cordova Variants troubleshooting guide.
Try the example project 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.
// TODO get implementation details
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
window.plugins.OneSignal.User.addEmail("[email protected]");
// Pass in phone number provided by customer
window.plugins.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.
window.plugins.OneSignal.User.addTag("key", "value");
Add Android Notification Icons
Follow the Android Notification Icons instructions to create small notification icons.
Setup Complete!
Visit Mobile Push Guide for next steps.
Updated 15 days ago