​
Overview

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

PropertyDescription
ChannelThe Subscriptions the user has, such as Push, Email, or SMS.
OneSignal IDA UUID v4 auto-generated by OneSignal for each user. It may change upon assigning an External ID.
Last sessionThe latest timestamp of app interaction.
First sessionWhen the user was initially created in OneSignal.
EmailEmail from the most recent Email Subscription.
PhonePhone number from the most recent SMS Subscription.
IP AddressFrom the latest updated Subscription.
External IDA unique identifier you assign to unify the user with your system.
TagsCustom metadata (e.g. preferences, behavior). See Data Tags.
LocationGPS coordinates of mobile subscriptions (if location tracking is enabled). See Location-Triggered Notifications.
Timezonetimezone_id in IANA TZ format, set by the SDK. Can be updated via API.
LanguageUser’s language in ISO 639-1 format. Can be updated via API or setLanguage.
AliasesKey-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:
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 to OSID1

​
Best practices

  1. Always assign an External ID.
  2. Avoid generic values.
  3. Use OneSignal.login for reliable identification.
  4. 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 with optIn when logging back in

​
Monthly active users (MAU)

MAU is used for billing and is defined as a mobile Subscription that has a last session within the 30 day billing period. This includes:
  • Users that open your app for the first time, creating a mobile Subscription via our SDK
  • Users that reinstall the app and open it again, creating another mobile Subscription via our SDK
  • Users that get imported via our API

​
MAU billing example

If a User has these Subscriptions:
  • iOS mobile (active in the last 30 days)
  • Android mobile (active in the last 30 days)
  • Web push
  • Email
  • SMS
Only iOS and Android mobile Subscriptions count, resulting in 2 MAUs. The subscription status does not matter for MAU billing.

​
Reducing MAUs (e.g., paywall use cases)

You can delay SDK initialization and Subscription creation using the mobile SDK privacy methods.
  1. Call setConsentRequired() before initializing the SDK – this prevents auto-creation of a Subscription
  2. Call setConsentGiven() when ready to create a Subscription for the user