OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

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


Beta Period

Currently, the OneSignal Flutter 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 Flutter SDK Setup Guide

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 Beta

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

    onesignal_flutter: ^3.0.0-beta1


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
        .init("YOUR_ONESIGNAL_APP_ID", iOSSettings: settings);

With the new initialization:

// OneSignal Initialization

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



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.

Step 5 - Review Full List

:white-check-mark: 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.

Updated 2 months ago

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

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.