JourneysUsersSDKIntegrations
Log InSign Up
Hey! These docs are for version 7.0, which is no longer officially supported. Click here for the latest version, 9.0!

This guide details how to sync your user data from an external Database, CRM or Data Management Platform (DMP) with OneSignal.

OneSignal creates and stores device-level data under a unique OneSignal ID called the **`player_id`**. A single user can have multiple `player_id` records based on how many devices they use to interact with your app/site.

For example, a user:

  1. downloads your app on Android, gets a unique Android Push `player_id` record

  2. subscribes to your website, a new `player_id` is created for the web push record

  3. changes to iOS and downloads your app, a 3rd `player_id` for the iOS Push Record is now created.

You have 3 records in OneSignal for the 1 User.

You can send OneSignal your unique Database/DMP User ID called the **`external_user_id`** and associate that with multiple `player_id` records. Conversely, you can get each `player_id` and send it to your Database. This guide explains both options:

## Linking Your External User ID to OneSignal Player ID

Use the OneSignal SDK [`setExternalUserId` method](🔗) when the user logs into the app/site and after the email or phone number is provided. This can be combined with [Identity Verification](🔗).

### Example Linking the External User ID

For Web Push, a `player_id` is generated when the user subscribes. You can detect if the user is subscribed using the [`isPushNotificationsEnabled` method](🔗) and set the External User ID when pulled from your server.

This same concept can be done with all of our mobile SDKs. A `player_id` on mobile is generated as soon as the user opens the app with the OneSignal SDK is initialized.


Once the `external_user_id` is set, you can:
  1. Target devices with push and email through our [Create Notification REST API Call](🔗) using the `include_external_user_ids` targeting parameter. Also see [Sending Transactional Messages](🔗).
  2. Use the CSV [List Upload](🔗) feature to tag and segment users based on the `external_user_id`'s set in our system.
  3. Update tags with our [API Edit Tags with External User ID](🔗) endpoint.
### Disassociating the External User ID
Each OneSignal SDK has the [`removeExternalUserId` method](🔗) to disassociate the `external_user_id` from the current `player_id` record. 
Warning - Android SDK Data Synchronization
The OneSignal Android SDKs leverage cacheing on `external_user_id` and [Data Tags](🔗).
If setting `external_user_id` through the [Edit device](🔗) API Endpoint, then use the same endpoint to remove the `external_user_id` upon the user logging out of the app.
The `removeExternalUserId` method will not work unless the `external_user_id` is set first with the `setExternalUserId` method on Android.
This is only applicable on the OneSignal Android Mobile App SDKs.

## Adding the OneSignal Player ID to your Database
To store the device's OneSignal Player ID to your Database, use the OneSignal SDK [User Data methods](🔗) which returns the Player ID and other available data on the device.
### Example Storing the OneSignal Player ID
For Web Push, a Player ID is generated when the user subscribes. You can detect if the user is subscribed using the [`isPushNotificationsEnabled` method](🔗) and get the OneSignal Player ID. 
Then make a POST to your server with the data.
This same concept can be done with all of our mobile SDKs. A Player ID on mobile is generated as soon as the user opens the app with the OneSignal SDK is initialized.

Once the Player ID is saved, you can:
  1. Target devices with push and email through our [Create Notification REST API Call](🔗) using the `include_player_ids` targeting parameter. See [Sending Transactional Messages](🔗).
  2. Use the [List Upload](🔗) feature to tag and segment users based on the `player_id` set in our system.
  3. Use the [API Edit Device Call](🔗) to update `tags` or `external_user_id`'s on devices.
If you haven't already done so, please see our [Data Integration blog post](🔗) for more details.

## Linking Data Between OneSignal and a Database
Other common data you want to link between your Database and OneSignal are:
  • Email Addresses - see [Import Email Addresses](🔗) for details.
  • Other Custom Data - see [Data Tags](🔗) for details on this data.
Most custom data can be stored to OneSignal in the form of [Data Tags](🔗) which are `key:value` pairs of string or integer data. We do not recommend storing array or dictionary data types as tags.
Any data tags sent to OneSignal should be for the purpose of sending notifications, either through creating [Segments](🔗) or using [API Filters](🔗).
Tags can also be used within notifications for [Message Personalization](🔗), i.e adding custom information into the push like the "username" or "last product added to cart".
Please see our [Use Cases & Best Practices](🔗) for other ideas on using tags.