Comprehensive API reference for the OneSignal Mobile SDK, including initialization, user identity, subscriptions, tags, permissions, in-app messages, live activities, and more. Supports Android, iOS, Unity, React Native, Flutter, and Cordova/Ionic platforms.
Set the logging to print additional logs to Android LogCat or Xcode logs.
Call this before initializing OneSignal. See Getting a Debug Log for more details.Log levels (least to most verbose): None | Fatal | Error | Warn | Info | Debug | Verbose. Cordova/Ionic uses integers 0–6.
When users open your app, OneSignal automatically creates a OneSignal ID (User-level ID ID) and a Subscription ID (device-level ID). You can associate multiple Subscriptions (e.g., devices, emails, phone numbers) with a single user by calling login() with your unique user identifier.
Links the current device (mobile Subscription) to a known user identified external_id. Call this only for identified users (after sign-in or session restore). For anonymous users, rely on the automatically assigned onesignal_id (see User State addObserver()).If the external_id already exists: the SDK switches to the existing user, links the current mobile Subscription to it, and discards any anonymous data (tags, session data, email/SMS Subscriptions). A 409 Conflict log is expected and can be ignored.If the external_id does not exist: a new user is created with the current onesignal_id, retaining all anonymous data.
The SDK retries automatically on network failures. Call login(external_id)every time the app starts once the user’s ID is known, and again on account switches.
Returns the current user-level onesignal_id from local device storage. It may return null before the SDK finishes initializing; use the User State addObserver() instead to reliably get the onesignal_id and react to changes.
Do not persist the OneSignal ID as a permanent user identifier. It can change when users log in, log out, or switch accounts.
Returns the current user-level external_id from local device storage. It may return null if not set via the login method or called before user state is initialized.
OneSignal.User.addObserver((state) { var userState = state.jsonRepresentation(); print('OneSignal user changed: $userState');});/// Remove a user state observer that has been previously added.OneSignal.User.removeObserver(observer);
Aliases are alternative identifiers (like usernames or CRM IDs). Set external_id with login() before adding aliases. Aliases added without an external_id will not sync across multiple Subscriptions.
// Add a single aliasOneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID")// Add multiple aliasesvar aliases = mapOf("ALIAS_LABEL_01" to "ALIAS_ID_01", "ALIAS_LABEL_02" to "ALIAS_ID_02")OneSignal.User.addAliases(aliases)// Remove a single aliasOneSignal.User.removeAlias("ALIAS_LABEL")// Remove multiple aliasesOneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02"])
// Add a single aliasOneSignal.getUser().addAlias("ALIAS_LABEL", "ALIAS_ID");// Add multiple aliasesHashMap<String, String> aliases = new HashMap<String, String>();aliases.put("ALIAS_LABEL_01", "ALIAS_ID_01");aliases.put("ALIAS_LABEL_02", "ALIAS_ID_02");OneSignal.getUser().addAliases(aliases);// Remove a single aliasOneSignal.getUser().removeAlias("ALIAS_LABEL")// Remove multiple aliasesHashSet<String> labels = new HashSet<String>();labels.add("ALIAS_LABEL_01");labels.add("ALIAS_LABEL_02");OneSignal.getUser().removeAliases(labels);
// Add a single aliasOneSignal.User.addAlias(label: "ALIAS_LABEL", id: "ALIAS_ID")// Add multiple aliasesOneSignal.User.addAliases(["ALIAS_LABEL_01": "ALIAS_ID_01", "ALIAS_LABEL_02": "ALIAS_ID_02"])// Remove a single aliasOneSignal.User.removeAlias("ALIAS_LABEL")// Remove multiple aliasesOneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02"])
// Add a single alias[OneSignal.User addAliasWithLabel:@"ALIAS_LABEL" id:@"ALIAS_ID"];// Add multiple aliases[OneSignal.User addAliases:@{@"ALIAS_LABEL_01": @"ALIAS_ID_01", @"ALIAS_LABEL_02": @"ALIAS_ID_02"}]// Remove a single alias[OneSignal.User removeAlias:@"ALIAS_LABEL"]// Remove multiple aliases[OneSignal.User removeAliases:@[@"ALIAS_LABEL_01", @"ALIAS_LABEL_02"]]
// Add a single aliasOneSignal.User.AddAlias("ALIAS_LABEL", "ALIAS_ID");// Add multiple aliasesOneSignal.User.AddAliases(new Dictionary<string, string> { { "ALIAS_LABEL_01", "ALIAS_ID_01" }, { "ALIAS_LABEL_02", "ALIAS_ID_02" }});// Remove a single aliasOneSignal.User.RemoveAlias("ALIAS_LABEL");// Remove multiple aliasesOneSignal.User.RemoveAliases(new[] {"ALIAS_LABEL_01", "ALIAS_LABEL_02"});
// Add a single aliasOneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID");// Add multiple aliasesOneSignal.User.addAliases({ALIAS_LABEL_01: "ALIAS_ID_01", ALIAS_LABEL_02: "ALIAS_ID_02"});// Remove a single aliasOneSignal.User.removeAlias("ALIAS_LABEL");// Remove multiple aliasesOneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02"]);
// Add a single aliasOneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID");// Add multiple aliasesvar aliases = <String, String>{ "alias_key_1": "alias_id_1", "alias_key_2": "alias_id_2"};OneSignal.User.addAliases(aliases);// Remove a single aliasOneSignal.User.removeAlias("ALIAS_LABEL");// Remove multiple aliasesvar aliases = <String>["alias_key_1", "alias_key_2"];OneSignal.User.removeAliases(aliases);
// Add a single alias - IonicOneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID");// Add a single alias - Cordovawindow.plugins.OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID");// Add multiple aliases - IonicOneSignal.User.addAliases({ALIAS_LABEL_01: "ALIAS_ID_01", ALIAS_LABEL_02: "ALIAS_ID_02"});// Add multiple aliases - Cordovawindow.plugins.OneSignal.User.addAliases({ALIAS_LABEL_01: "ALIAS_ID_01", ALIAS_LABEL_02: "ALIAS_ID_02"});// Remove a single alias - IonicOneSignal.User.removeAlias("ALIAS_LABEL");// Remove a single alias - Cordovawindow.plugins.OneSignal.User.removeAlias("ALIAS_LABEL");// Remove multiple aliases - IonicOneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02"]);// Remove multiple aliases - Cordovawindow.plugins.OneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02"]);
Track user actions with associated properties. See Custom Events for more details.
Custom events require the following minimum SDK versions: iOS 5.4.0, Android 5.6.1, React Native 5.3.0, Flutter 5.4.0, Unity 5.2.0.
Track and send a custom event performed by the current user.
name - Required. The name of the event as a string.
properties - Optional. Key-value pairs to add to the event. The properties dictionary or map must be serializable into a valid JSON Object. Supports nested values.
The SDK automatically includes app-specific data under the reserved os_sdk key in the properties payload (e.g., os_sdk.device_type).
OneSignal.User.trackEvent("my_event_name")OneSignal.User.trackEvent( name = "started_free_trial", properties = mapOf( "promo_code" to "NEW50", "membership_details" to mapOf( "vip" to true, "products_viewed_count" to 15 ) ))
OneSignal.getUser().trackEvent("my_event_name", null);Map<String, Object> membershipDetails = new HashMap<>();membershipDetails.put("vip", true);membershipDetails.put("products_viewed_count", 15);Map<String, Object> properties = new HashMap<>();properties.put("promo_code", "NEW50");properties.put("membership_details", membershipDetails);OneSignal.getUser().trackEvent("started_free_trial", properties);
Grants or revokes user consent for data collection. Without consent, no data is sent to OneSignal and no subscription is created.
If setConsentRequired() is true, our SDK will not be fully enabled until setConsentGiven is called with true.
If setConsentGiven is set to true and a Subscription is created, then later it is set to false, that Subscription will no longer receive updates. The current data for that Subscription remains unchanged until setConsentGiven is set to true again.
LocationManager.startGetLocation: not possible, no location dependency found
Check your App’s dependencies. A common solutions is in you app/build.gradle add: implementation 'com.google.android.gms:play-services-location:21.0.1'
Enable your app to share location with OneSignal using the Location.setShared() method.
Request permission from the user for location tracking with the Location.requestPermission method or use in-app messages.
A Subscription represents a single messaging channel instance (for example, a mobile device) and has a unique Subscription ID (OneSignal’s device-level ID). A user can have multiple Subscriptions across devices and platforms.See Subscriptions for more details.
Returns the current device-level subscription_id from local device storage. It may return null before the SDK finishes initializing; use the Push Subscription addObserver() instead to reliably get the subscription_id and react to changes.
val subscriptionId = OneSignal.User.pushSubscription.id
Returns the current device-level push subscription token from local device storage. It may return null before the SDK finishes initializing or the token isn’t available yet; use the Push Subscription addObserver() instead to reliably get the token and react to changes.
val pushToken = OneSignal.User.pushSubscription.token
Use this method to respond to mobile Subscription changes like:
The device receives a new push token from Google (FCM) or Apple (APNs)
OneSignal assigns a subscription ID
The optedIn value changes (e.g. called optIn() or optOut())
The user toggles push permission in system settings, then opens the app
When this happens, the SDK triggers the onPushSubscriptionChange event. Your listener receives a state object with the previous and current values so you can detect exactly what changed.To stop listening for updates, call the associated removeObserver() or removeEventListener() method.
class MyObserver : IPushSubscriptionObserver { init { OneSignal.User.pushSubscription.addObserver(this) } override fun onPushSubscriptionChange(state: PushSubscriptionChangedState) { if (state.current.optedIn) { println("User is now opted-in with push token: ${state.current.token}") } }}// Remove the observerOneSignal.User.pushSubscription.removeObserver(this)
OneSignal.User.pushSubscription.addObserver((state) { if (state.current.optedIn) { /// respond to new state }});// Removes the previously added observerOneSignal.User.pushSubscription.removeObserver(myObserver);
const listener = (event: PushSubscriptionChangedState) => { console.log("Push subscription changed: " + (event));};// Add the listener - IonicOneSignal.User.pushSubscription.addEventListener("change", listener);// Remove the listener - IonicOneSignal.User.pushSubscription.removeEventListener("change", listener);// Add the listener - Cordovawindow.plugins.OneSignal.User.pushSubscription.addEventListener("change", listener);// Remove the listener - Cordovawindow.plugins.OneSignal.User.pushSubscription.removeEventListener("change", listener);
Control the subscription status (subscribed or unsubscribed) of the current mobile Subscription within your app. Common use cases:
Call optOut() after logout() to prevent push from being sent to users that log out. Call optIn() to resume push notifications.
Implement a notification preference center within your app.
optOut(): Sets the current push subscription status to unsubscribed (even if the user has a valid push token). This sets notification_types to -2 on the server. To resubscribe the user, call optIn().
optIn(): Does one of three actions:
If the Subscription has a valid push token, it sets the current push subscription status to subscribed.
If the Subscription does not have a valid push token, it displays the push permission prompt.
If the push permission prompt has been displayed more than the operating system’s limit (once iOS, twice Android), it displays the fallback prompt.
optedIn: Returns true if the current push subscription status is subscribed, otherwise false. If the push token is valid but optOut() was called, this will return false.
Adds or removes an SMS Subscription for the current user. Phone numbers must be in E.164 format (e.g., +15551234567). Compatible with Identity Verification.
addSms(phoneNumber) creates or reassigns the SMS Subscription to the current user. The same number cannot exist multiple times in one app.
removeSms(phoneNumber) detaches the number from the current user and assigns it a new OneSignal ID. Other Subscriptions remain unaffected.
Shows the native system prompt asking the user for push notification permission. Optionally enable a fallback prompt that links to the settings app.
fallbackToSettings: If true, the fallback prompt will be displayed if the user denied push permissions more than the operating system’s limit (once iOS, twice Android).
Fires when push permission changes — the user accepts/declines the prompt, or toggles notifications in system settings. The listener receives a state object with from and to values. Call removePermissionObserver() to stop listening.
class MyObserver : IPermissionObserver { init { OneSignal.Notifications.addPermissionObserver(this) } override fun onNotificationPermissionChange(granted: Boolean) { if (granted) { // Notifications are now enabled } } fun cleanup() { OneSignal.Notifications.removePermissionObserver(this) }}
public class MainActivity extends Activity implements IPermissionObserver { protected void onCreate(Bundle savedInstanceState) { OneSignal.getNotifications().addPermissionObserver(this); } @Override public void onNotificationPermissionChange(boolean granted) { if (granted) { // Notifications are now enabled } } @Override protected void onDestroy() { OneSignal.getNotifications().removePermissionObserver(this); super.onDestroy(); }}
const onPermissionChange = (granted) => { console.log('Permission changed:', granted);};OneSignal.Notifications.addEventListener('permissionChange', onPermissionChange);// Remove later if neededOneSignal.Notifications.removeEventListener('permissionChange', onPermissionChange);
final observer = (bool hasPermission) { print("Notification permission: $hasPermission");};OneSignal.Notifications.addPermissionObserver(observer);// Remove later if neededOneSignal.Notifications.removePermissionObserver(observer);
const listener = (granted) => { console.log("Push permission changed:", granted);};// IonicOneSignal.Notifications.addEventListener("permissionChange", listener);// Remove later if neededOneSignal.Notifications.removeEventListener("permissionChange", listener);// Cordovawindow.plugins.OneSignal.Notifications.addEventListener("permissionChange", listener);// Remove later if neededwindow.plugins.OneSignal.Notifications.removeEventListener("permissionChange", listener);
getPermission() returns the current app-level push permission status. It does not reflect OneSignal-level changes from optOut() or the Subscriptions API. For real-time tracking, use the Push Permission Observer or Push Subscription Observer.getCanRequestPermission() returns whether the system will show a permission prompt. If false, the user already denied permission. See Prompt for push permissions.
Runs when a user clicks a push notification that opens the app. The app is already launched by the time this fires — do not relaunch or duplicate navigation. Use removeClickListener() or removeEventListener() to stop listening.
In Flutter Debug mode, force-closing the app prevents click listeners from registering. Use a release build (flutter run --release) or set the Xcode scheme to Release.
val clickListener = object : INotificationClickListener { override fun onClick(event: INotificationClickEvent) { Log.d("OneSignal", "Notification clicked: ${event.notification.title}") }}OneSignal.Notifications.addClickListener(clickListener)
Runs when a notification is received while the app is in the foreground. By default, OneSignal displays foreground notifications automatically — this listener lets you intercept and control that behavior.Within this method, you can:
Call event.preventDefault() to stop the notification from displaying. This is helpful to prevent the notification from disrupting the user while the app is in the foreground.
Optionally, you have about 25 seconds to do any checks or make any changes to the notification before calling event.notification.display() to show it on your own terms. If you never call display() after preventDefault(), the notification is silently discarded.
If preventDefault() does not suppress the notification (or the notification appears after a ~25 second delay), check if your app sets a custom UNUserNotificationCenterDelegate. A custom delegate’s willPresent completion handler can force the notification to display regardless of preventDefault(). Remove the custom delegate or ensure it does not pass display options (.banner, .sound, .list) to the completion handler.
Use removeForegroundLifecycleListener() or removeEventListener() to stop listening.
val lifecycleListener = object : INotificationLifecycleListener { override fun onWillDisplay(event: INotificationWillDisplayEvent) { Log.d("OneSignal", "Foreground notification: ${event.notification.title}") // Stop the notification from displaying automatically // event.preventDefault() // Show it manually when ready // event.notification.display() }}OneSignal.Notifications.addForegroundLifecycleListener(lifecycleListener)
OneSignal.getNotifications().addForegroundLifecycleListener(new INotificationLifecycleListener() { @Override public void onWillDisplay(@NonNull INotificationWillDisplayEvent event) { Log.d("OneSignal", "Foreground notification received: " + event.getNotification().getTitle()); // Stop the notification from displaying automatically // event.preventDefault(); // Show it manually when ready // event.getNotification().display(); }});
// Add the OSNotificationLifecycleListener protocol to your app delegateclass AppDelegate: NSObject, UIApplicationDelegate, OSNotificationLifecycleListener { func onWillDisplay(event: OSNotificationWillDisplayEvent) { print("Foreground notification: \(event.notification.title)") // Stop the notification from displaying automatically // event.preventDefault() // Show it manually when ready // event.notification.display() } func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { OneSignal.Notifications.addForegroundLifecycleListener(self) return true }}
@implementation AppDelegate- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [OneSignal.Notifications addForegroundLifecycleListener:self]; return YES;}- (void)onWillDisplayNotification:(OSNotificationWillDisplayEvent *)event { NSLog(@"Foreground notification: %@", event.notification.title); // Stop the notification from displaying automatically // [event preventDefault]; // Show it manually when ready // [event.notification display];}@end
OneSignal.Notifications.ForegroundWillDisplay += (sender, e) =>{ Console.WriteLine("Foreground notification: " + e.Notification.RawPayload); // Stop the notification from displaying automatically // e.PreventDefault(); // Show it manually when ready // e.Notification.Display();};
OneSignal.Notifications.addEventListener('foregroundWillDisplay', (event) => { console.log("Foreground notification:", event.getNotification().title); // Stop the notification from displaying automatically // event.preventDefault(); // Show it manually when ready // event.getNotification().display();});
OneSignal.Notifications.addForegroundWillDisplayListener((event) { print("Foreground notification: ${event.notification.title}"); // Stop the notification from displaying automatically // event.preventDefault(); // Show it manually when ready // event.notification.display();});
const myLifecyleListener = function(event) { console.log("Foreground notification:", event.notification.title); // Stop the notification from displaying automatically // event.preventDefault(); // Show it manually when ready // event.notification.display();};// IonicOneSignal.Notifications.addEventListener("foregroundWillDisplay", myLifecyleListener);// Cordovawindow.plugins.OneSignal.Notifications.addEventListener("foregroundWillDisplay", myLifecyleListener);
Removes all OneSignal notifications from the Notification Shade. Use instead of Android’s android.app.NotificationManager.cancel. Otherwise, the notifications will be restored when your app is restarted.
Cancel a single notification by its Android notification ID, or a group by its group key. Use these instead of android.app.NotificationManager.cancel — otherwise notifications will be restored when the app restarts.
Decide when to display an In-App Message based on a single or multiple triggers. See Triggers for more information.Triggers are not persisted to the backend. They only exist on the local device and apply to the current user.
OneSignal.InAppMessages.addTrigger("KEY", "VALUE")OneSignal.InAppMessages.addTriggers(mapOf("KEY_01" to "VALUE_01", "KEY_02" to "VALUE_02"))
Prevent In-app messages from being displayed to the user. When set to true, no in-app messages will be presented. When set to false, any messages the user qualifies for will be presented to them at the appropriate time.
OneSignal.InAppMessages.paused = true
OneSignal.getInAppMessages().setPaused(true);
OneSignal.InAppMessages.paused = true// Get `paused` statelet paused = OneSignal.InAppMessages.paused
[OneSignal.InAppMessages paused:true];// Get `paused` stateBOOL paused = [OneSignal.InAppMessages paused];
// AppDelegate.swift// Add OSInAppMessageLifecycleListener as an implemented protocol of the class that will handle the In-App Message lifecycle events.class AppDelegate: UIResponder, UIApplicationDelegate, OSInAppMessageLifecycleListener { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool { // Add your implementing class as the listener OneSignal.InAppMessages.addLifecycleListener(self) } // Add one or more of the following optional lifecycle methods func onWillDisplay(event: OSInAppMessageWillDisplayEvent) { print("OSInAppMessageLifecycleListener: onWillDisplay Message: \(event.message.messageId)") } func onDidDisplay(event: OSInAppMessageDidDisplayEvent) { print("OSInAppMessageLifecycleListener: onDidDisplay Message: \(event.message.messageId)") } func onWillDismiss(event: OSInAppMessageWillDismissEvent) { print("OSInAppMessageLifecycleListener: onWillDismiss Message: \(event.message.messageId)") } func onDidDismiss(event: OSInAppMessageDidDisplayEvent) { print("OSInAppMessageLifecycleListener: onDidDismiss Message: \(event.message.messageId)") }}
// AppDelegate.h// Add OSInAppMessageLifecycleListener as an implemented protocol of the class that will handle the In-App Message lifecycle events.@interface AppDelegate : UIResponder <UIApplicationDelegate, OSInAppMessageLifecycleListener>@end// AppDelegate.m@implementation AppDelegate- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { // Add your implementing class as the listener. [OneSignal.InAppMessages addLifecycleListener:self];}// Add one or more of the following optional lifecycle methods- (void)onWillDisplayInAppMessage:(OSInAppMessageWillDisplayEvent *)event { NSLog(@"OSInAppMessageLifecycleListener: onWillDisplay Message: %@", event.message.messageId);}- (void)onDidDisplayInAppMessage:(OSInAppMessageDidDisplayEvent *)event { NSLog(@"OSInAppMessageLifecycleListener: onDidDisplay Message: %@", event.message.messageId);}- (void)onWillDismissInAppMessage:(OSInAppMessageWillDismissEvent *)event { NSLog(@"OSInAppMessageLifecycleListener: onWillDismiss Message: %@", event.message.messageId);}- (void)onDidDismissInAppMessage:(OSInAppMessageDidDismissEvent *)event { NSLog(@"OSInAppMessageLifecycleListener: onDidDismiss Message: %@", event.message.messageId);}
OneSignal.InAppMessages.WillDisplay += (sender, e) => { // Access the in-app message with e.Message };OneSignal.InAppMessages.DidDisplay += (sender, e) => { // Access the in-app message with e.Message };OneSignal.InAppMessages.WillDismiss += (sender, e) => { // Access the in-app message with e.Message };OneSignal.InAppMessages.DidDismiss += (sender, e) => { // Access the in-app message with e.Message };
OneSignal.InAppMessages.addEventListener('willDisplay', (event) => { console.log('OneSignal: will display IAM: ', event);});OneSignal.InAppMessages.addEventListener('didDisplay', (event) => { console.log('OneSignal: did display IAM: ', event);});OneSignal.InAppMessages.addEventListener('willDismiss', (event) => { console.log('OneSignal: will dismiss IAM: ', event);});OneSignal.InAppMessages.addEventListener('didDismiss', (event) => { console.log('OneSignal: did dismiss IAM: ', event);});
OneSignal.InAppMessages.addWillDisplayListener((event) { print("ON WILL DISPLAY IN APP MESSAGE ${event.message.messageId}");});OneSignal.InAppMessages.addDidDisplayListener((event) { print("ON DID DISPLAY IN APP MESSAGE ${event.message.messageId}");});OneSignal.InAppMessages.addWillDismissListener((event) { print("ON WILL DISMISS IN APP MESSAGE ${event.message.messageId}");});OneSignal.InAppMessages.addDidDismissListener((event) { print("ON DID DISMISS IN APP MESSAGE ${event.message.messageId}");});
// Define the lifecycle listener functionslet willDisplayListener = async function(event) { console.log("OneSignal: will display IAM: "+ event.messageId);};let didDisplayListener = async function(event) { console.log("OneSignal: did display IAM: "+ event.messageId);};let willDismissListener = async function(event) { console.log("OneSignal: will dismiss IAM: "+ event.messageId);};let didDismissListener = async function(event) { console.log("OneSignal: did dismiss IAM: "+ event.messageId);};// Listeners for each event added separately// IonicOneSignal.InAppMessages.addEventListener("willDisplay", willDisplayListener);OneSignal.InAppMessages.addEventListener("didDisplay", didDisplayListener);OneSignal.InAppMessages.addEventListener("willDismiss", willDismissListener);OneSignal.InAppMessages.addEventListener("didDismiss", didDismissListener);// Cordovawindow.plugins.OneSignal.InAppMessages.addEventListener("willDisplay", willDisplayListener);window.plugins.OneSignal.InAppMessages.addEventListener("didDisplay", didDisplayListener);window.plugins.OneSignal.InAppMessages.addEventListener("willDismiss", willDismissListener);window.plugins.OneSignal.InAppMessages.addEventListener("didDismiss", didDismissListener);
Applications should allow users to opt-in to Live Activities. For example, your app gives the user the option to start the Live Activity within your US using a button or presenting an IAM. You may start and update a Live Activity via any method without an explicit prompt, unlike Notification Permission or Location Permission. Live Activities appear with the iOS Provisional Authorization UI. Live Activities must be started when your application is in the foreground. We recommend reading Apple’s developer guidelines to learn more about Live Activities.
Allows OneSignal to manage the lifecycle of a LiveActivity on behalf of the application. This includes listening for both pushToStart token updates and pushToUpdate token updates.
//... your app's codeOneSignal.LiveActivities.setup(MyWidgetAttributes.self);
Allows cross platform SDK’s to manage the lifecycle of a LiveActivity by eliminating the need for a customer app to define and manage their own ActivityAttributes. See Cross-platform setup for further details.
using OneSignalSDK;//Push To StartOneSignal.LiveActivities.SetupDefault();//Launching the Live Activity from within the app (not needed for push to start)string activityId = "my_activity_id";OneSignal.LiveActivities.StartDefault( activityId, new Dictionary<string, object>() { { "title", "Welcome!" } }, new Dictionary<string, object>() { { "message", new Dictionary<string, object>() { { "en", "Hello World!"} }}, });
import { OneSignal } from 'react-native-onesignal'//Push To StartOneSignal.LiveActivities.setupDefault()//Launching the Live Activity from within the app (not needed for push to start)const activityId = "my_activity_id"const attributes = { title: "Sample Title" } ;const content = { message: { en: "message" } };OneSignal.LiveActivities.startDefault(activityId, attributes, content);
import 'package:onesignal_flutter/onesignal_flutter.dart';OneSignal.LiveActivities.setupDefault()//Launching the Live Activity from within the app (not needed for push to start)const String activityId = "my_activity_id";OneSignal.LiveActivities.startDefault(activityId!, { "title": "Welcome!" }, { "message": {"en": "Hello World!"},});
//Ionicimport OneSignal from "onesignal-cordova-plugin";//Push To StartOneSignal.LiveActivities.setupDefault();//Launching the Live Activity from within the app (not needed for push to start)const activityId = "my_activity_id";const attributes = { title: "Sample Title" };const content = { message: { en: "message" } };OneSignal.LiveActivities.startDefault(activityId, attributes, content);//Cordova//Push To Startwindow.plugins.OneSignal.LiveActivities.setupDefault();//Launching the Live Activity from within the app (not needed for push to start)const activityId = "my_activity_id";const attributes = { title: "Sample Title" };const content = { message: { en: "message" } };window.plugins.OneSignal.LiveActivities.startDefault( activityId, attributes, content);
Entering a Live Activity associates an activityId with a Live Activity Temporary Push Token on our server. Specify this identifier when using the Update Live Activities REST API to update one or multiple Live Activities simultaneously.
// ... your app's codelet activity = try Activity<MyWidgetAttributes>.request( attributes: attributes, contentState: contentState, pushType: .token)Task { for await data in activity.pushTokenUpdates { let token = data.map {String(format: "%02x", $0)}.joined() // ... required code for entering a live activity // Activity ID cannot contain "/" characters OneSignal.LiveActivities.enter("ACTIVITY_ID", withToken: token) }}
var result = OneSignalSDK.DotNet.OneSignal.Default.EnterLiveActivity("ACTIVITY_ID", token);if(result) { Console.WriteLine("Success");}
OneSignal.LiveActivities.enter('ACTIVITY_ID', token, (result) => { console.log('Results of entering live activity: ', result);});
OneSignal.LiveActivities.enterLiveActivity("ACTIVITY_ID", token).then((result) { print("Successfully enter live activity");}).catchError((error) { print("Failed to enter live activity with error: $error");});
//IonicOneSignal.LiveActivities.enter("ACTIVITY_ID", token, (result) => { console.log("Results of entering live activity: ", result);});//Cordovawindow.plugins.OneSignal.LiveActivities.enter("ACTIVITY_ID", token, (result) => { console.log("Results of entering live activity: ", result);});
OneSignal.LiveActivities.exit('ACTIVITY_ID', (result) => { console.log('Results of exiting live activity: ', result);});
OneSignal.LiveActivities.exit("ACTIVITY_ID").then((result) { print("Successfully exit live activity");}).catchError((error) { print("Failed to exit live activity: $error");});
window.plugins.OneSignal.LiveActivities.exit("ACTIVITY_ID", (result) => { console.log("Results of exiting live activity: ", result);});
Optional “low-level” approach to push to start live activities. Offers fine-grained control over the LiveActivity start and update tokens without altering the ActivityAttribute structure. Additional details available here
if #available(iOS 17.2, *) { // Setup an async task to monitor and send pushToStartToken updates to OneSignalSDK. Task { for try await data in Activity<MyWidgetAttributes>.pushToStartTokenUpdates { let token = data.map {String(format: "%02x", $0)}.joined() OneSignal.LiveActivities.setPushToStartToken(MyWidgetAttributes.self, withToken: token) } } // Setup an async task to monitor for an activity to be started, for each started activity we // can then set up an async task to monitor and send updateToken updates to OneSignalSDK. Task { for await activity in Activity<MyWidgetAttributes>.activityUpdates { Task { for await pushToken in activity.pushTokenUpdates { let token = pushToken.map {String(format: "%02x", $0)}.joined() OneSignal.LiveActivities.enter("my-activity-id", withToken: token) } } } }}
What is the difference between onesignal_id and the Subscription ID?
The onesignal_id is a user-level identifier that represents a person across all their devices and channels. The Subscription ID (User.pushSubscription.id) is a device-level identifier for a single push channel. One user can have multiple Subscriptions.
Do I need to call login() every time the app starts?
Yes. Call login(external_id) on every app launch once you know the user’s identifier (after sign-in or session restore). The SDK handles deduplication — if the user is already logged in with that ID, the call is effectively a no-op.
What happens to anonymous data when I call login()?
If the external_id already exists, anonymous data (tags, session data, email/SMS Subscriptions) collected before login is discarded. If the external_id is new, the anonymous data is retained and associated with the newly created user.
The OneSignal ID is not available until the SDK finishes initializing. If you call getOnesignalId() too early (for example, immediately after initialize()), it may return null. Use User State addObserver() to reliably detect when the ID becomes available.
