Step 1 - Requirements

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

❗️

Upgrade Flutter for AndroidX Support

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

Step 2 - Upgrade to the major release

In your pubspec.yaml, update the one signal flutter dependencies version

dependencies:
	onesignal_flutter: ^3.0.0

In your Podfile, update the OneSignalNotificationServiceExtension

target 'OneSignalNotificationServiceExtension' do
  pod 'OneSignalXCFramework', '>= 3.4.3', '< 4.0'
end

Install

Make sure to run flutter packages get to install the SDK.

Step 3 - Update initialization code

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

// OneSignal Initialization
var settings = {
  OSiOSSettings.autoPrompt: false,
  OSiOSSettings.promptBeforeOpeningPushUrl: true
};
OneSignal.shared
        .init("YOUR_ONESIGNAL_APP_ID", iOSSettings: settings);

With the new initialization:

// OneSignal Initialization
OneSignal.shared.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 - Flutter for a full list of new and deprecated features as well as other advanced features you may need to migrate as well.