📘

You're Viewing User Model Documentation 🎉

OneSignal is in the process of migrating from a device-centric model (player ID) to a new user-centric data model (OneSignal ID). To learn more, check out the User Model Migration Guide.

Please refer to Version 9 of our documentation for device-centric information.

User

A user represents a person with one or more subscriptions to the different messaging channels of your application i.e push notifications, SMS and email. Users are automatically assigned a unique identifier called OneSignal ID. Users are considered anonymous until identified with an alias.

A user must have at least one of the following, otherwise it is deleted:

• a subscription
• an alias

User Properties

In addition to subscriptions and aliases, a user can have the following properties.

Test Subscriptions for a User

You can set a user's subscriptions as Test Subscriptions to access when sending test messages.

See Find & Set Test Subscriptions for details.

User Lifecycle

All users start as anonymous, with a OneSignal ID and a Subscription ID. When you identify a user in your app / site (via OneSignal.login) this assigns your provided ID to OneSignal's built-in alias called External ID.

For example, if a user installs your app on multiple devices (or uninstalls and reinstalls your app on the same device), each time this creates a new OneSignal ID and Subscription ID. Setting the External ID (calling OneSignal.login) every time users identify themselves will associate all data and history together under a single OneSignal user with the same OneSignal ID. See Aliases & External ID for details.

🚧

Assigning External ID and Aliases

The External ID and aliases needs to be a unique identifier for a user. Do not assign an External ID or alias to a user before you are able to uniquely identify them. Generic values such as 0, NA, NULL can not be set for an External ID.

It is recommended to always use External ID. Then if needed, add additional custom user aliases. See Aliases & External ID for details.

Anonymous user becomes a new identified user

When you identify the user with OneSignal.login, if the External ID does not yet exist in your OneSignal app, the current anonymous user becomes a newly identified user.

New Subscription IDs will have the same OneSignal ID when calling OneSignal.login with the associated External ID.

Anonymous user identified as an already existing user

When you identify the user with OneSignal.login, if the External ID already exists in your OneSignal app, then the current anonymous user’s data automatically merges to the existing identified user.

The anonymous OneSignal ID is deleted and the identified OneSignal ID is set on the Subscription ID.

Data tags set on the anonymous user will be merged and existing tag values will be updated on the identified OneSignal ID.

Identified user becomes an anonymous user

Calling OneSignal.logout method removes the OneSignal ID and sets an anonymous OneSignal ID on the current Push Notification Subscription ID.

Data tags and Aliases are disassociated with the Push Notification Subscription ID and new anonymous OneSignal ID.

Email, SMS and any other Push Notification Subscription IDs remain with the identified OneSignal ID. They are not transferred to the new anonymous OneSignal ID.

User deletion

You can delete users via their OneSignal ID, External ID or custom aliases. This deletes all Subscription IDs and data associated with the user. More details in the Delete Users guide.

Example User Lifecycles

Common examples and recommendations on how to address users in OneSignal.

Login User (Recommended)

It is recommended to call OneSignal.login as soon as you identify the user in your app, even before adding the email and/or phone number subscriptions or custom user aliases. The login method associates the OneSignal ID and External ID with all Subscription IDs for that user.

1. A new User1 downloads your app on Android. This creates:
   1. a new OneSignal ID (example OSID1).
   2. a new Android Subscription ID (example SID_Android1).
2. User1 identifies themself and you call OneSignal.login to set an External ID (example EID1).
   1. The user is identified and has OneSignal ID (OSID1), External ID (EID1), and Subscription ID (SID_Android1).
3. User1 provides you their email address and phone number which you set with OneSignal.User.addEmail and OneSignal.User.addSms.
   1. An Email Subscription ID (SID_Email1) and SMS Subscription ID (SID_Sms1) are created.
   2. The user1 OneSignal ID (OSID1), External ID (EID1) has 3 Subscription IDs: SID_Android1, SID_Email1, and SID_Sms1.
4. This same User1 subscribes to your website. This creates:
   1. a new OneSignal ID (example OSID2).
   2. a new Web Push Subscription ID (SID_Web1).
   3. The web subscription and OneSignal ID are currently anonymous.
5. User1 logs in to identify themself on your website. You call OneSignal.login with the same identifier used on the mobile app.
   1. The External ID (EID1) is set on this Subscription (SID_Web1).
   2. The current OneSignal ID (OSID2) is replaced with User1's original OneSignal ID (OSID1).
   3. User1 is identified and has OneSignal ID (OSID1), External ID (EID1), and 4 Subscription IDs: SID_Web1, SID_Android1, SID_Email1, and SID_Sms1.

Creating Email & SMS Subscriptions Before Login

It is recommended to identify the user with OneSignal.login before adding custom user aliases, email addresses and/or phone number subscriptions. However, if your app allows anonymous users to provide email addresses and phone numbers, this is what to expect.

1. A user downloads your app on iOS. This creates:
   1. a new OneSignal ID (example OSID3).
   2. a new iOS Subscription ID (example SID_iOS3).
2. The user provides their email address and phone number which you set with the SDK methods: OneSignal.User.addEmail and OneSignal.User.addSms .
   1. A new Email Subscription ID (SID_Email3) and new SMS Subscription ID (SID_Sms3) is created.
   2. The Email and SMS Subscription IDs gets the same OneSignal ID (OSID3).
3. The user logs in to identify themself in the iOS app as User1. You call OneSignal.login with External ID EID1.
   1. The iOS Push Subscription (SID_iOS3) gets External ID (EID1) and OneSignal ID (OSID1).
   2. However, OSID3 is still set on the Email and SMS Subscriptions.
   3. You will need to call OneSignal.User.addEmail and OneSignal.User.addSms again to add these subscriptions to OSID1.

🚧

Login only sets the OneSignal ID on the Push Subscription

If you add the Email and/or Phone number before calling OneSignal.login you will need to call addEmail/addSms again to set the Email and Phone number Subscription IDs to the current OneSignal ID.

Notes on CSV and API Imports

If you import your existing email addresses and phone numbers using the Import Phone Numbers CSV, Import Email Addresses CSV or Create user API without setting an External ID. This creates:

1. a new OneSignal ID.
2. a new Email or SMS Subscription ID.

It is always recommended to include the identified external_id in your CSV uploads to associate the Subscription with a User or use the Create subscription API if the user is already known in OneSignal.

If you imported the data without an known External ID, these subscriptions will be "fixed" to the identified OneSignal ID and External ID under the following situations:

1. Calling the SDK OneSignal.User.addSms/addEmail methods on the mobile apps or website with the same phone number/email address you imported.
2. Use the CSV Upload options again with the external_id column and correct ID.
3. Use the Update user API.