Flutter - 3.0 API Reference


Out of Beta

This reference includes changes from version 2 to version 3, including breaking changes.

Read the following reference documentation carefully. If you are migrating from an older version, go through your existing code and cross-reference it with the changes listed in this reference to ensure a smooth migration. Make sure to make all the changes necessary and test them thoroughly.

Notable Changes:

  • Initialization is now done differently
  • Foreground notification control
  • New handlers and observer setters
  • getDeviceState to get device info

To report a bug, open a new issue in our public repo.


setAppId Function

In version 3, we are simplifying initialization. OneSignal initialization now only requires that you set the application ID.

You can call setAppId at any point in your app's flow. This allows full initialization to be delayed until say, a user logs in.

OneSignal.shared.init(appId, {OSiOSSettings.autoPrompt: true});OneSignal.shared.setAppId(appId);

New Functions

setAppId()Required: Set the OneSignal app id.
setNotificationWillShowInForegroundHandler()Set the callback to run just before displaying a notification while the app is in focus.
disablePush()Disable the push notification subscription to OneSignal.
getDeviceState()Gets information about the device.
clearOneSignalNotifications()Android Only, clear all One Signal notifications from the Notification Shade
removeNotification()Android Only, manually cancel a single OneSignal notification based on its Android notification integer ID
userProvidedPrivacyConsent()Android Only, a boolean value indicating if the user provided privacy consent

Removed Functions


In version 3, there are several functions you should remove.

Deprecated FunctionsReplacement
init()Half of the initialization process is now done for you automatically. Call setAppId to complete initialization.
getPermissionSubscriptionState()Replaced by getDeviceState()
enableVibrate()No replacement.
enableSound()No replacement.
inFocusDisplaying()Replaced by setNotificationWillShowInForegroundHandler() functionality.
setNotificationReceivedHandler()Replaced by setNotificationWillShowInForegroundHandler() functionality.

New Functions

Foreground Notification Control

In version 3, you can now specifically read notification data that will display while the app is in focus as well as change the display type dynamically. This allows developers to have even greater control over the notification experience.

Replaces inFocusDisplaying() functionality.

setNotificationWillShowInForegroundHandler Function

Runs before displaying a notification while the app is in focus. Use this handler to decide if the notification should show or not.

Note: this runs after the Notification Service Extension which can be used to modify the notification before showing it (native code).

The callback accepts a parameter OSNotification.

OneSignal.shared.setNotificationWillShowInForegroundHandler((OSNotificationReceivedEvent event) {           
      /// Display Notification, send null to not display, send notification to display           

the callback argument object has two functions:

complete()Show Notification:
Pass the notification to this function in order to display it while the app is in the foreground.

Silence Notification:
If you would like to silence the notification, call complete(null) with a null argument.
notificationRetrieves the notification object.

This returned object is of class (OSNotification).


setInAppMessageClickHandler Function

Set the callback to run on an In-App Message click.

OneSignal.shared.setInAppMessageClickedHandler((OSInAppMessageAction action) {
     print('OneSignal: IAM clicked action: ${action}');

setOnWillDisplayInAppMessageHandler Function

Set In-App message will display handler whenever the In-app message is about to be displayed

OneSignal.shared.setOnWillDisplayInAppMessageHandler((message) {
      print("OneSignal: On will display In-App message: ${message.messageId}");

setOnDidDisplayInAppMessageHandler Function

Set In-App message did display handler whenever the In-app message is displayed

OneSignal.shared.setOnDidDisplayInAppMessageHandler((message) {
      print("OneSignal: On did display In-App message: ${message.messageId}");

setOnWillDismissInAppMessageHandler Function

Set In-App message will dismiss handler whenever the In-app message is about to be dismissed

OneSignal.shared.setOnWillDismissInAppMessageHandler((message) {
      print("OneSignal: On will dismiss In-App message: ${message.messageId}");

setOnDidDismissInAppMessageHandler Function

Set In-App message did dismiss handler whenever the In-app message is dismissed

OneSignal.shared.setOnDidDismissInAppMessageHandler((message) {
      print("OneSignal: On did dismiss In-App message: ${message.messageId}");
click_nameAn optional click name entered defined by the app developer when creating the IAM.
click_url An optional URL that opens when the action takes place.
closes_message Whether tapping on the element closed the In-App Message.
first_click Whether this was the first action taken on the in app message.
outcomes Outcome for action.

Mainly useful for debugging
prompts Permission prompts.

Mainly useful for debugging
tags Tags for action.

Mainly useful for debugging
url_target Determines where the URL is opened, ie.

Mainly useful for debugging

setNotificationOpenedHandler Function

Set the callback to run on notification open/click.

        .setNotificationOpenedHandler((OSNotificationOpenedResult result) {
    print('"OneSignal: notification opened: ${result}');

openedEvent fields:

actionThe action the user took on the notification.

0) notification was clicked
1) button was clicked
notificationThe notification the user received.

Of class OSNotification


Each callback you pass to an observer adder function will receive a state change object when fired that contains two parameters: to and from. The parameters on those objects are the same between the two. This format allows for the detection of the previous state and the new state.

Example: a change in the subscription state of the device might see the isSubscribed parameter change from false to true. You can detect the change by the event.from.isSubscribed and event.to.isSubscribed objects.

setPermissionObserver Function

Add a callback that fires when the native push permission changes.

Change event parameters:

areNotificationsEnabled (Android)Whether the device-level permission is granted or denied (boolean).
hasPrompted (iOS)Did the user answer the notification permission prompt.
provisional (iOS)Is provisional push authorization enabled.
status (iOS)0 - "NotDetermined" - The user hasn't yet made a choice about whether the app is allowed to schedule notifications.

1 - "Denied" - The app isn't authorized to schedule or receive notifications.

2 - "Authorized" - The app is authorized to schedule or receive notifications.

3 - "Provisional" - The application is provisionally authorized to post noninterruptive user notifications. See iOS Customizations

4 - "Ephemeral" - For App Clips. The app is authorized to schedule or receive notifications for a limited amount of time.

setSubscriptionObserver Function

Add a callback that fires when the OneSignal subscription state changes.

Change event parameters:

userIdThe OneSignal player identifier.
pushTokenThe native push token identifier used by FCM / HMS / FireOS / APNs.
isPushDisabledIs push disabled (disablePush was called).
isSubscribed (Android)Whether the player is subscribed to OneSignal.

setEmailSubscriptionObserver Function

Add a callback that fires when the OneSignal email subscription changes.

Change event parameters:

emailAddressThe email address associated with this player record.
emailUserIdThe UUID associated with the email record.
isSubscribedWhether the associated email record is subscribed to OneSignal messaging.


OneSignal.shared.setPermissionObserver((OSPermissionStateChanges changes) {
      print("OneSignal: permission changed: ${changes.jsonRepresentation()}");

        .setSubscriptionObserver((OSSubscriptionStateChanges changes) {
      print("OneSignal: subscription changed:: ${changes.jsonRepresentation()}");

        (OSEmailSubscriptionStateChanges changes) {
      print("OneSignal: email subscription changed: ${changes.jsonRepresentation()}");

Other Functions

getDeviceState Function

(Async method) Returns an OSDeviceState object with device info.


Do not cache OSDeviceState object

This method returns a "snapshot" of the device state for when it was called. Make sure to call getDeviceState again to get the latest state.

OneSignal.shared.getDeviceState().then((deviceState) {
     print("OneSignal: device state: ${deviceState.jsonRepresentation()}");

deviceState parameters:

isSubscribedGet whether the device is subscribed to receive OneSignal push notifications.
hasNotificationPermissionGet whether notifications are enabled on the device at the app level.
This is the same value as Android's.
isPushDisabledWas push disabled with disablePush.
userIdGet the OneSignal user (player) id
pushTokenGet device's push token.
This can be one of the following depending on the device:
- Google FCM token
- Huawei HMS token
- FireOS token
emailUserIdGet the OneSignal user email id.
Only available if OneSignal.setEmail() was called.
emailAddressGet the user email address.
Only available if OneSignal.setEmail() was called.
isEmailSubscribedIs there an associated email record that is subscribed to OneSignal messaging.

disablePush Function

Use this function to opt users out of receiving all notifications through OneSignal.


clearOneSignalNotifications Function

Android Only, use this function to manually remove all OneSignal notifications from the Notification Shade.


removeNotification Function

Android Only, use this function to manually cancel a single OneSignal notification based on its Android notification integer ID. The notification identifier can be found as part of the OSNotification object.


userProvidedPrivacyConsent Function

Android Only, use this function to get a boolean value indicating if the user-provided privacy consent.

bool consent = await OneSignal.shared.userProvidedPrivacyConsent();

Other Additions / Changes

OSNotificationContains all notification properties such as title, body, additionalData, etc...

OSNotification Object

In version 4, the OSNotification class is composed of all notification properties in a single object. This is the object passed into the notificationWillShowInForeground handler.

additionalDataCustom additional data that was sent with the notification. Set on the dashboard under Options > Additional Data or with the data field on the REST API.
notificationIdThe OneSignal notification UUID.
bodyThe body text of the notification.
titleThe title text of the notification.
launchUrlThe URL opened when opening the notification.
actionButtonsThe list of action buttons on the notification.
soundThe sound resource played when the notification is shown.
rawPayloadThe raw JSON payload string received from OneSignal.
androidNotificationId (Android)The Android notification integer ID.
largeIcon (Android)The large icon set on the notification.
bigPicture (Android)The big picture image set on the notification.
smallIcon (Android)The small icon resource name set on the notification.
smallIconAccentColor (Android)The accent color shown around small notification icon on Android 5+ devices. ARGB format.
ledColor (Android)LED string. Devices that have a notification LED will blink in this color. ARGB format.
collapseId (Android)The collapse id for the notification.
priority (Android)The priority of the notification. Values range from -2 to 2 (see Android's NotificationCompat reference for more info.
fromProjectNumber (Android)The Google project number the notification was sent under.
groupKey (Android)Notifications with this same key will be grouped together as a single summary notification.
groupMessage (Android)The summary text displayed in the summary notification.
lockScreenVisibility (Android)Privacy setting for how the notification should be shown on the lockscreen of Android 5+ devices.

1 (Default) - Public (fully visible)
0 - Private (Contents are hidden)
-1 - Secret (not shown).
badge (iOS)The badge number assigned to the application icon.
category (iOS)Notification category key previously registered to display with.
threadId (iOS)iOS 10+ only. Groups notifications into threads.
subtitle (iOS)The message subtitle.
attachments (iOS)iOS 10+ only. Attachments sent as part of the rich notification.
templateId (iOS)Unique Template Identifier.
templateName (iOS)Name of Template.
mutableContent (iOS)True when the key mutable-content is set to 1 in the APNS payload.

See Apple's documentation for more details.
badgeIncrement (iOS)The amount to increment the badge icon number.
contentAvailable (iOS)True when the key content-available is set to 1 in the APNS payload. Used to wake your app when the payload is received.

See Apple's documentation for more details.