OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Internal Database, DMP, & CRM

How to link users to an internal database or CRM (Salesforce)

Data Integrations with OneSignal Overview

Integrating your internal data from a database, CRM or Data Management Platform (DMP) with OneSignal is an important priority with a couple things to consider.

Please see our Data Integration blog post for a great overview before getting started.

Linking Users to between your Database and OneSignal

Each device that subscribes to your website or opens your mobile app with the OneSignal SDK will get a OneSignal UUID called Player Id. This Id is tied to a device, so if a single user has multiple device records, they will have multiple Player Ids in OneSignal.

Adding Your User Id to OneSignal

You can link your own Database or CRM User Id, we call external_user_id to the device record in OneSignal using our SDK setExternalUserId method or API Edit Device Call.

It is recommended to call setExternalUserId each time the user logs-in to your app or website and you fetch their data to make sure it is accurate.
‚Äč
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.

External User Id API Limitations

OneSignal recommends updating user records directly through our SDK using our Tagging Methods.

If you want to update devices directly through our API Edit Device Call, then you will need to save the OneSignal Player Id to your database to make these calls.

Our API does not support device updates through the external_user_id.

Adding the OneSignal Player Id to your Database

If you want to update user records to OneSignal directly through our API, you must store the OneSignal Player Id to your database. Our API does not support device updates through any other Id.

To store the device's Player Id 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 use the Subscription Event handler to know when the user subscribes 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.

OneSignal.push(function() {
  OneSignal.on('subscriptionChange', function(isSubscribed) {
    if (isSubscribed) {
      // The user is subscribed
      //   Either the user subscribed for the first time
      //   Or the user was subscribed -> unsubscribed -> subscribed
      OneSignal.getUserId( function(userId) {
        // Make a POST call to your server with the user ID
      });
    }
  });
});
// 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's set in our system.
  3. Use the API Edit Device Call to update tags or external_user_id's on devices.

Updated 2 months ago


Internal Database, DMP, & CRM


How to link users to an internal database or CRM (Salesforce)

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.