Flutter SDK 2.x.x

📘

Just Starting with Flutter?

Check out our Flutter SDK Setup Guide

Initialization

OSiOSSettings

Enum

Describes different settings you can use when initializing iOS. Please note that these settings are ignored in Android.

Handling Notifications

setNotificationReceivedHandler

This function/callback will be called whenever your application receives a notification from OneSignal when the app is in the foreground.

OneSignal.shared.setNotificationReceivedHandler((OSNotification notification) {
  // a notification has been received
});

setNotificationOpenedHandler

This function/callback will be called whenever a user taps on a OneSignal push notification from your application.

If your application was closed and the user taps a notification, the app will launch, and the SDK will call this handler.

OneSignal.shared.setNotificationOpenedHandler((OSNotificationOpenedResult result) {
  // a notification has been opened
});

postNotification

Allows you to post a notification. To send a notification, you build a custom OSCreateNotification object with the various properties.

Please note that you must specify at least one OneSignal user ID that the notification should be sent to, using the playerIds property.

var status = await OneSignal.shared.getPermissionSubscriptionState();

var playerId = status.subscriptionStatus.userId;

await OneSignal.shared.postNotification(OSCreateNotification(
  playerIds: [playerId],
  content: "this is a test from OneSignal's Flutter SDK",
  heading: "Test Notification",
  buttons: [
    OSActionButton(text: "test1", id: "id1"),
    OSActionButton(text: "test2", id: "id2")
  ]
));

You can also send a silent notification (which will not alert the user in any way):

var status = await OneSignal.shared.getPermissionSubscriptionState();

var playerId = status.subscriptionStatus.userId;

await OneSignal.shared.postNotification(OSCreateNotification.silentNotification(
  playerIds: [playerId],
  additionalData: {
    'test' : 'value'
  }
));

postNotificationWithJson

You can also manually build up notification JSON and send it with this method instead of using the OSCreateNotification class:

var status = await OneSignal.shared.getPermissionSubscriptionState();

var playerId = status.subscriptionStatus.userId;

var response = await OneSignal.shared.postNotificationWithJson({
  "include_player_ids" : [ playerId],
  "contents" : {"en" : "test notification"}
});

inFocusDisplayType

Gets setting on how notifications will be shown when the app is in focus.

OneSignal.shared.inFocusDisplayType;

External User ID's

setExternalUserId

If your system assigns unique identifiers to users, it can be annoying to have to also remember their OneSignal user ID's as well. To make things easier, OneSignal now allows you to set an external_id for your users. Simply call this method, pass in your custom user ID (as a string), and from now on when you send a push notification, you can use include_external_user_ids instead of include_player_ids.

var myCustomUniqueUserId = "something from my backend server";

OneSignal.shared.setExternalUserId(myCustomUniqueUserId);

removeExternalUserId

If your user logs out of your app and you would like to disassociate their custom user ID from your system with their OneSignal user ID, you will want to call this method.

//usually called after the user logs out of your app
OneSignal.shared.removeExternalUserId()

Objects

OSSubscriptionState

The subscription state contains information about the user's push notification subscription with OneSignal. For example, when the user first launches your app and gets registered with OneSignal, the subscription state will change. It contains properties such as the push token and OneSignal user ID.

OSEmailSubscriptionState

Represents the user's email subscription state with OneSignal.

OSPermissionState

Represents the permission state for push notifications. For example, in iOS, if the user taps 'Allow' on the push notification permission prompt, their OSPermissionState will change.

OSSubscriptionStateChanges

Represents a change in the user's subscription state. For example, if the user first installs and opens your app, when they become registered with OneSignal, the subscription state will change to account for the new userId.

OSEmailSubscriptionStateChanges

Represents a change in the user's email subscription state. For example, if your user enters their email address and your app calls setEmail(), the SDK will update OneSignal's server and will assign the user a new emailUserId. This will change the user's email subscription state.

OSPermissionStateChanges

Represents a change in the user's email permission state. For example, if an iOS user taps Allow on the push notification permission prompt, the permission state will go from notDetermined to allowed.

OSNotification

This class represents a push notification that the user has received in your app from OneSignal.

OSNotificationPayload

This class represents all of the various properties that control how a notification looks, such as the title, subtitle, etc.

OSCreateNotification

This class represents a notification that will be created and sent by your application. Because the properties and format involved in creating a push notification are so different from the platform-dependent properties in receiving a notification (ie. from APNS or GCM), we have split this logic into it's own separate class.

OSNotificationOpenedResult

Describes the opening of a notification.

OSNotificationAction

Describes an action taken on a push notification (ie. tapping a button).

OSActionButton

This class represents a button added to a push notification.

OSAndroidBackgroundImageLayout

This class represents the background image layout used for push notifications that show a background image.

Enumerations

OSNotificationDisplayType

Represents the different ways a notification can be displayed.

OSNotificationActionType

Describes an action taken on a notification, such as tapping a button.

OSNotificationPermission

Describes the different types of permissions in regards to push notifications.

OSCreateNotificationBadgeType

Describes what happens when a push notification with a badge is received.

OSCreateNotificationDelayOption

Describes the different ways to delay a notification.