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    Discussions

PhoneGap SDK Setup

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

Xcode 10 Notice - PhoneGap CLI

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 - PhoneGap CLI users MUST have a Mac with a new version of Xcode

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

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 --save

-- OR --

1B. PhoneGap Build (PGB)

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

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

<!-- Requires cli-8.0.0 but we recommend using the latest version. -->
<preference name="phonegap-version" value="cli-8.0.0" />

<preference name="android-build-tool" value="gradle" />
<preference name="android-minSdkVersion" value="15" />

<!-- Can omit if not targetting Windows Phone -->
<preference name="windows-appx-target" value="8.1-phone" />
<preference name="WindowsToastCapable" value="true" />

Update to PhoneGap CLI 8.0.0

Please update to PhoneGap CLI-8.0.0 or newer to ensure there are no conflicts with other plugins. Ensure you have only phonegap-version entry in your config.xml and it is up to date.
<preference name="phonegap-version" value="cli-8.0.0" />

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));

}, 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

3.1 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 - Part 1 (CLI ONLY)

5.0 Open <project-root>/platform/ios/YourAppName.xcworkspace
5.1 Select the root project and Under Capabilities Enable "Push Notifications".
5.2 Next Enable "Background Modes" and check "Remote notifications".

iOS - Add App Groups (Optional but Recommended) (CLI ONLY)

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.

5. iOS - Part 2 (Recommend) (CLI ONLY)

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.5). 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


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

Does NOT work with the PhoneGap Developer App.

You're Done!

Next up: Send your first push notification via the OneSignal Dashboard

Updated 12 days ago

PhoneGap SDK Setup

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

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.