Mobile SDK reference

Setup & debugging

These methods are a reference for integrating the OneSignal SDK into your app. For full platform-specific setup instructions, see Mobile SDK setup.

`initialize()`

Initializes the OneSignal SDK. This should be called during application startup. The ONESIGNAL_APP_ID can be found in Keys & IDs.

If you want to delay initialization of the OneSignal SDK, we recommend using our Privacy methods.

OneSignal.initWithContext(this, ONESIGNAL_APP_ID)

OneSignal.initWithContext(this, ONESIGNAL_APP_ID);

import OneSignalFramework

OneSignal.initialize("ONESIGNAL_APP_ID", withLaunchOptions: launchOptions)

#import <OneSignalFramework/OneSignalFramework.h>

[OneSignal initialize:@"ONESIGNAL_APP_ID" withLaunchOptions:launchOptions];

OneSignal.Initialize("ONESIGNAL_APP_ID");

OneSignal.initialize("ONESIGNAL_APP_ID");

OneSignal.initialize("ONESIGNAL_APP_ID");

// Ionic
OneSignal.initialize("ONESIGNAL_APP_ID");

// Cordova
window.plugins.OneSignal.initialize("ONESIGNAL_APP_ID");

`setLogLevel()`

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. In Ionic, you can also import the LogLevel enum from onesignal-cordova-plugin.

OneSignal.Debug.logLevel = LogLevel.VERBOSE

OneSignal.getDebug().setLogLevel(LogLevel.VERBOSE);

OneSignal.Debug.setLogLevel(.LL_VERBOSE)

[OneSignal.Debug setLogLevel:ONE_S_LL_VERBOSE];

OneSignal.Debug.LogLevel = LogLevel.Verbose;

OneSignal.Debug.setLogLevel(LogLevel.Verbose);

OneSignal.Debug.setLogLevel(OSLogLevel.verbose);

// Ionic
OneSignal.Debug.setLogLevel(6);

// Cordova
window.plugins.OneSignal.Debug.setLogLevel(6);

`setAlertLevel()`

Sets the logging level to show as alert dialogs in your app. Make sure to remove this before submitting to the app store.

OneSignal.Debug.alertLevel = LogLevel.NONE

OneSignal.getDebug().setAlertLevel(LogLevel.NONE);

OneSignal.Debug.setAlertLevel(.LL_NONE)

[OneSignal.Debug setAlertLevel:ONE_S_LL_NONE];

OneSignal.Debug.AlertLevel = LogLevel.None;

OneSignal.Debug.setAlertLevel(LogLevel.None);

OneSignal.Debug.setAlertLevel(OSLogLevel.none);

// Ionic
OneSignal.Debug.setAlertLevel(0);

// Cordova
window.plugins.OneSignal.Debug.setAlertLevel(0);

User identity & properties

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.

OneSignal.login("external_id")

OneSignal.login("external_id");

OneSignal.login("external_id")

[OneSignal login:@"external_id"];

OneSignal.Login("external_id");

OneSignal.login("external_id");

OneSignal.login("external_id");

// Ionic
OneSignal.login("external_id");

// Cordova
window.plugins.OneSignal.login("external_id");

Logs in a user and sets their email, SMS number, tags, and aliases in one request, then returns whether the login worked. Use it at sign-up or sign-in when you already have the user’s contact details. Availability: Android native 5.11.0 and later. Other SDKs are coming soon. On other platforms, call login(external_id), then addEmail(), addSms(), addTags(), and addAlias(). Build the profile with OneSignalUserProfile.builder(). Every field is optional. A profile with no email, phone number, tags, or aliases behaves like login(external_id). Anonymous data follows the same rules as login(external_id), unless Identity Verification is on. Those rules also require that OneSignal has already saved a OneSignal ID for the anonymous user. If the external ID is new, the SDK keeps data collected before login and adds the profile to that user. If that external ID already belongs to another user, the SDK switches to that user, discards the anonymous data, and returns success. A 409 may appear in the logs during that switch. If this device is already logged in with that external ID, a profile with no fields does nothing once OneSignal has assigned a OneSignal ID. A profile that has fields sends those fields again.

Builder method	Sets
`setEmail()`	An email address for the user. A blank value is ignored.
`setSms()`	A phone number in E.164 format, including the leading `+`, such as `+15551234567`. A blank value is ignored.
`setEmailEnabled()`	Whether the email from `setEmail()` is subscribed. `true` subscribes it. `false` unsubscribes it. If you leave it unset, the SDK sends no status. OneSignal subscribes a new address and keeps an existing address’s status unchanged. It has no effect without `setEmail()`.
`setSmsEnabled()`	Whether the phone number from `setSms()` is subscribed. `true` subscribes it. `false` unsubscribes it. If you leave it unset, the SDK sends no status. OneSignal subscribes a new number and keeps an existing number’s status unchanged. It has no effect without `setSms()`.
`setTags()`	A map of tag keys and values to set.
`setAliases()`	A map of alias labels and IDs. `external_id` and `onesignal_id` are reserved labels. The SDK skips them, logs a warning, and the login still succeeds.

Email and SMS: If the address is new to your app, OneSignal creates a Subscription for it. If another user in your app already has the address, that Subscription moves to this user and keeps its Subscription ID. The user’s other Subscriptions don’t change. setEmailEnabled(false) or setSmsEnabled(false) creates or moves the address and leaves it unsubscribed. A pending addEmail() or addSms() for that same address still sends subscribed when you leave the matching status unset. After you call setEmailEnabled() or setSmsEnabled(), you cannot clear it. Pass SMS numbers with the leading +. A number that fails the SDK’s format check, such as 555-0100, returns INVALID_ARGUMENT and sends no request. A number that only omits +, such as 15551234567, can pass that check. OneSignal then rejects it with BACKEND_ERROR and HTTP status 400.

Because an existing address moves to the user who logs in, an app that passes an email or phone number the user typed lets that user claim someone else’s Subscription. Turn on Identity Verification and include each address in the JWT’s subscriptions claim. See Adding subscriptions.

// login(external_id, profile) is a suspend function. Call it from a coroutine.
val profile = OneSignalUserProfile.builder()
    .setEmail("email@example.com")
    .setSms("+15551234567")
    .setTags(mapOf("plan" to "pro"))
    .setAliases(mapOf("crm_id" to "CRM-98421"))
    .build()

val loginResult = OneSignal.login("user-123", profile)

if (loginResult.isSuccess) {
    val loginData = loginResult.data
    loginData?.onesignalId          // OneSignal ID for this user
    loginData?.externalId           // "user-123"
    loginData?.emailSubscriptionId  // Subscription ID for the email passed, or null
    loginData?.smsSubscriptionId    // Subscription ID for the phone number passed, or null
} else {
    val reason = loginResult.error?.first
    reason?.code         // INVALID_ARGUMENT, NOT_INITIALIZED, BACKEND_ERROR, or UNKNOWN
    reason?.httpStatus   // HTTP status when code is BACKEND_ERROR
    reason?.backendCode  // Catalog code from the response, such as "user-1", or null
    reason?.message      // For logs, not for end users
}

OneSignalUserProfile profile = OneSignalUserProfile.builder()
    .setEmail("email@example.com")
    .setSms("+15551234567")
    .setTags(Collections.singletonMap("plan", "pro"))
    .setAliases(Collections.singletonMap("crm_id", "CRM-98421"))
    .build();

// Continue.with requires Android API level 24 or later. The callback may not run on the main thread.
OneSignal.login("user-123", profile, Continue.with(continueResult -> {
    if (!continueResult.isSuccess()) {
        // The call threw before returning a result. See continueResult.getThrowable().
        return;
    }

    OneSignalResult<LoginData> loginResult = continueResult.getData();
    if (loginResult.isSuccess()) {
        LoginData loginData = loginResult.getData();
        loginData.getOnesignalId();          // OneSignal ID for this user
        loginData.getExternalId();           // "user-123"
        loginData.getEmailSubscriptionId();  // Subscription ID for the email passed, or null
        loginData.getSmsSubscriptionId();    // Subscription ID for the phone number passed, or null
    } else {
        OneSignalError.Detail reason = loginResult.getError().getFirst();
        reason.getCode();         // INVALID_ARGUMENT, NOT_INITIALIZED, BACKEND_ERROR, or UNKNOWN
        reason.getHttpStatus();   // HTTP status when code is BACKEND_ERROR
        reason.getBackendCode();  // Catalog code from the response, such as "user-1", or null
        reason.getMessage();      // For logs, not for end users
    }
}));

On success, the result holds the OneSignal ID, the external ID, and the Subscription IDs for the email and phone number you passed. It does not list the user’s other tags or Subscriptions. Right after login, getTags() may return only the tags in the profile. The SDK then loads the user’s full tags in the background, and getTags() returns them once that finishes. Await the result before you call other user methods such as addTag(), so they apply to the new user. On failure, loginResult.error explains why:

Code	Meaning
`INVALID_ARGUMENT`	No request is sent and the current user doesn’t change. The external ID is null, empty, or contains a null character, the email or phone number is invalid, a tag key is empty or contains a null character, a tag value is null, or an alias label or ID is empty or contains a null character.
`NOT_INITIALIZED`	`initWithContext` has not been called, or initialization failed. A call made while initialization is still running waits for it to finish. Nothing changes when this error is returned.
`BACKEND_ERROR`	OneSignal rejected the request. `httpStatus` is the HTTP status. `backendCode` is the catalog code from the body when the body includes one, such as `user-1`. HTTP `409` means an alias already belongs to another user.
`UNKNOWN`	Any other failure, including no response within 60 seconds.

After a BACKEND_ERROR or UNKNOWN failure, the device is already on the new external ID. HTTP 401 means OneSignal rejected the JWT. With Identity Verification on, the SDK keeps that login queued and retries it after you call updateUserJwt. With Identity Verification off, the SDK drops a 401 the same way it drops any other BACKEND_ERROR. A request that timed out stays queued and can still complete later.

`logout()`

Unlinks the current user from the mobile Subscription.

Removes the external_id from the current mobile Subscription. Does not remove the external_id from other Subscriptions.
Resets the onesignal_id to a new anonymous user.
Any new data (e.g tags, Subscriptions, session data, etc.) will now be set on the new anonymous user until they are identified with the login method.

Use this when a user signs out of your app and you do not want to send targeted transactional messages to the device anymore.

OneSignal.logout()

OneSignal.logout();

OneSignal.logout()

[OneSignal logout];

OneSignal.Logout();

OneSignal.logout();

OneSignal.logout();

// Ionic
OneSignal.logout();

// Cordova
window.plugins.OneSignal.logout();

`getOnesignalId()`

Returns the current user-level onesignal_id from local device storage. Until OneSignal assigns the ID, getOnesignalId() returns null (nil on iOS). On Android native, it returns an empty string instead. Use the User State addObserver() 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.

val onesignalId = OneSignal.User.onesignalId

String onesignalId = OneSignal.getUser().getOnesignalId();

let onesignalId = OneSignal.User.onesignalId

NSString* onesignalId = OneSignal.User.onesignalId;

string onesignalId = OneSignal.User.OneSignalId;

const onesignalId = await OneSignal.User.getOnesignalId();

final onesignalId = await OneSignal.User.getOnesignalId();

// Ionic
const onesignalId = await OneSignal.User.getOnesignalId();

// Cordova
const onesignalId = await window.plugins.OneSignal.User.getOnesignalId();

`getExternalId()`

Returns the current user-level external_id from local device storage. If you haven’t set an external ID with login(), or user state isn’t initialized yet, getExternalId() returns null (nil on iOS). On Android native, it returns an empty string instead.

val externalId = OneSignal.User.externalId

String externalId = OneSignal.getUser().getExternalId();

let externalId: String? = OneSignal.User.externalId

NSString* externalId = OneSignal.User.externalId;

string externalId = OneSignal.User.ExternalId;

const externalId = await OneSignal.User.getExternalId();

final externalId = await OneSignal.User.getExternalId();

// Ionic
const externalId = await OneSignal.User.getExternalId();

// Cordova
const externalId = await window.plugins.OneSignal.User.getExternalId();

`addEventListener()` User State

Listen for changes in the user context (e.g., login, logout, ID assignment).

OneSignal.User.addObserver(object : IUserStateObserver {
    override fun onUserStateChange(state: UserChangedState) {
        println("User State Changed: onesignalId=${state.current.onesignalId}, externalId=${state.current.externalId}")
    }
})

OneSignal.getUser().addObserver(userChangedState -> {
	Log.d("User State Changed", String.valueOf(userChangedState.toJSONObject()));
});

// AppDelegate.swift
// Add OSUserStateObserver after UIApplicationDelegate
class AppDelegate: UIResponder, UIApplicationDelegate, OSUserStateObserver {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Add your AppDelegate as an observer
        OneSignal.User.addObserver(self)
        return true
    }

    // Add this new method
    func onUserStateDidChange(state: OSUserChangedState) {
        // prints out all properties
        print("OSUserChangedState: \n\(state.jsonRepresentation())")
        print(state.current.externalId)
        print(state.current.onesignalId)
    }
}

// Remove the observer
OneSignal.User.removeObserver(self)

// AppDelegate.h
// Add OSUserStateObserver after UIApplicationDelegate
@interface AppDelegate : UIResponder <UIApplicationDelegate, OSUserStateObserver>
@end

// AppDelegate.m
@implementation AppDelegate

- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Add your AppDelegate as an observer
    [OneSignal.User addObserver:self];
    return YES;
}

// Add this new method
- (void)onUserStateDidChangeWithState:(OSUserChangedState * _Nonnull)state {
    // prints out all properties
    NSLog(@"OSUserChangedState:\n%@", [state jsonRepresentation]);
    NSLog(@"current externalId: %@", state.current.externalId);
    NSLog(@"current onesignalId: %@", state.current.onesignalId);
}
@end

// Remove the observer
[OneSignal.User removeObserver:self];

OneSignal.User.Changed += _userStateChanged;

private void _userStateChanged(object sender, UserStateChangedEventArgs e) {
    ...
}

const listener = (event: UserChangedState) => {
    console.log("User changed: " + (event));
};

OneSignal.User.addEventListener("change", listener);
// Remove the listener
OneSignal.User.removeEventListener("change", listener);

void onUserChange(OSUserChangedState state) {
  var userState = state.jsonRepresentation();
  print('OneSignal user changed: $userState');
}
OneSignal.User.addObserver(onUserChange);

/// Remove a user state observer that has been previously added.
OneSignal.User.removeObserver(onUserChange);

// Ionic
const listener = (event: UserChangedState) => {
    console.log("User changed: " + (event));
};
OneSignal.User.addEventListener("change", listener);
// Remove the listener
OneSignal.User.removeEventListener("change", listener);

// Cordova
window.plugins.OneSignal.User.addEventListener("change", listener);
window.plugins.OneSignal.User.removeEventListener("change", listener);

`addAlias()`, `addAliases()`, `removeAlias()`, `removeAliases()`

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 alias
OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID")

// Add multiple aliases
var aliases = mapOf("ALIAS_LABEL_01" to "ALIAS_ID_01", "ALIAS_LABEL_02" to "ALIAS_ID_02")
OneSignal.User.addAliases(aliases)

// Remove a single alias
OneSignal.User.removeAlias("ALIAS_LABEL")

// Remove multiple aliases
OneSignal.User.removeAliases(listOf("ALIAS_LABEL_01", "ALIAS_LABEL_02"))

// Add a single alias
OneSignal.getUser().addAlias("ALIAS_LABEL", "ALIAS_ID");

// Add multiple aliases
HashMap<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 alias
OneSignal.getUser().removeAlias("ALIAS_LABEL");

// Remove multiple aliases
HashSet<String> labels = new HashSet<String>();
labels.add("ALIAS_LABEL_01");
labels.add("ALIAS_LABEL_02");
OneSignal.getUser().removeAliases(labels);

// Add a single alias
OneSignal.User.addAlias(label: "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 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 alias
OneSignal.User.AddAlias("ALIAS_LABEL", "ALIAS_ID");

// Add multiple aliases
OneSignal.User.AddAliases(new Dictionary<string, string> {
  { "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(new[] {"ALIAS_LABEL_01", "ALIAS_LABEL_02"});

// Add a single alias
OneSignal.User.addAlias("ALIAS_LABEL", "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 alias
OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID");

// Add multiple aliases
var aliases = <String, String>{
  "alias_key_1": "alias_id_1",
  "alias_key_2": "alias_id_2"
};
OneSignal.User.addAliases(aliases);

// Remove a single alias
OneSignal.User.removeAlias("ALIAS_LABEL");

// Remove multiple aliases
var labels = <String>["alias_key_1", "alias_key_2"];
OneSignal.User.removeAliases(labels);

// Add a single alias - Ionic
OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID");
// Add a single alias - Cordova
window.plugins.OneSignal.User.addAlias("ALIAS_LABEL", "ALIAS_ID");

// Add multiple aliases - Ionic
OneSignal.User.addAliases({ALIAS_LABEL_01: "ALIAS_ID_01", ALIAS_LABEL_02: "ALIAS_ID_02"});
// Add multiple aliases - Cordova
window.plugins.OneSignal.User.addAliases({ALIAS_LABEL_01: "ALIAS_ID_01", ALIAS_LABEL_02: "ALIAS_ID_02"});

// Remove a single alias - Ionic
OneSignal.User.removeAlias("ALIAS_LABEL");
// Remove a single alias - Cordova
window.plugins.OneSignal.User.removeAlias("ALIAS_LABEL");

// Remove multiple aliases - Ionic
OneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02"]);
// Remove multiple aliases - Cordova
window.plugins.OneSignal.User.removeAliases(["ALIAS_LABEL_01", "ALIAS_LABEL_02"]);

`setLanguage()`

Overrides the auto-detected language of the user. Use ISO 639-1 language code.

OneSignal.User.setLanguage("en")

OneSignal.getUser().setLanguage("en");

OneSignal.User.setLanguage("en")

[OneSignal.User setLanguage:@"en"];

OneSignal.User.Language = "en";

OneSignal.User.setLanguage("en");

OneSignal.User.setLanguage("en");

window.plugins.OneSignal.User.setLanguage("en");

Custom events

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.0, React Native 5.3.0, Flutter 5.4.0, Cordova/Ionic 5.3.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).

Example os_sdk payload

{ 
  "os_sdk": { 
    "sdk": "050213", 
    "device_os": "18.5", 
    "type": "iOSPush", 
    "device_model": "iPhone14,4", 
    "device_type": "ios", 
    "app_version": "5.4.0" 
  }
}

`trackEvent()`

See Custom Events for more details.

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);

OneSignal.User.trackEvent(name: "my_event_name", properties: nil)

let myProperties: [String: Any] = [
  "promo_code": "NEW50",
  "membership_details": [
    "vip": true,
    "products_viewed_count": 15
  ]
]
OneSignal.User.trackEvent(name: "started_free_trial", properties: myProperties)

[OneSignal.User trackEventWithName:@"my_event_name" properties:nil];

NSDictionary *myProperties = @{
  @"promo_code" : @"NEW50",
  @"membership_details" : @{
    @"vip" : @true,
    @"products_viewed_count" : @15
  } 
};
[OneSignal.User trackEventWithName:@"started_free_trial" properties:myProperties];

OneSignal.User.TrackEvent("my_event_name");

OneSignal.User.TrackEvent("started_free_trial", new Dictionary<string, object> {
    { "promo_code", "NEW50" },
    { "membership_details", new Dictionary<string, object> {
        { "vip", true },
        { "products_viewed_count", 15 }
    }}
});

OneSignal.User.trackEvent("my_event_name")

OneSignal.User.trackEvent("started_free_trial", {
  "promo_code": "NEW50",
  "membership_details": {
    "vip": true,
    "products_viewed_count": 15 
  }
})

OneSignal.User.trackEvent("my_event_name");

OneSignal.User.trackEvent("started_free_trial", {
  "promo_code": "NEW50",
  "membership_details": {
    "vip": true,
    "products_viewed_count": 15 
  }
});

// Ionic
OneSignal.User.trackEvent("my_event_name")

OneSignal.User.trackEvent("started_free_trial", {
  "promo_code": "NEW50",
  "membership_details": {
    "vip": true,
    "products_viewed_count": 15 
  }
})

// Cordova
window.plugins.OneSignal.User.trackEvent("my_event_name")

window.plugins.OneSignal.User.trackEvent("started_free_trial", {
  "promo_code": "NEW50",
  "membership_details": {
    "vip": true,
    "products_viewed_count": 15 
  }
})

Privacy

`setConsentRequired()`

Enforces user consent before data collection begins. Must be called before initializing the SDK.

OneSignal.consentRequired = true

OneSignal.setConsentRequired(true);

OneSignal.setConsentRequired(true)

[OneSignal setConsentRequired:true];

OneSignal.ConsentRequired = true;

OneSignal.setConsentRequired(true);

OneSignal.consentRequired(true);

// Ionic
OneSignal.setConsentRequired(true);
// Cordova
window.plugins.OneSignal.setConsentRequired(true);

`setConsentGiven()`

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.
If you want to delete the User and/or Subscription data, use our Delete user or Delete subscription APIs.

OneSignal.consentGiven = true

OneSignal.setConsentGiven(true);

OneSignal.setConsentGiven(true)

[OneSignal setConsentGiven:true];

OneSignal.ConsentGiven = true;

OneSignal.setConsentGiven(true);

OneSignal.consentGiven(true);

// Ionic
OneSignal.setConsentGiven(true);
// Cordova
window.plugins.OneSignal.setConsentGiven(true);

Location

Tracking location points requires 3 steps:

Add location tracking permissions and dependencies to your app.

iOS: Choosing the Location Services Authorization to Request developer guide. OneSignalLocation is an optional package. See iOS SDK setup.
Android: Request location permissions developer guide. The umbrella dependency com.onesignal:OneSignal includes location. If you declare modules individually, add com.onesignal:location. See Gradle modules.

Calling OneSignal.Location without com.onesignal:location throws Must include gradle module com.onesignal:Location in order to use this functionality! and crashes the app when the exception is uncaught. You may get the following errors:

LocationManager.startGetLocation: not possible, no location dependency found

Check your app’s dependencies. A common solution is to add the following to your app/build.gradle: 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.

`setShared()` Location

Enables or checks whether the SDK is sharing the Subscription’s latitude and longitude with OneSignal. Set proper location permissions first. On iOS, the SDK ignores setShared() when your OneSignal app settings already define location sharing.

OneSignal.Location.isShared = true

var isShared: Boolean = OneSignal.Location.isShared

OneSignal.getLocation().setShared(true);

boolean isShared = OneSignal.getLocation().isShared();

OneSignal.Location.isShared = true

let locationShared = OneSignal.Location.isShared

[OneSignal.Location setShared:true];

BOOL locationShared = [OneSignal.Location isShared];

OneSignal.Location.IsShared = true;

bool isShared = OneSignal.Location.IsShared;

OneSignal.Location.setShared(true);

OneSignal.Location.isShared();

OneSignal.Location.setShared(true);

OneSignal.Location.isShared();

// Ionic
OneSignal.Location.setShared(true);

OneSignal.Location.isShared().then((isShared) => {
  console.log("Location shared: ", isShared);
});

// Cordova
window.plugins.OneSignal.Location.setShared(true);

window.plugins.OneSignal.Location.isShared().then((isShared) => {
  console.log("Location shared: ", isShared);
});

`requestPermission()` Location

Displays the system-level location permission prompt. Alternatively, use in-app messages. Requires proper location permissions and setShared(true).

// requestPermission() is a suspend function. Call it from a coroutine.
val granted: Boolean = OneSignal.Location.requestPermission()

import com.onesignal.Continue;

OneSignal.getLocation().requestPermission(Continue.with(result -> {
    if (result.isSuccess()) {
        Boolean granted = result.getData();
        // act on granted
    } else {
        Throwable t = result.getThrowable();
        // log, fallback, etc.
    }
}));

OneSignal.Location.requestPermission()

[OneSignal.Location requestPermission];

OneSignal.Location.RequestPermission();

OneSignal.Location.requestPermission();

OneSignal.Location.requestPermission();

// Ionic
OneSignal.Location.requestPermission();

// Cordova
window.plugins.OneSignal.Location.requestPermission();

Subscriptions

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.

`User.pushSubscription.id`

Returns the current device-level subscription_id from local device storage. Until OneSignal assigns the ID, the Android SDK returns an empty string and the iOS SDK returns nil. Wrapper SDKs can return either null or an empty string, so check for both. Use the Push Subscription addObserver() instead to reliably get the subscription_id and react to changes. To read the ID off a device without code, see Copy the Subscription ID from a mobile device.

val subscriptionId = OneSignal.User.pushSubscription.id

String subscriptionId = OneSignal.getUser().getPushSubscription().getId();

let subscriptionId: String? = OneSignal.User.pushSubscription.id

NSString* subscriptionId = OneSignal.User.pushSubscription.id;

string subscriptionId = OneSignal.User.PushSubscription.Id;

const subscriptionId = await OneSignal.User.pushSubscription.getIdAsync();

final subscriptionId = OneSignal.User.pushSubscription.id;

// Ionic
const subscriptionId = await OneSignal.User.pushSubscription.getIdAsync();

// Cordova
const subscriptionId = await window.plugins.OneSignal.User.pushSubscription.getIdAsync();

`User.pushSubscription.token`

Returns the current device-level push subscription token from local device storage. Until the token is available, the Android SDK returns an empty string and the iOS SDK returns nil. Wrapper SDKs can return either null or an empty string, so check for both. Use the Push Subscription addObserver() instead to reliably get the token and react to changes.

val pushToken = OneSignal.User.pushSubscription.token

String pushToken = OneSignal.getUser().getPushSubscription().getToken();

let token: String? = OneSignal.User.pushSubscription.token

NSString* token = OneSignal.User.pushSubscription.token;

string token = OneSignal.User.PushSubscription.Token;

await OneSignal.User.pushSubscription.getTokenAsync();

OneSignal.User.pushSubscription.token;

// Ionic
await OneSignal.User.pushSubscription.getTokenAsync();

// Cordova
await window.plugins.OneSignal.User.pushSubscription.getTokenAsync();

`addObserver()` Push Subscription Changes

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 notifies your observer. The callback is onPushSubscriptionChange on Android and onPushSubscriptionDidChange(state:) on iOS. 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 observer
OneSignal.User.pushSubscription.removeObserver(this)

public class MainActivity extends Activity implements IPushSubscriptionObserver {
  protected void onCreate(Bundle savedInstanceState) {
    OneSignal.getUser().getPushSubscription().addObserver(this);
  }

  @Override
   public void onPushSubscriptionChange(@NotNull PushSubscriptionChangedState pushSubscriptionChangedState) {
      Log.i("OneSignal", "current subscription ID: " + pushSubscriptionChangedState.getCurrent().getId() );
   }
}

OneSignal.getUser().getPushSubscription().removeObserver(this);

class AppDelegate: UIResponder, UIApplicationDelegate, OSPushSubscriptionObserver {
   func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
      OneSignal.User.pushSubscription.addObserver(self)
      return true
   }

   func onPushSubscriptionDidChange(state: OSPushSubscriptionChangedState) {
       // respond to state change
   }
}

OneSignal.User.pushSubscription.removeObserver(self)

// AppDelegate.h
@interface AppDelegate : UIResponder <UIApplicationDelegate, OSPushSubscriptionObserver>
@end

// AppDelegate.m
@implementation AppDelegate

- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [OneSignal.User.pushSubscription addObserver:self];
  return YES;
}

- (void)onPushSubscriptionDidChangeWithState:(OSPushSubscriptionChangedState *)state {
   // respond to new state
}

@end

[OneSignal.User.pushSubscription removeObserver:self];

OneSignal.User.PushSubscription.Changed += (sender, e) =>
  {
    if (e.State.Current.Id != e.State.Previous.Id)
    {
      // OneSignal Subscription id changed.
    }
  };

const onSubscriptionChange = (subscription) => {
  console.log('OneSignal: subscription changed:', subscription);
};

OneSignal.User.pushSubscription.addEventListener('change', onSubscriptionChange);

// Removes the previously added listener
OneSignal.User.pushSubscription.removeEventListener('change', onSubscriptionChange);

void onPushSubscriptionChange(OSPushSubscriptionChangedState state) {
  if (state.current.optedIn) {
    /// respond to new state
  }
}
OneSignal.User.pushSubscription.addObserver(onPushSubscriptionChange);

// Removes the previously added observer
OneSignal.User.pushSubscription.removeObserver(onPushSubscriptionChange);

const listener = (event: PushSubscriptionChangedState) => {
  console.log("Push subscription changed: " + (event));
};

// Add the listener - Ionic
OneSignal.User.pushSubscription.addEventListener("change", listener);

// Remove the listener - Ionic
OneSignal.User.pushSubscription.removeEventListener("change", listener);

// Add the listener - Cordova
window.plugins.OneSignal.User.pushSubscription.addEventListener("change", listener);

// Remove the listener - Cordova
window.plugins.OneSignal.User.pushSubscription.removeEventListener("change", listener);

`optOut()`, `optIn()`, `optedIn`

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(): Sets the current push subscription status to subscribed. If the app does not have push permission, optIn() also requests it with fallbackToSettings set to true:
- iOS: If the user has not answered the prompt yet, the system permission prompt displays. If the user was already prompted and notifications are off, the fallback prompt displays.
- Android: The system permission prompt displays until the user denies it twice. After that, the fallback prompt displays.

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.

OneSignal.User.pushSubscription.optOut()

OneSignal.User.pushSubscription.optIn()

val optedIn = OneSignal.User.pushSubscription.optedIn

OneSignal.getUser().getPushSubscription().optOut();

OneSignal.getUser().getPushSubscription().optIn();

Boolean optedIn = OneSignal.getUser().getPushSubscription().getOptedIn();

OneSignal.User.pushSubscription.optOut()

OneSignal.User.pushSubscription.optIn()

let optedIn: Bool = OneSignal.User.pushSubscription.optedIn

[OneSignal.User.pushSubscription optOut];

[OneSignal.User.pushSubscription optIn];

BOOL optedIn = OneSignal.User.pushSubscription.optedIn;

OneSignal.User.PushSubscription.OptOut();

OneSignal.User.PushSubscription.OptIn();

bool optedIn = OneSignal.User.PushSubscription.OptedIn;

OneSignal.User.pushSubscription.optOut();

OneSignal.User.pushSubscription.optIn();

await OneSignal.User.pushSubscription.getOptedInAsync();

OneSignal.User.pushSubscription.optOut();

OneSignal.User.pushSubscription.optIn();

OneSignal.User.pushSubscription.optedIn;

// Ionic
OneSignal.User.pushSubscription.optOut();

OneSignal.User.pushSubscription.optIn();

await OneSignal.User.pushSubscription.getOptedInAsync();

// Cordova
window.plugins.OneSignal.User.pushSubscription.optOut();

window.plugins.OneSignal.User.pushSubscription.optIn();

await window.plugins.OneSignal.User.pushSubscription.getOptedInAsync();

`addEmail()`, `removeEmail()`

Adds or removes an email Subscription for the current user. Compatible with Identity Verification.

addEmail(email) creates or reassigns the email Subscription to the current user. The same email cannot exist multiple times in one app.
removeEmail(email) detaches the email from the current user and assigns it a new OneSignal ID. Other Subscriptions remain unaffected.

Call login() before addEmail() to avoid attaching it to an anonymous user. See Email reputation best practices.

OneSignal.User.addEmail("example@email.com")

OneSignal.User.removeEmail("example@email.com")

OneSignal.getUser().addEmail("example@email.com");

OneSignal.getUser().removeEmail("example@email.com");

OneSignal.User.addEmail("example@email.com")

OneSignal.User.removeEmail("example@email.com")

[OneSignal.User addEmail:@"example@email.com"];

[OneSignal.User removeEmail:@"example@email.com"];

OneSignal.User.AddEmail("example@email.com");

OneSignal.User.RemoveEmail("example@email.com");

OneSignal.User.addEmail("example@email.com");

OneSignal.User.removeEmail("example@email.com");

OneSignal.User.addEmail("example@email.com");

OneSignal.User.removeEmail("example@email.com");

// Ionic
OneSignal.User.addEmail("example@email.com");

OneSignal.User.removeEmail("example@email.com");

// Cordova
window.plugins.OneSignal.User.addEmail("example@email.com");

window.plugins.OneSignal.User.removeEmail("example@email.com");

`addSms()`, `removeSms()`

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.

Call login() before addSms() to avoid attaching it to an anonymous user. See SMS Registration Requirements.

OneSignal.User.addSms("+15558675309")

OneSignal.User.removeSms("+15558675309")

OneSignal.getUser().addSms("+15558675309");

OneSignal.getUser().removeSms("+15558675309");

OneSignal.User.addSms("+15558675309")

OneSignal.User.removeSms("+15558675309")

[OneSignal.User addSms:@"+15558675309"];

[OneSignal.User removeSms:@"+15558675309"];

OneSignal.User.AddSms("+15558675309");

OneSignal.User.RemoveSms("+15558675309");

OneSignal.User.addSms("+15558675309");

OneSignal.User.removeSms("+15558675309");

OneSignal.User.addSms("+15558675309");

OneSignal.User.removeSms("+15558675309");

// Ionic
OneSignal.User.addSms("+15558675309");

OneSignal.User.removeSms("+15558675309");

// Cordova
window.plugins.OneSignal.User.addSms("+15558675309");

window.plugins.OneSignal.User.removeSms("+15558675309");

Push permissions

`requestPermission(fallbackToSettings)` Push

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).

Fallback-to-settings prompt when permission is blocked

For production apps, consider using In-App Messages to prompt for notification permission instead of calling this method directly.

// requestPermission() is a suspend function. Call it from a coroutine.
val accepted: Boolean = OneSignal.Notifications.requestPermission(true)

OneSignal.getNotifications().requestPermission(true, Continue.with(r -> {
    if (r.isSuccess()) {
      if (r.getData()) {
        // User accepted permission
      }
      else {
        // User rejected permission
      }
    }
    else {
      // Request failed, check r.getThrowable()
    }
}));

OneSignal.Notifications.requestPermission({ accepted in
  print("User accepted notifications: \(accepted)")
}, fallbackToSettings: true)

[OneSignal.Notifications requestPermission:^(BOOL accepted) {
  NSLog(@"User accepted notifications: %d", accepted);
} fallbackToSettings:true];

var result = await OneSignal.Notifications.RequestPermissionAsync(true);

OneSignal.Notifications.requestPermission(true);

OneSignal.Notifications.requestPermission(true);

// Ionic
OneSignal.Notifications.requestPermission(true).then((accepted) => {
    console.log("User accepted notifications: " + accepted);
});

// Cordova
window.plugins.OneSignal.Notifications.requestPermission(true).then((accepted) => {
    console.log("User accepted notifications: " + accepted);
});

`addPermissionObserver()` Push

Fires when push permission changes, such as when the user accepts or declines the prompt or toggles notifications in system settings. The listener receives a boolean: true if the app has push permission, otherwise false. 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();
  }
}

class AppDelegate: UIResponder, UIApplicationDelegate, OSNotificationPermissionObserver {
  func application(_ application: UIApplication,
                  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    OneSignal.Notifications.addPermissionObserver(self)
    return true
  }

  func onNotificationPermissionDidChange(_ granted: Bool) {
    print("Notification permission changed: \(granted)")
  }

  func cleanup() {
    OneSignal.Notifications.removePermissionObserver(self)
  }
}

// AppDelegate.h
@interface AppDelegate : UIResponder <UIApplicationDelegate, OSNotificationPermissionObserver>
@end

// AppDelegate.m
@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [OneSignal.Notifications addPermissionObserver:self];
  return YES;
}

- (void)onNotificationPermissionDidChange:(BOOL)granted {
  NSLog(@"Permission changed: %d", granted);
}

- (void)cleanup {
  [OneSignal.Notifications removePermissionObserver:self];
}
@end

OneSignal.Notifications.PermissionChanged += (sender, e) =>
  {
    // Respond to permission change
  };

const onPermissionChange = (granted) => {
  console.log('Permission changed:', granted);
};

OneSignal.Notifications.addEventListener('permissionChange', onPermissionChange);

// Remove later if needed
OneSignal.Notifications.removeEventListener('permissionChange', onPermissionChange);

final observer = (bool hasPermission) {
  print("Notification permission: $hasPermission");
};

OneSignal.Notifications.addPermissionObserver(observer);

// Remove later if needed
OneSignal.Notifications.removePermissionObserver(observer);

const listener = (granted) => {
  console.log("Push permission changed:", granted);
};
// Ionic
OneSignal.Notifications.addEventListener("permissionChange", listener);

// Remove later if needed
OneSignal.Notifications.removeEventListener("permissionChange", listener);

// Cordova
window.plugins.OneSignal.Notifications.addEventListener("permissionChange", listener);

// Remove later if needed
window.plugins.OneSignal.Notifications.removeEventListener("permissionChange", listener);

`getPermission()`, `getCanRequestPermission()`

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. On iOS, it returns false once the user answers the prompt, whether they allowed or denied permission. On Android, it returns false once the user allows permission or denies it twice. See Prompt for push permissions.

// getPermission
OneSignal.Notifications.permission

// getCanRequestPermission
val canRequest: Boolean = OneSignal.Notifications.canRequestPermission

OneSignal.getNotifications().getPermission();

OneSignal.getNotifications().getCanRequestPermission();

OneSignal.Notifications.permission

OneSignal.Notifications.canRequestPermission

[OneSignal.Notifications permission];

[OneSignal.Notifications canRequestPermission];

bool permission = OneSignal.Notifications.Permission;

bool canRequest = OneSignal.Notifications.CanRequestPermission;

await OneSignal.Notifications.getPermissionAsync();

await OneSignal.Notifications.canRequestPermission();

var permission = OneSignal.Notifications.permission;

var canRequest = await OneSignal.Notifications.canRequest();

// Ionic
await OneSignal.Notifications.getPermissionAsync();
await OneSignal.Notifications.canRequestPermission();

// Cordova
await window.plugins.OneSignal.Notifications.getPermissionAsync();
await window.plugins.OneSignal.Notifications.canRequestPermission();

`permissionNative` iOS

Returns an enum for the native permission of the iOS device. It will be one of:

0 = NotDetermined
1 = Denied
2 = Authorized
3 = Provisional (only available in iOS 12+)
4 = Ephemeral (only available in iOS 14+)

let permissionNative: OSNotificationPermission = OneSignal.Notifications.permissionNative

OSNotificationPermission permissionNative = [OneSignal.Notifications permissionNative];

NotificationPermission permissionNative = OneSignal.Notifications.PermissionNative;

await OneSignal.Notifications.permissionNative()

var permissionNative = await OneSignal.Notifications.permissionNative();

// Ionic
await OneSignal.Notifications.permissionNative()

// Cordova
await window.plugins.OneSignal.Notifications.permissionNative()

Push notification events

`addClickListener()` Push

Runs when a user clicks a push notification that opens the app. The app is already launched by the time this fires, so 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)

OneSignal.getNotifications().addClickListener(event -> {
  Log.v(Tag.LOG_TAG, "INotificationClickListener.onClick fired" +
          " with event: " + event);
});

class AppDelegate: UIResponder, UIApplicationDelegate, OSNotificationClickListener {
  func application(_ application: UIApplication,
                  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    OneSignal.Notifications.addClickListener(self)
    return true
  }

  func onClick(event: OSNotificationClickEvent) {
    print("Notification clicked: \(event.jsonRepresentation())")
  }
}

// AppDelegate.h
@interface AppDelegate : UIResponder <UIApplicationDelegate, OSNotificationClickListener>
@end

// AppDelegate.m
@implementation AppDelegate

- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [OneSignal.Notifications addClickListener:self];
  return YES;
}

- (void)onClickNotification:(OSNotificationClickEvent *)event {
  NSLog(@"Notification clicked: %@", [event jsonRepresentation]);
}
@end

OneSignal.Notifications.Clicked += (sender, e) => {
  var RawPayload = e.Notification.RawPayload;
  Console.WriteLine("Notification clicked: " + RawPayload);
};

OneSignal.Notifications.addEventListener('click', (event) => {
  console.log('OneSignal: notification clicked:', event);
});

OneSignal.Notifications.addClickListener((event) {
  print('Notification clicked: ${event}');
});

const myClickListener = (event) => {
  console.log("Notification clicked:", JSON.stringify(event));
};
// Ionic
OneSignal.Notifications.addEventListener("click", myClickListener);

// Cordova
window.plugins.OneSignal.Notifications.addEventListener("click", myClickListener);

`addForegroundLifecycleListener()` Push

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, do any checks or make any changes to the notification, then call event.notification.display() to show it on your own terms. You have 30 seconds on Android and 25 seconds on iOS before the SDK stops waiting. 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.

This listener runs after Notification Service Extensions, which modify the payload before display.

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 delegate
class 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.getNotification().title);

  // Stop the notification from displaying automatically
  // event.preventDefault();

  // Show it manually when ready
  // event.getNotification().display();
};
// Ionic
OneSignal.Notifications.addEventListener("foregroundWillDisplay", myLifecyleListener);

// Cordova
window.plugins.OneSignal.Notifications.addEventListener("foregroundWillDisplay", myLifecyleListener);

`clearAllNotifications()`

Removes your app’s notifications from the device’s notification shade and resets the badge count to 0. The method runs asynchronously and does not fire click listeners. What gets removed differs by platform:

Android: Removes only notifications created by the OneSignal SDK and marks them as dismissed, so they are not restored when the app restarts. Notifications posted by your own code or by other SDKs are not affected.
iOS: Removes all of your app’s delivered notifications from Notification Center, including local notifications and notifications not sent through OneSignal. Scheduled local notifications that have not been delivered yet are not affected.

On Android, always clear notifications with OneSignal methods instead of Android’s native NotificationManager.cancel() or cancelAll(). Notifications canceled with the native APIs are not marked as dismissed, so the SDK restores them the next time the app restarts.If you call this method on app launch to prevent restored notifications, gate the call to Android in cross-platform apps. On iOS it also removes local notifications and pushes from other providers.

OneSignal.Notifications.clearAllNotifications()

OneSignal.getNotifications().clearAllNotifications();

OneSignal.Notifications.clearAll()

[OneSignal.Notifications clearAll];

OneSignal.Notifications.ClearAllNotifications();

OneSignal.Notifications.clearAll();

OneSignal.Notifications.clearAll();

// Ionic
OneSignal.Notifications.clearAll();

// Cordova
window.plugins.OneSignal.Notifications.clearAll();

`removeNotification()`, `removeGroupedNotifications()` Android

Removes a single notification by its Android notification ID, or all notifications in a group by its group key. Removed notifications are marked as dismissed, so they are not restored when the app restarts. Removing a grouped notification also updates the group’s summary. Both methods run asynchronously. The ID is the androidNotificationId from the notification object, available in the foreground lifecycle listener, the click listener, or a service extension. There is no API to look it up later, so store the ID when the notification arrives if you plan to remove the notification programmatically. The group key is the android_group value set when sending.

These methods are Android only. On iOS, remove specific delivered notifications with Apple’s removeDeliveredNotifications(withIdentifiers:). Send the notification with a collapse_id to get a predictable identifier to target. To replace a notification instead of removing it, use collapse_id when sending; no client code is required.

OneSignal.Notifications.removeNotification(id)
OneSignal.Notifications.removeGroupedNotifications("GROUP_KEY")

OneSignal.getNotifications().removeNotification(id);
OneSignal.getNotifications().removeGroupedNotifications("GROUP_KEY");

// Unity does not support removeNotification() or removeGroupedNotifications().

OneSignal.Notifications.removeNotification(id);
OneSignal.Notifications.removeGroupedNotifications("GROUP_KEY");

OneSignal.Notifications.removeNotification(id);
OneSignal.Notifications.removeGroupedNotifications("GROUP_KEY");

// Ionic
OneSignal.Notifications.removeNotification(id);
OneSignal.Notifications.removeGroupedNotifications("GROUP_KEY");

// Cordova
window.plugins.OneSignal.Notifications.removeNotification(id);
window.plugins.OneSignal.Notifications.removeGroupedNotifications("GROUP_KEY");

In-App Messages

In-app messages do not require any code; however, the SDK enables you to customize when messages are presented and handle lifecycle events.

`addTrigger()`, `addTriggers()`

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"))

OneSignal.getInAppMessages().addTrigger("KEY", "VALUE");

OneSignal.getInAppMessages().addTriggers(new HashMap<String, String>() {{
  put("KEY_01","VALUE_01");
  put("KEY_02", "VALUE_02");
}});

OneSignal.InAppMessages.addTrigger("KEY", withValue: "VALUE")

OneSignal.InAppMessages.addTriggers(["KEY_01": "VALUE_01", "KEY_02": "VALUE_02"])

[OneSignal.InAppMessages addTrigger:@"KEY" withValue:@"VALUE"];

[OneSignal.InAppMessages addTriggers:@{@"KEY_01": @"VALUE_01", @"KEY_02": @"VALUE_02"}];

OneSignal.InAppMessages.AddTrigger("KEY", "VALUE");

OneSignal.InAppMessages.AddTriggers(new Dictionary<string, string> {
  { "KEY_01", "VALUE_01" },
  { "KEY_02", "VALUE_02" }
});

OneSignal.InAppMessages.addTrigger("KEY", "VALUE");

OneSignal.InAppMessages.addTriggers({
  "KEY_01": "VALUE_01",
  "KEY_02": "VALUE_02"
});

OneSignal.InAppMessages.addTrigger("KEY", "VALUE");

OneSignal.InAppMessages.addTriggers({
  "KEY_01": "VALUE_01",
  "KEY_02": "VALUE_02"
});

// Ionic
OneSignal.InAppMessages.addTrigger("KEY", "VALUE");

OneSignal.InAppMessages.addTriggers({"KEY_01":"VALUE_01", "KEY_02":"VALUE_02"});

// Cordova
window.plugins.OneSignal.InAppMessages.addTrigger("KEY", "VALUE");

window.plugins.OneSignal.InAppMessages.addTriggers({"KEY_01":"VALUE_01", "KEY_02":"VALUE_02"});

`removeTrigger()`, `removeTriggers()`, `clearTriggers()`

Remove a single, multiple, or all triggers with the provided key from the current user.

OneSignal.InAppMessages.removeTrigger("KEY")

OneSignal.InAppMessages.removeTriggers(setOf("KEY_01", "KEY_02"))

OneSignal.InAppMessages.clearTriggers()

OneSignal.getInAppMessages().removeTrigger("KEY");

OneSignal.getInAppMessages().removeTriggers(Arrays.asList("KEY_01", "KEY_02"));

OneSignal.getInAppMessages().clearTriggers();

OneSignal.InAppMessages.removeTrigger("KEY")

OneSignal.InAppMessages.removeTriggers(["KEY_01", "KEY_02"])

OneSignal.InAppMessages.clearTriggers()

[OneSignal.InAppMessages removeTrigger:@"KEY"];

[OneSignal.InAppMessages removeTriggers:@[@"KEY_01", @"KEY_02"]];

[OneSignal.InAppMessages clearTriggers];

OneSignal.InAppMessages.RemoveTrigger("KEY");

OneSignal.InAppMessages.RemoveTriggers("KEY_01", "KEY_02");

OneSignal.InAppMessages.ClearTriggers();

OneSignal.InAppMessages.removeTrigger("KEY");

OneSignal.InAppMessages.removeTriggers(["KEY_01", "KEY_02"]);

OneSignal.InAppMessages.clearTriggers();

OneSignal.InAppMessages.removeTrigger("KEY");

OneSignal.InAppMessages.removeTriggers(["KEY_01", "KEY_02"]);

OneSignal.InAppMessages.clearTriggers();

// Ionic
OneSignal.InAppMessages.removeTrigger("KEY");

OneSignal.InAppMessages.removeTriggers(["KEY_01", "KEY_02"]);

OneSignal.InAppMessages.clearTriggers();

// Cordova
window.plugins.OneSignal.InAppMessages.removeTrigger("KEY");

window.plugins.OneSignal.InAppMessages.removeTriggers(["KEY_01", "KEY_02"]);

window.plugins.OneSignal.InAppMessages.clearTriggers();

`paused`

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` state
let paused = OneSignal.InAppMessages.paused

[OneSignal.InAppMessages paused:true];

// Get `paused` state
BOOL paused = [OneSignal.InAppMessages paused];

OneSignal.InAppMessages.Paused = true;

OneSignal.InAppMessages.setPaused(true);

OneSignal.InAppMessages.paused(true);

// Ionic
OneSignal.InAppMessages.setPaused(true);

// Cordova
window.plugins.OneSignal.InAppMessages.setPaused(true);

`addLifecycleListener()`

Respond to or track In-App Messages being displayed and dismissed.

val lifecycleListener = object : IInAppMessageLifecycleListener {
  override fun onWillDisplay(event: IInAppMessageWillDisplayEvent) {
    print(event.message.messageId)
  }

  override fun onDidDisplay(event: IInAppMessageDidDisplayEvent) {
    print(event.message.messageId)
  }

  override fun onWillDismiss(event: IInAppMessageWillDismissEvent) {
    print(event.message.messageId)
  }

  override fun onDidDismiss(event: IInAppMessageDidDismissEvent) {
    print(event.message.messageId)
  }
}
OneSignal.InAppMessages.addLifecycleListener(lifecycleListener)
OneSignal.InAppMessages.removeLifecycleListener(lifecycleListener)

OneSignal.getInAppMessages().addLifecycleListener(new IInAppMessageLifecycleListener() {
  @Override
  public void onWillDisplay(@NonNull IInAppMessageWillDisplayEvent event) {
      Log.v(Tag.LOG_TAG, "onWillDisplayInAppMessage");
  }

  @Override
  public void onDidDisplay(@NonNull IInAppMessageDidDisplayEvent event) {
      Log.v(Tag.LOG_TAG, "onDidDisplayInAppMessage");
  }

  @Override
  public void onWillDismiss(@NonNull IInAppMessageWillDismissEvent event) {
      Log.v(Tag.LOG_TAG, "onWillDismissInAppMessage");
  }

  @Override
  public void onDidDismiss(@NonNull IInAppMessageDidDismissEvent event) {
      Log.v(Tag.LOG_TAG, "onDidDismissInAppMessage");
  }
});

// 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: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Add your implementing class as the listener
    OneSignal.InAppMessages.addLifecycleListener(self)
    return true
  }
  // 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: OSInAppMessageDidDismissEvent) {
    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];
    return YES;
}

// 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 functions
let willDisplayListener = async function(event) {
  console.log("OneSignal: will display IAM: "+ event.message.messageId);
};
let didDisplayListener = async function(event) {
  console.log("OneSignal: did display IAM: "+ event.message.messageId);
};
let willDismissListener = async function(event) {
  console.log("OneSignal: will dismiss IAM: "+ event.message.messageId);
};
let didDismissListener = async function(event) {
  console.log("OneSignal: did dismiss IAM: "+ event.message.messageId);
};

// Listeners for each event added separately
// Ionic
OneSignal.InAppMessages.addEventListener("willDisplay", willDisplayListener);
OneSignal.InAppMessages.addEventListener("didDisplay", didDisplayListener);
OneSignal.InAppMessages.addEventListener("willDismiss", willDismissListener);
OneSignal.InAppMessages.addEventListener("didDismiss", didDismissListener);

// Cordova
window.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);

`addClickListener()` In-App

Respond to in-app message click events. The event contains the following click action metadata:

actionId: A custom identifier you set on the element.
urlTarget: An enum specifying how the launch URL for the message will be presented.
url: The launch URL for the action, if any.
closingMessage: A boolean value indicating if the action resulted in the message being closed.

val clickListener = object : IInAppMessageClickListener {
  override fun onClick(event: IInAppMessageClickEvent) {
    print(event.result.actionId)
  }
}
OneSignal.InAppMessages.addClickListener(clickListener)

OneSignal.getInAppMessages().addClickListener(new IInAppMessageClickListener() {
  @Override
  public void onClick(@Nullable IInAppMessageClickEvent event) {
    Log.v(Tag.LOG_TAG, "INotificationClickListener.inAppMessageClicked");
  }
});

class MyInAppMessageClickListener : NSObject, OSInAppMessageClickListener {
    func onClick(event: OSInAppMessageClickEvent) {
        let messageId = event.message.messageId
        print("Message ID: \(messageId)")
        let result: OSInAppMessageClickResult = event.result
        let actionId = result.actionId
        print("Action ID: ",(actionId ?? "no actionId"))
        let url = result.url
        print("URL: ", (url ?? "No URL"))
        let urlTarget: OSInAppMessageActionUrlType = result.urlTarget
        print("URL Target: \(urlTarget)")
        let closingMessage = result.closingMessage
        print("Closing Message: \(closingMessage)")
    }
}

// Add your object as a listener
let myListener = MyInAppMessageClickListener()
OneSignal.InAppMessages.addClickListener(myListener)

// Add this method to object implementing the OSInAppMessageClickListener protocol
- (void)onClickInAppMessage:(OSInAppMessageClickEvent * _Nonnull)event {
    NSLog(@"onClickInAppMessage event: %@", [event jsonRepresentation]);
    NSString *message = [NSString stringWithFormat:@"In App Message Click Occurred: messageId: %@ actionId: %@ url: %@ urlTarget: %@ closingMessage: %i",
                        event.message.messageId,
                        event.result.actionId,
                        event.result.url,
                        @(event.result.urlTarget),
                        event.result.closingMessage];
}

// Add your object as a listener
[OneSignal.InAppMessages addClickListener:self];

OneSignal.InAppMessages.Clicked += (sender, e) =>
  {
    // Access the in-app message with e.Message and the click result with e.Result
  };

OneSignal.InAppMessages.addEventListener('click', (event) => {
  console.log('OneSignal IAM clicked:', event);
});

OneSignal.InAppMessages.addClickListener((event) {
	print("In App Message Clicked: \n${event.result.jsonRepresentation().replaceAll("\\n", "\n")}");
});

let inAppClickListener = async function(event) {
  let clickData = JSON.stringify(event);
  console.log("In-App Message Clicked: "+ clickData);
};

// Ionic
OneSignal.InAppMessages.addEventListener("click", inAppClickListener);

// Cordova
window.plugins.OneSignal.InAppMessages.addEventListener("click", inAppClickListener);

Live Activity

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 UI 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.

`setup()`

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 attributes struct must conform to OneSignalLiveActivityAttributes. setup() requires iOS 16.1 or later. Listening for pushToStart tokens requires iOS 17.2 or later. On earlier versions, setup() listens only for pushToUpdate tokens.

//... your app's code
OneSignal.LiveActivities.setup(MyWidgetAttributes.self);

`setupDefault()`

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.

if #available(iOS 16.1, *) {
  //Push To Start
  OneSignal.LiveActivities.setupDefault()

  //Launching the Live Activity from within the app (not needed for push to start)
  let activityId = "my_activity_id"
  let attributes: [String: Any] = ["title": "Sample Title"]
  let content: [String: Any] = ["message": ["en": "message"]]
  OneSignal.LiveActivities.startDefault(activityId, attributes: attributes, content: content)
}

using OneSignalSDK;

//Push To Start
OneSignal.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 Start
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" } };
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!"},
});

//Ionic
import OneSignal from "onesignal-cordova-plugin";

//Push To Start
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" } };
OneSignal.LiveActivities.startDefault(activityId, attributes, content);

//Cordova
//Push To Start
window.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
);

`enter()`

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 code
let 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)
  }
}

OneSignal.LiveActivities.EnterAsync("ACTIVITY_ID", 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");
});

//Ionic
OneSignal.LiveActivities.enter("ACTIVITY_ID", token, (result) => {
  console.log("Results of entering live activity: ", result);
});

//Cordova
window.plugins.OneSignal.LiveActivities.enter("ACTIVITY_ID", token, (result) => {
  console.log("Results of entering live activity: ", result);
});

`exit()`

Exiting a Live activity deletes the association between an Activity Identifier with the Live Activity push token on our server.

The React Native, Flutter, Cordova/Ionic, and Unity SDKs mark exit() as deprecated and currently unsupported. Avoid calling it from these SDKs.

OneSignal.LiveActivities.exit("ACTIVITY_ID")

OneSignal.LiveActivities.ExitAsync("ACTIVITY_ID");

OneSignalSDK.DotNet.OneSignal.Default.ExitLiveActivity("ACTIVITY_ID");

OneSignal.LiveActivities.exit('ACTIVITY_ID', (result) => {
  console.log('Results of exiting live activity: ', result);
});

OneSignal.LiveActivities.exitLiveActivity("ACTIVITY_ID").then((result) {
    print("Successfully exit live activity");
}).catchError((error) {
    print("Failed to exit live activity: $error");
});

//Ionic
OneSignal.LiveActivities.exit("ACTIVITY_ID", (result) => {
  console.log("Results of exiting live activity: ", result);
});

//Cordova
window.plugins.OneSignal.LiveActivities.exit("ACTIVITY_ID", (result) => {
  console.log("Results of exiting live activity: ", result);
});

`setPushToStartToken()`

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 This method requires iOS 17.2 or later. In the cross-platform SDKs, pass the name of your ActivityAttributes struct as the activityType string. On Android, the cross-platform SDKs ignore the call.

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)
            }
        }
      }
  }
}

OneSignal.LiveActivities.SetPushToStartToken("MyWidgetAttributes", "PUSH_TO_START_TOKEN");

OneSignal.LiveActivities.setPushToStartToken("MyWidgetAttributes", "PUSH_TO_START_TOKEN");

OneSignal.LiveActivities.setPushToStartToken("MyWidgetAttributes", "PUSH_TO_START_TOKEN");

//Ionic
OneSignal.LiveActivities.setPushToStartToken("MyWidgetAttributes", "PUSH_TO_START_TOKEN");

//Cordova
window.plugins.OneSignal.LiveActivities.setPushToStartToken("MyWidgetAttributes", "PUSH_TO_START_TOKEN");

`removePushToStartToken()`

Called per-activity-type whenever that activity type should no longer be registered against the current subscription

if #available(iOS 17.2, *) {
  OneSignal.LiveActivities.removePushToStartToken(MyWidgetAttributes.self)
}

OneSignal.LiveActivities.RemovePushToStartToken("MyWidgetAttributes");

OneSignal.LiveActivities.removePushToStartToken("MyWidgetAttributes");

OneSignal.LiveActivities.removePushToStartToken("MyWidgetAttributes");

//Ionic
OneSignal.LiveActivities.removePushToStartToken("MyWidgetAttributes");

//Cordova
window.plugins.OneSignal.LiveActivities.removePushToStartToken("MyWidgetAttributes");

Outcomes

Track actions taken by users and attribute them to messages. See Outcomes for more details.

`addOutcome()`, `addUniqueOutcome()`, `addOutcomeWithValue()`

addOutcome(name): Adds an outcome captured against the current session.
addUniqueOutcome(name): Adds an outcome that the SDK sends only once. When a notification or in-app message influenced the session, the SDK sends the outcome once per influencing message. When nothing influenced the session, the SDK sends the outcome once per session.
addOutcomeWithValue(name, value): Adds an outcome with a numeric value.

OneSignal.Session.addOutcome("OUTCOME_NAME")
OneSignal.Session.addUniqueOutcome("OUTCOME_NAME")
OneSignal.Session.addOutcomeWithValue("OUTCOME_NAME", 3.14f)

OneSignal.getSession().addOutcome("OUTCOME_NAME");
OneSignal.getSession().addUniqueOutcome("OUTCOME_NAME");
OneSignal.getSession().addOutcomeWithValue("OUTCOME_NAME", 3.14f);

OneSignal.Session.addOutcome("OUTCOME_NAME")
OneSignal.Session.addUniqueOutcome("OUTCOME_NAME")
OneSignal.Session.addOutcome("OUTCOME_NAME", 3.14)

[OneSignal.Session addOutcome:@"OUTCOME_NAME"];
[OneSignal.Session addUniqueOutcome:@"OUTCOME_NAME"];
[OneSignal.Session addOutcomeWithValue:@"OUTCOME_NAME" value:@3.14];

OneSignal.Session.AddOutcome("OUTCOME_NAME");
OneSignal.Session.AddUniqueOutcome("OUTCOME_NAME");
OneSignal.Session.AddOutcomeWithValue("OUTCOME_NAME", 3.14f);

OneSignal.Session.addOutcome("OUTCOME_NAME");
OneSignal.Session.addUniqueOutcome("OUTCOME_NAME");
OneSignal.Session.addOutcomeWithValue("OUTCOME_NAME", 3.14);

OneSignal.Session.addOutcome("OUTCOME_NAME");
OneSignal.Session.addUniqueOutcome("OUTCOME_NAME");
OneSignal.Session.addOutcomeWithValue("OUTCOME_NAME", 3.14);

//Ionic
OneSignal.Session.addOutcome("OUTCOME_NAME");
OneSignal.Session.addUniqueOutcome("OUTCOME_NAME");
OneSignal.Session.addOutcomeWithValue("OUTCOME_NAME", 3.14);

//Cordova
window.plugins.OneSignal.Session.addOutcome("OUTCOME_NAME");
window.plugins.OneSignal.Session.addUniqueOutcome("OUTCOME_NAME");
window.plugins.OneSignal.Session.addOutcomeWithValue("OUTCOME_NAME", 3.14);

FAQ

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. 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. login(external_id, profile) sends its email, phone number, tags, and aliases on every call, including when that external ID is already the current user. Use login(external_id) on later launches. Use the profile overload when you have those fields to set. 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.

Why does `getOnesignalId()` return `null` or an empty string?

OneSignal hasn’t assigned a OneSignal ID to the current user yet. Until it does, Android returns an empty string and iOS returns nil. This happens on a fresh install and right after login() or logout() switches the user. Use User State addObserver() to detect when the ID becomes available.

​Setup & debugging

​initialize()

​setLogLevel()

​setAlertLevel()

​User identity & properties

​login(external_id)

​login(external_id, profile)

​logout()

​getOnesignalId()

​getExternalId()

​addEventListener() User State

​addAlias(), addAliases(), removeAlias(), removeAliases()

​setLanguage()

​Custom events

​trackEvent()

​Tags

​addTag(), addTags()

​removeTag(), removeTags()

​getTags()

​Privacy

​setConsentRequired()

​setConsentGiven()

​Location

​setShared() Location

​requestPermission() Location

​Subscriptions

​User.pushSubscription.id

​User.pushSubscription.token

​addObserver() Push Subscription Changes

​optOut(), optIn(), optedIn

​addEmail(), removeEmail()

​addSms(), removeSms()

​Push permissions

​requestPermission(fallbackToSettings) Push

​addPermissionObserver() Push

​getPermission(), getCanRequestPermission()

​permissionNative iOS

​Push notification events

​addClickListener() Push

​addForegroundLifecycleListener() Push

​clearAllNotifications()

​removeNotification(), removeGroupedNotifications() Android

​In-App Messages

​addTrigger(), addTriggers()

​removeTrigger(), removeTriggers(), clearTriggers()

​paused

​addLifecycleListener()

​addClickListener() In-App

​Live Activity

​setup()

​setupDefault()

​enter()

​exit()

​setPushToStartToken()

​removePushToStartToken()

​Outcomes

​addOutcome(), addUniqueOutcome(), addOutcomeWithValue()

​FAQ

​What is the difference between onesignal_id and the Subscription ID?

​Do I need to call login() every time the app starts?

​What happens to anonymous data when I call login()?

​Why does getOnesignalId() return null or an empty string?

Setup & debugging

`initialize()`

`setLogLevel()`

`setAlertLevel()`

User identity & properties

`login(external_id)`

`login(external_id, profile)`

`logout()`

`getOnesignalId()`

`getExternalId()`

`addEventListener()` User State

`addAlias()`, `addAliases()`, `removeAlias()`, `removeAliases()`

`setLanguage()`

Custom events

`trackEvent()`

Tags

`addTag()`, `addTags()`

`removeTag()`, `removeTags()`

`getTags()`

Privacy

`setConsentRequired()`

`setConsentGiven()`

Location

`setShared()` Location

`requestPermission()` Location

Subscriptions

`User.pushSubscription.id`

`User.pushSubscription.token`

`addObserver()` Push Subscription Changes

`optOut()`, `optIn()`, `optedIn`

`addEmail()`, `removeEmail()`

`addSms()`, `removeSms()`

Push permissions

`requestPermission(fallbackToSettings)` Push

`addPermissionObserver()` Push

`getPermission()`, `getCanRequestPermission()`

`permissionNative` iOS

Push notification events

`addClickListener()` Push

`addForegroundLifecycleListener()` Push

`clearAllNotifications()`

`removeNotification()`, `removeGroupedNotifications()` Android

In-App Messages

`addTrigger()`, `addTriggers()`

`removeTrigger()`, `removeTriggers()`, `clearTriggers()`

`paused`

`addLifecycleListener()`

`addClickListener()` In-App

Live Activity

`setup()`

`setupDefault()`

`enter()`

`exit()`

`setPushToStartToken()`

`removePushToStartToken()`

Outcomes

`addOutcome()`, `addUniqueOutcome()`, `addOutcomeWithValue()`

FAQ

What is the difference between `onesignal_id` and the Subscription ID?

Do I need to call `login()` every time the app starts?

What happens to anonymous data when I call `login()`?

Why does `getOnesignalId()` return `null` or an empty string?