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 have up to 20 subscriptions and is identified by a unique OneSignal ID.

Initially, users are anonymous until identified using an External ID, enabling tracking across platforms and devices.

---

User properties

OneSignal ID

The OneSignal ID is a UUID v4 generated by OneSignal to represent a user. It cannot be manually edited but may change when the External ID is assigned.

A OneSignal ID is created in the following scenarios:

• A user downloads or re-installs and opens your mobile app.
• A current user uninstalls, re-installs, and opens your mobile app.
• A user subscribes to your website.
• A current web user clears browser cache and returns to your website.
• You create a user or Subscription without setting an External ID like using our Create user API or CSV Import.
• You remove the External ID, like calling OneSignal.logout.

The OneSignal ID will be the same for all Subscriptions with matching External IDs. When you identify a user with OneSignal.login and the External ID already exists within the OneSignal app, the current OneSignal ID on the Subscription will be deleted and replaced with the identified OneSignal ID.

If a user uninstalls and re-installs your mobile app on the same device or clears browser cache and returns to your website, a new OneSignal ID and Push Subscription ID will be created. If you call OneSignal.login, then the original OneSignal ID and data will continue for the new Subscription.

Email and SMS subscriptions created with the OneSignal.User.addEmail and OneSignal.User.addSms methods will also be associated with the current OneSignal ID. See Mobile SDK reference and Web SDK reference for details on these methods.

External ID

The External ID is a unique String identifier that you assign to a user to track them consistently across Subscriptions. It is typically mapped to a user's ID in your own systems (such as a database ID or unique username).

Set the External ID via our frontend SDK's OneSignal.login method or through our Create user, Create alias (by subscription), and Transfer subscription APIs. Remove it from a subscription via the OneSignal.logout method.

📘

External IDs should be unique values

Generic values such as -1, 0, 1, NA, NULL, null, UNQUALIFIED cannot be set for an External ID.

Anonymous vs. identified users

Users without an External ID are considered anonymous, meaning each of their Subscriptions will have a different OneSignal ID and their data (like tags, sessions, language, country, etc) will not sync under the user. Once you identify the user by setting the External ID, then the OneSignal ID and data will sync across all their Subscriptions.

The below examples illustrate how this works.

Scenario: No External ID

• User subscribes to your website: OneSignal ID OSID1.
• Same user downloads your app: OneSignal ID OSID2.
• Result: The user has two separate profiles in OneSignal.

Scenario: With External ID

• User subscribes to your website and is assigned External ID EIDA: OneSignal ID OSID1.
• Same user downloads your app and is assigned the same External ID EIDA.
• Result: The two profiles merge into one: OneSignal ID OSID1.

Best practices

1. Always set an External ID to consolidate user profiles.
2. Avoid generic placeholder values for External IDs.
3. Use OneSignal.login for seamless tracking across platforms.
4. Only the External ID can update OneSignal ID. Set custom Aliases after you call OneSignal.login.

Multiple users on same device

Let's examine a scenario where two users share a device. It should be understood that when a user downloads and opens your app, a push Subscription is created with a Subscription ID and OneSignal ID. The Subscription ID represents the device (the push token) and the OneSignal ID represents the user.

First, you identify UserA by setting the External ID via the OneSignal.login method. This assigns OneSignal ID (OSID1) to be associated with UserA. Any data tags or other user data is now associated with OSID1.

When you send messages, if using segments or filters, the device (Subscription ID) will be sent the message as long as it fits the audience. If you send targeted messages directly to UserA then this Subscription ID and all other subscriptions tied to UserA will be sent the message.

If someone else uses your app on the same device, then you must call OneSignal.login to identify that new user (UserB) on the device. This will assign a new OneSignal ID (OSID2) to UserB and transfer the Subscription ID to UserB.

If a user logs out of the app, you can use the OneSignal.logout() method. This will remove the External ID and set the OneSignal ID to something anonymous. The Subscription ID can still receive messages, but it will not have the data tags or other user data associated with any user. If you want to prevent the Subscription from receiving any push notifications, use the optOut method to disable push at the OneSignal level, and then call optIn method when a user logs back in.

---

Monthly active users

For billing purposes, a Monthly Active User (MAU) is defined as a mobile push Subscription that has opened the app within the past 30 days. Mobile push Subscriptions are created when a user:

1. Opens the app on the device for the first time with the OneSignal SDK or
2. If they uninstall and re-install the app, then open it on the same device.

For example, if a User has multiple Subscriptions and has been active in the past 30 days on all of them:

• iOS mobile push Subscription
• Android mobile push Subscription
• Web push Subscription
• Email Subscription
• SMS Subscription

You would be billed for two MAUs, for both the iOS and Android mobile push Subscriptions. Email and web push Subscriptions do not count toward MAU billing.

If the user uninstalls and re-installs the app on the same Android device in that 30 day period, it would create a new Android Subscriptions, equalling three MAUs.

If you have a use case where you do not want to count every mobile push Subscription towards billing, for example, your app has a paywall and only want to include paying users. You can:

1. Add our user consent method setConsentRequired() to prevent our SDK from creating a Subscription.
2. When you want to count the Subscription towards MAU, call the setConsentGiven() method which will initialize our SDK to create the Subscription.
3. It is recommended to also call the login() method at this time to set the External ID and associate the Subscription with a User.