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
| Property | Description |
|---|---|
| OneSignal ID | UUID assigned by OneSignal to represent the user. Cannot be edited but may change after setting an External ID. See below for more details. |
| External ID | OneSignal's default alias and represents an identified user. See below for more details. |
| Data Tags | Custom event or user data. See Data Tags for more details. |
| Language | The 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. |
| Aliases | Custom key : value strings made up of an alias label (the key) and an alias ID (the value). |
| Timezone ID | The 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. |
| Location | GPS coordinates of the device. Location tracking must be turned on and accepted by the user. See Location-Triggered Notifications for more details. |
| Country | The 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 Session | The first date and time the user was created within OneSignal. |
| Purchases | The 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.loginis 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.loginis called, the original OneSignal ID associated with the External ID will update. More details below. - you call
OneSignal.logoutwhich 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_ididentity that is already associated with another OneSignal ID. - you CSV upload Email Addresses and/or Phone Numbers without an
external_idor 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.
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,UNQUALIFIEDcannot 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:
OSID1and Subscription ID:SID_Web1
- No External ID is set, so this user is anonymous with OneSignal ID:
- 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_Web1andSID_iOS1).
- Still no External ID is set, so now UserA has 2 OneSignal IDs (
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, andSID_Web1
- UserA is identified and has
- 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_Web1andSID_iOS1)
- UserA has 1 OneSignal ID (
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.
Updated 3 months ago