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

2.1 Remove the OneSignal plugin and add it again to upgrade

cordova plugin rm onesignal-cordova-plugin

cordova plugin add onesignal-cordova-plugin --save

2.2 iOS Only - Clear Xcode DerivedData to prevent any issues caused by cached build files.

rm -rf ~/Library/Developer/Xcode/DerivedData/*

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.

Step 5. Review Full List

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