​
Overview

In OneSignal, a User represents an individual with one or more Subscriptions across your messaging channels (mobile push, web push, email, and SMS).
  • Each User can have up to 20 Subscriptions.
  • Every User is automatically assigned a OneSignal ID (UUID v4).
  • Users start as anonymous until you assign them an External ID. Assigning an External ID links Subscriptions together and may replace the existing OneSignal ID if the user already exists in your app.
  • Users and Subscriptions have different properties. For example, Tags are stored at the User level, while subscription status (opted-in/out) belongs to the Subscription.
  • When the User context changes — for example, logging in (anonymous → identified) or switching accounts (UserA → UserB) — the Subscription is reassigned from the old User to the new one.
    • The Subscription will now inherit the properties of the new User.
    • Properties tied to the previous User (like Tags, language, or External ID) will no longer apply.
Example:
  • UserA has Tag premium=true
  • UserB has Tag premium=false
  • If a Subscription moves from UserA to UserB, it will no longer be associated with premium=true and will instead reflect UserB’s properties.

​
Anonymous vs. identified users

  • Anonymous user: Has no External ID → each Subscription is separate with its own OneSignal ID (treated as separate Users).
  • Identified user: Has an External ID → OneSignal merges all Subscriptions under a single OneSignal ID.
Example: Anonymous user
  • Web push Subscription → OneSignal_ID_1
  • Mobile Subscription → OneSignal_ID_2
  • Email Subscription → OneSignal_ID_3
  • SMS Subscription → OneSignal_ID_4
  • Result: Four Users (each Subscription is a separate User with unique properties)
Example: Identified user
  • Web push Subscription with External ID External_ID_A → OneSignal_ID_1
  • Mobile Subscription with same External_ID_A → merged into OneSignal_ID_1
  • Email Subscription with same External_ID_A → merged into OneSignal_ID_1
  • SMS Subscription with same External_ID_A → merged into OneSignal_ID_1
  • Result: One User with four Subscriptions (all tied to the same User)
Always assign an External ID. This ensures Subscriptions across channels and devices unify under a single User profile and prevents duplication.
  • Use stable, non-generic identifiers (e.g., your internal user ID or email address).
  • Call OneSignal.login early in your app lifecycle.

​
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 push Subscription
  • Creating Users/Subscriptions via Create user or CSV Import
  • Clearing browser cache and returning to the site
  • 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:

​
Restricted IDs

Do not use placeholder values or temporary values for External IDs. The following values cannot be used for External IDs:
  • NA
  • NULL
  • -1
  • 0
  • 1
  • all
  • 00000000-0000-0000-0000-000000000000

​
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, you can do the following to remove the user context:
  • Call OneSignal.logout() → clears External ID, removes previous user properties (Tags, Aliases, etc.), 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