Step-by-Step Cordova 2.x to 3.0.0 Upgrade Guide

🚧

Beta Period

Currently, the OneSignal Cordova 3.x is in beta. Please try it out and give us feedback via Github!
If you wish to set up the mainline SDK follow our Cordova SDK Setup Guide

Step 1 - Requirements

This guide assumes you already have set up the OneSignal-Cordova-SDK 2.x.x and are migrating your app to the 3.x Major version.

❗️

Upgrade Cordova for AndroidX Support

AndroidX is a new requirement to use the new OneSignal-Cordova 3.x SDK.
If your project is not already migrated, please migrate it. Learn more

Step 2 - Upgrade to the Beta

You will need to remove the plugin and add it again

cordova plugin rm onesignal-cordova-plugin

cordova plugin add [email protected] --save

Step 3 - Update initialization code

3.1 Open your main file (e.g: index.js)
3.2 Replace the following

// OneSignal Initialization
 var iosSettings = {};
iosSettings["kOSSettingsKeyAutoPrompt"] = false;
iosSettings["kOSSettingsKeyInAppLaunchURL"] = false;
               
window.plugins.OneSignal
  .startInit("YOUR_ONESIGNAL_APP_ID")
  .inFocusDisplaying(window.plugins.OneSignal.OSInFocusDisplayOption.Notification)
  .iOSSettings(iosSettings)
  .endInit();

With the new initialization:

// OneSignal Initialization
window.plugins.OneSignal.setAppId("YOUR_ONESIGNAL_APP_ID");

For any iOS settings, you had previously, note that:

  • OSiOSSettings.autoPrompt is deprecated. If you omitted this previously or set it to true, you will now need to prompt the user by calling promptForPushNotificationsWithUserResponse().
  • OSiOSSettings.inAppLaunchUrl is deprecated. There is currently no replacement for it.
  • OSiOSSettings.inFocusDisplayOption is replaced by adding a NotificationWillShowInForegroundHandler (see below).

3.3 Review your existing inFocusDisplaying() usage.

  • This was most likely set to OSNotificationDisplayType.notification which means no additional changes need as this is the default in 3.x. Simply remove the function call.
  • If you didn't have inFocusDisplaying at all in your code or this was set to OSNotificationDisplayType.none the replacement for this is adding a NotificationWillShowInForegroundHandler.

Step 4 - Update Event Listeners

If you have event-listeners set up, you will need to switch to use the new handlers & observer setter functions.

See handlers & observers reference for more details.

version 2.0+ event string

version 3.0+ event handler / observer

setNotificationReceivedHandler

setNotificationWillShowInForegroundHandler()

The equivalent of the "received" event listener is the new NotificationWillShowInForegroundHandler. You can use this to have better notification foreground control as well as get notification-specific data before it is displayed to the user while the app is in focus.

handleNotificationOpened

setNotificationOpenedHandler()

handleInAppMessageClicked

setInAppMessageClickHandler()

Step 5 - Review Full List

:white-check-mark: You're set up with the new SDK!
Please review the full 3.0 API Reference - Cordova for a full list of new and deprecated features as well as other advanced features you may need to migrate as well.


Did this page help you?