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 String value assigned by you to identify and link users in OneSignal with your internal system. This helps you track users across multiple Subscriptions and consolidates multiple OneSignal IDs into one user profile.

An External ID is set via the OneSignal.login method or through the Create user API.

The External ID can be removed from the Subscription via the OneSignal.logout method.

If the External ID exists within the OneSignal app, it will have the same OneSignal ID. Note that the current push subscription will always be transferred to the currently logged in user (OneSignal ID), as they represent the current owners of that push subscription.

If the user logs out of your app and/or you can no longer identify them in your app, then call the OneSignal.logout method to remove the External ID from the Push Subscription.

📘

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 in OneSignal. 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.

---

Monthly active users

For billing purposes, a Monthly Active User (MAU) is defined as a mobile push Subscription that has been active 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.