📘

This reference covers version 3.0.0+ of the Flutter SDK

For the old reference, click here.

Coming from version 2? See full changes in version 3 in our Migration Guide.

📘

Just starting with Flutter?

Check out our Flutter SDK Setup guide.

Initialization

setAppId Function

To initialize, simply set the OneSignal 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.setAppId(appId);

Foreground Notification Control

You can 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 argument is a notification received event object.

OneSignal.shared.setNotificationWillShowInForegroundHandler(notifReceivedEvent => {
    console.log("OneSignal: notification will show in foreground:", notifReceivedEvent);
    let notif = notifReceivedEvent.getNotification();
    setTimeout(() => notifReceivedEvent.complete(notif), 0);
});

The callback argument object has two functions:

Handlers

setInAppMessageClickHandler Function

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

OneSignal.shared.setInAppMessageClickHandler(event => {
    console.log("OneSignal IAM clicked:", event);
});

Click event parameters:

setNotificationOpenedHandler Function

Set the callback to run on notification open/click.

OneSignal.shared.setNotificationOpenedHandler(openedEvent => {
    console.log("OneSignal: notification opened:", openedEvent);
  const { action, notification } = openedEvent;
});

Opened event parameters:

Observers

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.

Important: as designated by the "add" prefix to these functions, it is possible to add multiple callbacks to the same event. The callbacks will then fire independently when the event occurs. (Related: see clearHandlers function).

setPermissionObserver Function

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

Change event parameters:

setSubscriptionObserver Function

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

Change event parameters:

setEmailSubscriptionObserver Function

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

Change event parameters:

Example

OneSignal.shared.setPermissionObserver((OSPermissionStateChanges changes) {
    console.log("OneSignal: permission changed:", event);
});

OneSignal.shared.setSubscriptionObserver((OSSubscriptionStateChanges changes) {
    console.log("OneSignal: subscription changed:", event);
});

OneSignal.shared.setEmailSubscriptionObserver((OSEmailSubscriptionStateChanges changes) {
    console.log("OneSignal: email subscription changed: ", event);
});

Other Functions

getDeviceState Function

ASYNC
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("DeviceState: ${deviceState?.jsonRepresentation()}");
});

deviceState parameters:

disablePush Function

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

OneSignal.shared.disablePush(true);

clearHandlers Function

Clears all handlers and observers.

📘

While this function clears both handlers AND observers, it is mainly useful for the observers since multiple observers can be added to a single event. React Native hot-reloading can lead to the buildup of these observers while in the dev environment which will result in multiple firings of the given callbacks. To avoid this, call in componentWillUnmount().

OSNotification

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.

Privacy

userProvidedPrivacyConsent Function

Whether the user has provided privacy consent (if required).

Clear Notifications (Android Only)

clearOneSignalNotifications Function

Removes all OneSignal notifications from the Notification Shade.

// Calling clearOneSignalNotifications
OneSignal.shared.clearOneSignalNotifications();

Remove Notifications (Android Only)

removeNotification Function

This function is used to remove a notification from the Android shade by supplying the Android notification identifier. The notification identifier can be found as part of the OSNotification object.

// Calling removeNotification
OneSignal.shared.removeNotification(id);

Troubleshooting

Troubleshooting the Flutter SDK