Xcode 10 Notice
To prevent Mismatched User errors, upgrade cordova-ios to 5.0.0
Required For Setup
- A OneSignal Account if you do not already have one
- Your OneSignal App ID, available in Keys & IDs
- iOS - An iOS device (iPhone, iPad, iPod Touch) to test on. The Xcode simulator doesn't support push notifications so you must test on a real device.
- iOS - You MUST have a Mac with a new version of Xcode
Example Project
For your convenience, we created an example project you can use to get started and learn about using OneSignal with Cordova.
Update SDK
If you already have an app with the Cordova SDK, you can run this to ensure your SDK is on the latest version:
cordova plugin update onesignal-cordova-pluginIf you have not set up an app yet, follow the instructions below.
Setup SDK
Generate Credentials
Before setting up the Cordova SDK, you must generate the appropriate credentials for the platform(s) you are releasing on:
iOS - Generate an iOS Push Certificate
Android - Generate a Google Server API Key
Amazon - Generate an Amazon API Key
iOS Requirements
1. Xcode 10 Compatibility - Please follow Cordova's Xcode 10 workaround
2. Cordova ios@4.3.0 or newer
3. CocoaPods - Install with the following from the terminal.
sudo gem install cocoapods
pod repo updateAndroid Requirements
1. Cordova android@7.0.0 or newer - To ensure compatibility with other Cordova plugins.
1. Import OneSignal Plugin
Please follow step 1A or 1B based how you build your app.
You should also remove other Push SDKs that you are not using, otherwise you may see duplicate notifications.
1A. Import from the Terminal
Run the following from your project directory.
cordova plugin add onesignal-cordova-plugin --save-- OR --
1B. Visual Studio
1. Open your project's config.xml and select Platforms. Make sure you have Cordova CLI 8.0.0 or higher.
2. Right click on config.xml and select "View Code".
3. Add the following to the file:
<vs:features>
<vs:feature>onesignal-cordova-plugin</vs:feature>
</vs:features>
2. Add required code
2.1. Add the following to the bottom of the first javascript file that loads with your app.
- This is
<project-dir>/www/js/index.jsfor most Cordova projects.
// Add to index.js or the first page that loads with your app.
// For Intel XDK and please add this to your app.js.
document.addEventListener('deviceready', function () {
// Enable to debug issues.
// window.plugins.OneSignal.setLogLevel({logLevel: 4, visualLevel: 4});
var notificationOpenedCallback = function(jsonData) {
console.log('notificationOpenedCallback: ' + JSON.stringify(jsonData));
};
window.plugins.OneSignal
.startInit("YOUR_APPID")
.handleNotificationOpened(notificationOpenedCallback)
.endInit();
}, false);2.2 Update initialization parameters
Replace YOUR_APPID with your OneSignal AppId, available in Keys & IDs
3. Android
3.1 Follow the Customize Notification Icons instructions to create a small notification icon required for Android 5.0+ devices.
4. Amazon ADM
Place your api_key.txt file into your <project-dir>/platforms/android/assets/ folder.
To create an api_key.txt for your app follow our Generate an Amazon API Key
5. iOS
5.0 Open Xcode by running xed platform/ios from the root of your project.
5.1 Select the root project and Under Capabilities Enable "Push Notifications".
5.2 Next Enable "Background Modes" and check "Remote notifications".
iOS Service Extensions
5.3 To support Action Buttons and Media Attachments on iOS 10+ please follow the Notification Service Extension guide (Only steps 1.1 to 1.6). Make sure to use Objective-C on this step then come back to this page and continue following the steps below.
5.4 Select the new OneSignalNotificationServiceExtension Target, select "Build Settings" then search for Code Signing Entitlements.
5.5 Delete both Debug and Release entries so they are blank.
5.6 Select Build Phases and expanded the"Link Binary With Libraries" section.
5.7 Press the + and add SystemConfiguration.framework and UIKit.framework.
5.8 Press the + and click Add Other...
5.9 Navigate to <Project-Root> > platforms > ios > Pods > OneSignalSDK > Framework >
Select OneSignal.framework and press Open
5.10 You should now see all 3 frameworks
5.11 Go to the Notification Service Extension's General Xcode project settings, and set the Deployment Target to be iOS 10.
iOS - Add App Groups (Optional but Recommended)
In order for your application to be able to let push notifications increment/decrement the badge count, you need to set up an App Group for your application.
Please follow this guide to set up a OneSignal app group in your app.
iOS Automatic Builds
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:
5.11 In your Xcode project, enable the Push Notifications capability (as well as any other capabilities your app needs).
5.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.
5.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>Troubleshooting
If you run into any errors see Troubleshooting Cordova Variants, our our general Troubleshooting section.
You may use an emulator but it must have an updated version of Google Play services installed.
- See our Cordova Example Project for more help.
You're Done!
Next up: Send your first push notification via the OneSignal Dashboard
What's Next
| Features Setup |
| Cordova SDK |