OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Support

PhoneGap SDK Setup

OneSignal PhoneGap SDK Setup Guide. Works with iOS, Android (and derivatives like Amazon) and Windows Phone 8.1.

For Developers

Update SDK

If you already have an app with the PhoneGap SDK, you can run this to ensure your SDK is on the latest version:

phonegap plugin update onesignal-cordova-plugin

If you have not set up an app yet, follow the instructions below.

Setup SDK

Generate Credentials

Before setting up the PhoneGap 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

Windows Phone 8.1 - Generate a Windows Phone Package SID and Secret

1. Import OneSignal Plugin

Please follow step 1A or 1B based which PhoneGap version you use to build your app.

You should also remove other Push SDKs that you are not using, otherwise you may see duplicate notifications.

1A. PhoneGap CLI

Run the following from your project directory.

phonegap plugin add onesignal-cordova-plugin

-- OR --

1B. PhoneGap Build (PGB)

Add the following lines to <project-dir>/www/config.xml

<gap:plugin name="onesignal-cordova-plugin" spec="^2.0.10" source="npm" />

<!--Requires cli-5.1.1+ for gradle Android but we recommend using the latest version. -->
<preference name="phonegap-version" value="cli-6.4.0" />
<preference name="android-build-tool" value="gradle" />

<!-- Window Phone 8.1 builds must use cli-6.1.0+ above -->
<preference name="windows-appx-target" value="8.1-phone" />
<preference name="WindowsToastCapable" value="true" />
<gap:plugin name="onesignal-cordova-plugin-pgb-compat" source="npm" />
<gap:plugin name="cordova-plugin-googleplayservices" source="npm" />
<gap:plugin name="cordova-plugin-android-support-v4" source="npm" />

2. Add required code

2.1. Add the following to the first javascript file that loads with your app.

  • This is <project-dir>/www/js/index.js for most PhoneGap 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));

  // Call syncHashedEmail anywhere in your app if you have the user's email.
  // This improves the effectiveness of OneSignal's "best-time" notification scheduling feature.
  // window.plugins.OneSignal.syncHashedEmail(userEmail);
}, false);

2.2 Update initialization parameters

Replace YOUR_APPID with your OneSignal AppId, available in Keys & IDs

Recommended - Change inFocusDisplaying to None when app is ready for launch. See PhoneGap SDK Reference for instructions.

Optional - follow the PhoneGap SDK reference to add code for when users tap on and open notifications to your liking by using the chaining methods handleNotificationReceived and handleNotificationOpened.

3. Android

Skip this section if you use PhoneGap Build

3.1 Open the Android SDK Manager.

3.2 Make sure to install and update the following under Extras:

  • Android Support Repository
  • Google Repository

3.3 Follow the Customize Notification Icons instructions to create a small notification icon required for Android 5.0+ devices.

4. Amazon ADM

Skip this section if you use PhoneGap Build

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.1 No extra steps, you're all set if you already setup your provisioning profile and push certificate.

6. Windows Phone 8.1 (WP8.1)

Skip this section if you use PhoneGap Build

Your app does not have to be published however, you must have it created on the Windows Dev Center. Follow our Windows Phone Project SID & Secret setup if you have not done this yet.

6.1 Run phonegap build windows and open the .sln in <project-root>/platforms/windows/

6.2 Under the Windows Phone 8.1 project double click on Package.appxmanifest then select the "Application" tab and scroll down to the "Notifications:" section. Change "Toast capable:" to Yes.

6.3 Right click on your VS project and select Store>Associate App with the Store...

6.4 Click Next and sign into your Microsoft account.

6.5 Select your app and press Next.

6.6. Lastly press Associate.


If you run into any errors see Troubleshooting Cordova Variants, our our general Troubleshooting section.

Push Notification Testing Requirements

  • iOS - Must test on a real device, Simulator does not support Apple push notifications.
  • Android
    • You MUST build and install your app's APK.
    • You may use an emulator but it must have an updated version of Google Play services installed.
  • Does NOT work with the PhoneGap Developer App.


Check out our PhoneGap SDK for more OneSignal functions.

PhoneGap SDK Setup

OneSignal PhoneGap SDK Setup Guide. Works with iOS, Android (and derivatives like Amazon) and Windows Phone 8.1.

For Developers