Log InSign Up

Aliases & External ID

Add your custom User IDs and Aliases within OneSignal.

Suggest Edits

📘

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.

Aliases are key-value strings made up of an alias label (the key) and an alias ID (the value). The alias label can be thought of as a consistent and static keyword across all users, while the alias ID is a specific value to identify a user for that particular label. The combined alias label and alias ID provide uniqueness to successfully identify a user.

OneSignal provides two default user aliases (the OneSignal ID and External ID) and up to 20 custom user aliases. OneSignal also identifies subscriptions (push tokens, email addresses, and phone numbers) with a Subscription ID. See Subscriptions for more details.

📘

Benefits of Aliases

  1. Identify users across different databases or platforms. Required for Integrations.
  2. Send transactional messages through our Create Notification REST API. Also see Sending Transactional Messages.
  3. Use the CSV List Upload feature to tag and segment users based on alias.
  4. Fetch, Update and Delete users through our API.
  5. Leverage Integrations.

OneSignal ID

The OneSignal ID is a UUID generated by OneSignal to represent a user. The OneSignal ID will always be associated with a Subscription ID and/or alias, otherwise it will be deleted.

New OneSignal IDs are created when:

  • a new user subscribes to your website
  • a current web subscriber clears browser cache and returns to your website
  • a new user downloads and opens your mobile app
  • a current user uninstalls and re-installs your mobile app
  • you call OneSignal.logout
  • you use the Create user API
  • you CSV upload Email Addresses and/or Phone Numbers without an external_id

The OneSignal ID will be the same for all Subscription IDs with matching External IDs. When you identify an anonymous user with OneSignal.login and the External ID already exists within the OneSignal app, the current OneSignal ID on the subscription will be 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 when the user is identified, then the original OneSignal ID and data will continue for the new Subscription ID.

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 Users for details.

External ID

The external_id is OneSignal's default and recommended alias label. This should be the main identifier you use to identify users. It is set when calling the OneSignal.login method (mobile SDK reference, web SDK reference) which will associate the current push subscription to the user that can be identified via alias external_id=YOUR_USER_EXTERNAL_ID.

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. See Users for details.

If the user is no longer identifiable in your app, the OneSignal.logout method will remove the External ID from the Push Subscription. See below FAQ for details.

📘

External IDs are Intended to be Unique Values

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

User Aliases

If you have multiple identifiers for your users and want to label them, you can set additional key : values for each alias. For example: facebook_id : 3453443, google_id : 573489307569, firebase_id : test3555.

🚧

Only External ID updates OneSignal ID

It is recommended to always use the External ID to identify users. Then if needed, add additional custom user aliases. For example:

  • User subscribes to your website, gets OneSignal ID: OSID1 and Subscription ID: SID_Web1
  • You set Alias: facebook_id : 01
  • User downloads and opens your iOS mobile app, gets OneSignal ID: OSID2 and Subscription ID: SID_iOS1
  • You try to set Alias: facebook_id : 01 this will error because this alias belongs to OSID1
  • You must call OneSignal.login to add the External ID which will replace OSID2 with OSID1
  • Then the facebook_id : 01 alias will also be set on iOS subscription ID SID_iOS1

User aliases can set with the addAlias and addAliases methods on the OneSignal.User namespace. Set the label to identify the alias and the alias id as the value. If this alias label already exists on this user (OneSignal ID), it will be overwritten with the new alias ID.

User aliases can be removed with the removeAlias and removeAliases methods on the OneSignal.User namespace. Set the alias label(s) you want to remove.

FAQ

When should I call OneSignal.logout?

The OneSignal.logout method will remove the External ID and set a new OneSignal ID on the current Push Subscription ID. This disassociates all aliases, tags, and all other data from the Push Subscription, effectively making it belong to a new anonymous user. See Users for more details.

It is only recommended to call this method if you do not want to send transactional push notifications to this device upon logout. For example, if your app sends targeted or personalized messages to users based on their aliases and its expected that upon logout, that device should not get those types of messages anymore, then it is a good idea to call OneSignal.logout.

This does not stop the subscription from receiving all push notifications, only targeted transactional messages based on the alias. You can disable push notifications to the subscription using the optOut() SDK methods:

Updated 5 days ago