PhoneGap SDK Setup

❗️

PhoneGap / PhoneGap Build (PGB) Deprecated

PhoneGap is no longer being support by Adobe and PhoneGap Build (PGB) servers are shutting down October 1, 2020.
https://blog.phonegap.com/update-for-customers-using-phonegap-and-phonegap-build-cc701c77502c

We recommend migrating to Ionic, Capacitator or Cordova.

📘

Looking for Ionic or Cordova setup?

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

Required For Setup

• A OneSignal account if you do not already have one
• Your OneSignal App ID, available in Settings > Keys & IDs in the OneSignal dashboard
• 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.
• PhoneGap CLI users 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.

Updating SDK

If you already have a PhoneGap app running OneSignal, , you can run this command to ensure that you are on the latest version of the onesignal-cordova-plugin:

phonegap plugin update onesignal-cordova-plugin

Setup SDK

Generate Credentials

While 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 after completing Step 5 below.
• Android - Generate a Google Server API Key
• Amazon - Generate an Amazon API Key

1. Import OneSignal Plugin

Please follow either Option A or Option B based on which PhoneGap version you use to build your app.

You should also remove any other push SDKs that you are not using – otherwise, you may see duplicate notifications being sent to your users.

Option A. PhoneGap CLI

Run the following from your project directory:

phonegap plugin add onesignal-cordova-plugin --save

Option B. 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. For example:

<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 () {
  //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);
  });
  
}, false);

2.2 Update initialization parameters

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

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

Optional - Follow the PhoneGap SDK reference to handle when users tap on and open notifications 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 guide.

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.

Add App Groups (Recommended)

In order for your application to use Confirmed Deliveries and increment/decrement Badges through push notifications, you need to set up an App Group for your application.

Please follow the iOS SDK App Groups setup guide to add the 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, and 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 Click the + and add SystemConfiguration.framework and UIKit.framework.

5.8 Click the + and click Add Other...

5.9 Navigate to > platforms > ios > Pods > OneSignalSDK > Framework >
Select OneSignal.framework and press Open

5.10 You should now see all 3 frameworks listed:

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

This setup does NOT work with the PhoneGap Developer App.