Users

Managing your users in OneSignal.

A user represents a person with one or more subscriptions (up to 20) 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 External ID.

User properties

PropertyDescription
OneSignal IDUUID assigned by OneSignal to represent the user. Cannot be edited but may change after setting an External ID. See below for more details.
External IDOneSignal's default alias and represents an identified user. See below for more details.
Data TagsCustom event or user data. See Data Tags for more details.
LanguageThe user's preferred language. Set automatically by our mobile or web SDKs based on the device's language setting the first time the user is created. You can override this by passing in the ISO 639-1 language code to the SDK setLanguage method or language property on the Create user or Update user API.
AliasesCustom key : value strings made up of an alias label (the key) and an alias ID (the value).
Timezone IDThe timezone ID from the user's device settings when last accessing your application with the our mobile or web SDK initialized. Timezone is tracked based on IANA TZ format.
LocationGPS coordinates of the device. Location tracking must be turned on and accepted by the user. See Location-Triggered Notifications for more details.
CountryThe ISO 3166-2 country code of the IP address detected on the user's device the last time they accessed your app with our mobile or web SDK initialized.
First SessionThe first date and time the user was created within OneSignal.
PurchasesThe SKUs of "consumable" in-app purchases made by the user while the OneSignal SDK has been active in your application.

OneSignal ID

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

New OneSignal IDs are created when:

  • a new user subscribes to your website.
  • a current web subscription clears browser cache and returns to your website. Once OneSignal.login is called, the original OneSignal ID associated with the External ID will update. More details below.
  • a new user downloads and opens your mobile app.
  • a current user uninstalls and re-installs your mobile app. Once OneSignal.login is called, the original OneSignal ID associated with the External ID will update. More details below.
  • you call OneSignal.logout which removes the External ID and sets a random OneSignal ID on the Subscription.
  • you use the Create user API and do not set an external_id identity that is already associated with another OneSignal ID.
  • you CSV upload Email Addresses and/or Phone Numbers without an external_id or with an external_id that is not associated with another OneSignal ID already.

The OneSignal ID will be the same for all Subscriptions 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.

Email and SMS subscriptions created with the OneSignal.User.addEmail and OneSignal.User.addSms methods will also be associated with the current OneSignal ID.

External ID

The external_id is OneSignal's default and recommended alias label. This should be the main identifier you use to identify users across all your other platforms. It is set when calling the OneSignal.login method (mobile SDK reference, web SDK reference) or with the Create User API identity:{external_id:your-user-id} property.

externalid

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 is no longer identifiable in your app, the OneSignal.logout method will 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.

Only External ID updates OneSignal ID

It is always recommended to use the External ID to identify users because this is the only way to track a user across all their subscriptions. For example:

  • UserA subscribes to your website.
    • No External ID is set, so this user is anonymous with OneSignal ID: OSID1 and Subscription ID: SID_Web1
  • UserA then downloads your iOS mobile app.
    • Still no External ID is set, so now UserA has 2 OneSignal IDs (OSID1 , OSID2) and 2 Subscriptions (SID_Web1 and SID_iOS1).

At this point, UserA has 2 anonymous user records in OneSignal and is considered 2 different users. However, if you use our SDK’s OneSignal.login method, then both OneSignal IDs will combine into a single user:

  • UserA subscribes to your website and you set the External ID EIDA .
    • UserA is identified and has EIDA , OSID1, and SID_Web1
  • UserA then downloads your iOS mobile app and you set the same External ID (EIDA).
    • UserA has 1 OneSignal ID (OSID1) and 2 Subscriptions (SID_Web1 and SID_iOS1)

You can set custom aliases along with the External ID, but your custom aliases will not update the OneSignal ID causing users to remain anonymous and have multiple user (OneSignal ID) records. See our docs on custom Aliases for more details.