📘

Looking for Ionic or PhoneGap setup?

See our Ionic SDK Setup or PhoneGap SDK Setup if you are using those frameworks directly.

Step 1 - Requirements

📘

Before getting started, try out the Example Project

For your convenience, we've created an example project that you can use to get started and learn about using OneSignal with Cordova.

• Create A OneSignal Account if you do not already have one

• Your OneSignal App ID, available in Settings > Keys & IDs in the OneSignal dashboard

Before setting up the Cordova SDK, you must generate the appropriate credentials for the platform(s) you are releasing on:

iOS Requirements

• 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.

• You MUST have a Mac with Xcode version 10 or greater. Xcode 10 Notice: To prevent Mismatched User errors, be sure you're using version 5.0.0 or greater of cordova-ios.

• An iOS Push Certificate. Generate one here using our Provisionator tool.

• CocoaPods - Install with the following from the Terminal:

sudo gem install cocoapods
pod repo update

Android Requirements

• Cordova [email protected] or newer - Use this version at a minimum to ensure compatibility with other Cordova plugins.

• A Google/Firebase Server API Key

• An Android 4.0.3 or newer device or emulator with "Google Play services" installed.

• Android Studio

Step 2 - Import OneSignal Plugin

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

Step 3 - Add Required Code

3.0 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.

receivedEvent: function(id) {
  //START ONESIGNAL CODE
  //Remove this method to stop OneSignal Debugging 
  window.plugins.OneSignal.setLogLevel({logLevel: 6, visualLevel: 0});
  
  var notificationOpenedCallback = function(jsonData) {
    console.log('notificationOpenedCallback: ' + JSON.stringify(jsonData));
  };
  // Set your iOS Settings
  var iosSettings = {};
  iosSettings["kOSSettingsKeyAutoPrompt"] = false;
  iosSettings["kOSSettingsKeyInAppLaunchURL"] = false;
  
  window.plugins.OneSignal
    .startInit("YOUR_ONESIGNAL_APP_ID")
    .handleNotificationOpened(notificationOpenedCallback)
    .iOSSettings(iosSettings)
    .inFocusDisplaying(window.plugins.OneSignal.OSInFocusDisplayOption.Notification)
    .endInit();
  
  // The promptForPushNotificationsWithUserResponse function will show the iOS push notification prompt. We recommend removing the following code and instead using an In-App Message to prompt for notification permission (See step 6)
  window.plugins.OneSignal.promptForPushNotificationsWithUserResponse(function(accepted) {
    console.log("User accepted notifications: " + accepted);
  });
  //END ONESIGNAL CODE
}

3.1 Update initialization parameters. Replace YOUR_APPID with your OneSignal App Id, available in the OneSignal dashboard under Settings > Keys & IDs.

📘

Amazon ADM Apps

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.

Step 4 - iOS Setup (Skip if your app is Android-only)

4.0 In /platforms/ios Open the .wcworkspace project in Xcode.
4.1 Select the root project, and under Signing & Capabilities, enable Push Notifications.
4.2 Next, enable Background Modes and check Remote 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.3 Please follow the Notification Service Extension guide (only Steps 2). Make sure to use Objective-C in this step, then come back to this page and continue following the steps below.

4.4 Select the new OneSignalNotificationServiceExtension Target, select Build Settings, then search for Code Signing Entitlements.

4.5 Delete both Debug and Release entries so they are blank.

4.6 Select Build Phases and expanded the"Link Binary With Libraries" section. Press the + and add the following frameworks:

• SystemConfiguration.framework
• UIKit.framework.
• CoreGraphics.framework
• WebKit.framework

4.7 Press the + and click Add Other... > Add Files

4.8 Navigate to > platforms > ios > Pods > OneSignal > iOS_SDK > OneSignalSDK > Framework > Select OneSignal.framework and click Open

4.9 You should now see all 5 frameworks listed.

4.10 Go to the Notification Service Extension's General Xcode project settings, and set the Deployment Target to be iOS 10 if you have not done so already.

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>

Step 5 - Prompt Your Users to Subscribe (Recommended for iOS)

Apple's Human Interface Guidelines recommend 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 an easy option for a "soft-prompt" using 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 can no longer be shown in your app if the user clicks deny.

See our iOS Push Opt-In Prompt for details on implementing this.

Troubleshooting

If you run into any errors, see Troubleshooting Cordova Variants, or 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.