Guides
Log InSign Up

Database, DMP, & CRM Integration

How to link your database user data with OneSignal

Suggest Edits

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. downloads your app on iOS, a 3rd player_id for the iOS Push Record is now created.
  4. provides their email. This creates a 4th email player_id record.
  5. provides their phone number, creating a 5th sms player_id record.

You have 5 records in OneSignal for the 1 User.

You can send OneSignal your unique User Id called the external_user_id and associate that with multiple player_id records. Conversely, you can get each player_id through the OneSignal SDK 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.

let externalUserId = "your User ID fetched from backend server";

OneSignal.push(function() {
  OneSignal.isPushNotificationsEnabled(function(isEnabled) {
    if (isEnabled)
      console.log("Push notifications are enabled!");
      OneSignal.setExternalUserId(externalUserId);
    else
      console.log("Push notifications are not enabled yet.");    
  });
});

String externalUserId = "123456789"; // You will supply the external user id to the OneSignal SDK

// Setting External User Id with Callback Available in SDK Version 4.0.0+
OneSignal.setExternalUserId(externalUserId, new OneSignal.OSExternalUserIdUpdateCompletionHandler() {
   @Override
   public void onSuccess(JSONObject results) {
      // The results will contain push and email success statuses
      OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "Set external user id done with results: " + results.toString());
      try {
         if (results.has("push") && results.getJSONObject("push").has("success")) {
            boolean isPushSuccess = results.getJSONObject("push").getBoolean("success");
            OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "Set external user id for push status: " + isPushSuccess);
         }
      } catch (JSONException e) {
         e.printStackTrace();
      }
      try {
         if (results.has("email") && results.getJSONObject("email").has("success")) {
            boolean isEmailSuccess = results.getJSONObject("email").getBoolean("success");
            OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "Sets external user id for email status: " + isEmailSuccess);
         }
      } catch (JSONException e) {
         e.printStackTrace();
      }
   }
   @Override
   public void onFailure(OneSignal.ExternalIdError error) {
      // The results will contain push and email failure statuses
      // Use this to detect if external_user_id was not set and retry when a better network connection is made
      OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "Set external user id done with error: " + error.toString());
   }
});

let externalUserId = "123456789" // You will supply the external user id to the OneSignal SDK

// Setting External User Id with Callback Available in SDK Version 3.x.x+
OneSignal.setExternalUserId(externalUserId, withSuccess: { results in
  // The results will contain push and email success statuses
  print("External user id update complete with results: ", results!.description)
  // Push can be expected in almost every situation with a success status, but
  // as a pre-caution its good to verify it exists
  if let pushResults = results!["push"] {
    print("Set external user id push status: ", pushResults)
  }
  if let emailResults = results!["email"] {
      print("Set external user id email status: ", emailResults)
  }
})

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.

A mobile app push player_id is generated and available shortly after a user opens the app with the OneSignal SDK initialized. Please allow 30 to 60 seconds for the player_id to be available.

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.

Then make a POST to your server with the data.

OneSignal.push(function() {
  OneSignal.isPushNotificationsEnabled(function(isEnabled) {
    if (isEnabled)
      console.log("Push notifications are enabled!");
      OneSignal.getUserId( function(userId) {
        // Make a POST call to your server with the user ID
        // Mixpanel Example
        // mixpanel.people.set({ $onesignal_user_id: userId });
      });
    else
      console.log("Push notifications are not enabled yet.");    
  });
});

// Android SDK Example addSubscriptionObserver
public class MainActivity extends Activity implements OSSubscriptionObserver {
  protected void onCreate(Bundle savedInstanceState) {
    OneSignal.addSubscriptionObserver(this);
  }
  
  public void onOSSubscriptionChanged(OSSubscriptionStateChanges stateChanges) {
    if (!stateChanges.getFrom().getSubscribed() &&
        stateChanges.getTo().getSubscribed()) {
         // The user is subscribed
         // Either the user subscribed for the first time
         // Or the user was subscribed -> unsubscribed -> subscribed
         stateChanges.getTo().getUserId();
         // Make a POST call to your server with the user ID
      }
  }
}

// iOS SDK Example addSubscriptionObserver
// AppDelegate.h
// Add OSSubscriptionObserver after UIApplicationDelegate
@interface AppDelegate : UIResponder <UIApplicationDelegate, OSSubscriptionObserver>
@end

// AppDelegate.m
@implementation AppDelegate
  
- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  // Add your AppDelegate as an obsserver
  [OneSignal addSubscriptionObserver:self];
}

// Add this new method
- (void)onOSSubscriptionChanged:(OSSubscriptionStateChanges*)stateChanges {
  
    if (!stateChanges.from.subscribed && stateChanges.to.subscribed) {
         // The user is subscribed
         // Either the user subscribed for the first time
         // Or the user was subscribed -> unsubscribed -> subscribed
         stateChanges.to.userId
        // Make a POST call to your server with the user ID
    }
}

// iOS SDK Example addSubscriptionObserver
// AppDelegate.swift
// Add OSSubscriptionObserver after UIApplicationDelegate
class AppDelegate: UIResponder, UIApplicationDelegate, OSSubscriptionObserver {

   func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
      // Add your AppDelegate as an obsserver
      OneSignal.add(self as OSSubscriptionObserver)
   }

   // Add this new method
   func onOSSubscriptionChanged(_ stateChanges: OSSubscriptionStateChanges!) {
      if !stateChanges.from.subscribed && stateChanges.to.subscribed {
         // The user is subscribed
         // Either the user subscribed for the first time
         // Or the user was subscribed -> unsubscribed -> subscribed
         stateChanges.to.userId
        // Make a POST call to your server with the user ID
      }
   }

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:

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".

Updated almost 3 years ago

What’s Next