Understand how Users work in OneSignal, including user identification, OneSignal ID, External ID, and how subscriptions and user properties are managed across channels.
In OneSignal, a User represents an individual with one or more Subscriptions to messaging channels such as push notifications, SMS, and email. Each User can be linked to up to 20 subscriptions and is uniquely identified by a OneSignal ID.
Users start as anonymous until you assign an External ID, allowing you to track them across devices and platforms.
Property | Description |
---|---|
Channel | The Subscriptions the user has, such as Push, Email, or SMS. |
OneSignal ID | A UUID v4 auto-generated by OneSignal for each user. It may change upon assigning an External ID. |
Last session | The latest timestamp of app interaction. |
First session | When the user was initially created in OneSignal. |
Email from the most recent Email Subscription. | |
Phone | Phone number from the most recent SMS Subscription. |
IP Address | From the latest updated Subscription. |
External ID | A unique identifier you assign to unify the user with your system. |
Tags | Custom metadata (e.g. preferences, behavior). See Data Tags. |
Location | GPS coordinates of mobile subscriptions (if location tracking is enabled). See Location-Triggered Notifications. |
Timezone | timezone_id in IANA TZ format, set by the SDK. Can be updated via API. |
Language | User’s language in ISO 639-1 format. Can be updated via API or setLanguage . |
Aliases | Key-value pairs like mixpanel_id : 1234 . See Aliases. |
The OneSignal ID is an internal UUID v4 generated to uniquely represent a user. It’s automatically created in scenarios such as:
OneSignal.logout
Once an External ID is used via OneSignal.login
, any existing OneSignal ID tied to the current Subscription is replaced by the one associated with that External ID. Subscriptions across platforms (Push, Email, SMS) will be merged under the same OneSignal ID if they share the same External ID.
If a user reinstalls the app or clears cache, a new OneSignal ID and Subscription are created. However, calling OneSignal.login
will link the new Subscription back to the original user profile.
Subscriptions added via OneSignal.User.addEmail
or addSms
will inherit the current OneSignal ID.
SDK references:
The External ID is a unique string you assign to users to track them across devices and subscriptions.
Use the External ID to track the user across their subscriptions.
You can set or remove the External ID via:
OneSignal.login
(frontend SDK)OneSignal.logout
(to remove)Do not use placeholder values like NA
, NULL
, 0
, -1
, all
, or 00000000-0000-0000-0000-000000000000
for External IDs.
Anonymous users have no External ID. Each subscription is treated as a separate user with its own OneSignal ID.
Identified users have a shared External ID across subscriptions, allowing OneSignal to merge their profiles.
OSID1
OSID2
EIDA
: OSID1
EIDA
: Merged to OSID1
OneSignal.login
for reliable identification.login
.When multiple users share a device, each new login should trigger a call to OneSignal.login
with a different External ID. This reassigns the OneSignal ID and Subscription to the new user.
To handle logout:
OneSignal.logout()
→ clears External ID and assigns anonymous OneSignal IDoptOut
, and re-enable with optIn
when logging back inMAU is used for billing and is defined as a mobile Subscription that has a last session within the 30 day billing period. This includes:
If a User has these Subscriptions:
Only iOS and Android mobile Subscriptions count, resulting in 2 MAUs.
The subscription status does not matter for MAU billing.
You can delay SDK initialization and Subscription creation using the mobile SDK privacy methods.
setConsentRequired()
before initializing the SDK – this prevents auto-creation of a SubscriptionsetConsentGiven()
when ready to create a Subscription for the user