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)

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 between your Database and OneSignal

Each device record in OneSignal gets a UUID called Player ID. This Player ID is generated when user subscribes to push notifications on the website or opens your mobile app with the OneSignal SDK.

This ID is tied to a device (not a user), so if a single user has multiple device records, they will have multiple Player IDs in OneSignal.

Linking Your User ID to OneSignal Player ID

Best practice is to 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.

Example Linking the External User 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 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.

let myCustomUniqueUserId = "something from my backend server";

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.push(function() {
        OneSignal.setExternalUserId(myCustomUniqueUserId);
      });
    }
  });
});

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.

Adding the OneSignal Player ID to your Database

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

For pulling OneSignal data into your database, we provide the View device or CSV export API methods.

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.

Updated 12 days 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.