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.
User properties
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. |
OneSignal ID
The OneSignal ID is an internal UUID v4 generated to uniquely represent a user. It’s automatically created in scenarios such as:
- First-time mobile app open (or after reinstall)
- New web subscription
- Creating users/subscriptions via Create user or CSV Import
- Clearing browser cache
- Logging out with
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.
Reassignment and behavior
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:
External ID
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)- Create user
- Create alias (by subscription)
- Transfer subscription
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 vs. identified users
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.
Example: Anonymous
- User subscribes on web:
OSID1
- Same user installs app:
OSID2
- Result: Two separate profiles
Example: Identified
- Web subscription with External ID
EIDA
:OSID1
- App subscription with same
EIDA
: Merged toOSID1
Best practices
- Always assign an External ID.
- Avoid generic values.
- Use
OneSignal.login
for reliable identification. - Set additional Aliases after
login
.
Multiple users on the same device
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:
- Call
OneSignal.logout()
→ clears External ID and assigns anonymous OneSignal ID - Optionally disable notifications using
optOut
, and re-enable withoptIn
when logging back in
Monthly active users (MAU)
MAUs are used for billing and are defined as mobile push Subscriptions that opened the app within the last 30 days. This includes:
- First-time app opens
- Reinstalls followed by opens
MAU billing example
If a User has these Subscriptions:
- iOS mobile push (active)
- Android mobile push (active)
- Web push
- SMS
Only iOS and Android push Subscriptions count, resulting in 2 MAUs.
Reinstalling the Android app again creates a 3rd MAU.
Reducing MAUs (e.g., paywall use cases)
You can delay SDK initialization and Subscription creation using:
setConsentRequired()
– prevent auto-creationsetConsentGiven()
– create Subscription only after consentlogin()
– assign External ID at the same time