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

Ionic SDK Setup

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

For Developers

Required For Setup

  • A OneSignal Account if you do not already have one
  • Your OneSignal App ID, available in Keys & IDs
  • Cordova 8.0.0 or newer - You should also remove other Push SDKs that you are not using, otherwise you may see duplicate notifications.
  • 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

Xcode 10 Notice

Cordova is currently incompatible with Xcode 10's new build system. For a workaround, please see this post

Because of changes to Xcode's build process, this results in the embedded.mobileprovision file not being attached to your app bundle. This breaks push notifications - it will cause Mismatched User errors.

Update SDK

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

ionic cordova plugin remove onesignal-cordova-plugin
ionic cordova plugin add onesignal-cordova-plugin

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

Setup SDK

Generate Credentials

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

OneSignal supports Ionic 1 through 3.

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.

  • IonicPro Package can skip to step 1.
sudo gem install cocoapods
pod repo update

Android Requirements

1. Cordova android@7.0.0 or newer - To ensure compatibility with other Cordova plugins.

1. Import from the Terminal

Run the following from your project directory.

ionic cordova plugin add onesignal-cordova-plugin --save
ionic plugin add onesignal-cordova-plugin --save
ionic cordova plugin add onesignal-cordova-plugin --save

2. Add required code

Optionally you can use the the OneSignal Typescript Ionic Native wrapper instead of following the step 2 instructions below.

2.1 If you are using the basic Ionic starter project add the following to your <project-dir>/src/app/app.component.ts. (or .js if you are using plain javascript)

// Add the following to your existing ready fuction.

constructor(platform: Platform, statusBar: StatusBar, splashScreen: SplashScreen) {
  platform.ready().then(() => {

    // OneSignal Code start:
    // Enable to debug issues:
    // window["plugins"].OneSignal.setLogLevel({logLevel: 4, visualLevel: 4});

    var notificationOpenedCallback = function(jsonData) {
      console.log('notificationOpenedCallback: ' + JSON.stringify(jsonData));

// Add the following to your existing ready fuction.

.run(function($ionicPlatform) {
  $ionicPlatform.ready(function() {
    // Enable to debug issues.
  // window.plugins.OneSignal.setLogLevel({logLevel: 4, visualLevel: 4});
  var notificationOpenedCallback = function(jsonData) {
    console.log('notificationOpenedCallback: ' + JSON.stringify(jsonData));


2.2 Update initialization parameters

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

3. Android

3.1 Follow the Custom Notification Icons instructions below 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 - Part 1 (Required)

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)

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


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

You're Done!

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