The current integration with Segment enables use of OneSignal without the OneSignal SDK on iOS.

This is possible because Segment itself can detect if the user has granted push permission. It then sends data to our API with the user’s push token and any custom Data Tags.

Android and Web are currently NOT supported directly through the Segment SDK. The OneSignal SDK is required for these platforms.

Current integration steps for Integrating Segment & OneSignal

Website & Android Mobile App Setup

Websites: Follow the Web Push Quickstart flow to get started based on your site configuration.

Android: Follow the Mobile Push Quickstart flow to get started based on the Platform used.

🚧

Android & Web User Record Visibility

Android and Web Push subscribers will only show up in the OneSignal Dashboard.

iOS Mobile App Setup

iOS device records will be created through the Segment SDK. These will show up in your OneSignal dashboard and you will be able to send them push notifications.

🚧

Caution Duplicate Notifications!

Be careful not to send the same push to iOS from Segment and OneSignal. This will cause duplicate notifications.

Tagging Device Data

The OneSignal SDK Tagging methods can be used to update device tags similar to the Segment-OneSignal integration.

Sending Push Notifications

When Sending Push Messages from OneSignal, you can trigger these via the Dashboard or API. Make sure to exclude iOS if you sent notifications via Segment.

Integrating Segment & OneSignal User Records

The Segment Anonymous ID and/or User ID can be detected using the Segment SDK and sent to OneSignal as the OneSignal external_user_id.

Once this mapping is in place, you can leverage the OneSignal API Create notification endpoint to target users directly when they get added to Segment Personas and Edit tags with external user id to update device Data Tags for grouping users into OneSignal Segments.

Get the Segment User ID and send to OneSignal

Example of how to use the OneSignal SDK setExternalUserId method to add the Segment User ID to OneSignal.

// get the segment user id either anonymous or user id
let segmentUserID = analytics.user().anonymousId();

// check if push notifications are enabled, if they are, user is subscribed and has a user record in OneSignal
//https://documentation.onesignal.com/docs/web-push-sdk#ispushnotificationsenabled

OneSignal.push(function() {
  OneSignal.isPushNotificationsEnabled(function(isEnabled) {
    if (isEnabled)
        // add the segment user id to OneSignal as the "external user id"
        // https://documentation.onesignal.com/docs/web-push-sdk#setexternaluserid

        OneSignal.setExternalUserId(segmentUserID);
    else
      console.log("Push notifications are not enabled yet.");    
  });
});

Now that the Segment ID is tied to the OneSignal record, we can do 2 things:

Target users directly with notifications in real time

As soon as Segment captures the data, a request can be made to the OneSignal Create notification endpoint, to send push to the "external_user_id" (Segment User ID).

The minimum parameters needed would be:

• include_external_user_ids - which takes an array of string data (the segment user ids)
• app_id - the OneSignal App ID
• contents - the message of the push notification

Other parameters like chrome_web_image can be set as well to add an image to the push.

Example nodeJS code:

var sendNotification = function(data) {
  var headers = {
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": "Basic YOUR_ONESIGNAL_REST_API_KEY"
  };
  
  var options = {
    host: "onesignal.com",
    port: 443,
    path: "/api/v1/notifications",
    method: "POST",
    headers: headers
  };
  
  var https = require('https');
  var req = https.request(options, function(res) {  
    res.on('data', function(data) {
      console.log("Response:");
      console.log(JSON.parse(data));
    });
  });
  
  req.on('error', function(e) {
    console.log("ERROR:");
    console.log(e);
  });
  
  req.write(JSON.stringify(data));
  req.end();
};

var message = { 
  app_id: "YOUR_ONESIGNAL_APP_ID",
  contents: {"en": "English Message"},
  include_external_user_ids: ["segment user id 1","segment user id 2","segment user id 3"]
};

sendNotification(message);

Update Tags or User Attributes

Using the External User ID (Segment User ID) we can add the data to OneSignal as Data Tags which is helpful for creating groups of devices for targeting with large marketing campaigns

As users get added to Personas in Segment you may want to trigger notifications to all users within that Persona or group of users (OneSignal calls a group of users to target "segments").

The Edit tags with external user id endpoint can add tags which are custom key: value pairs of string or integer data to users

For example, a user spends $20, we can create a tag like purchases: 20

Tags can also be used in Message Personalization like adding a user's name or some custom data to a push notification.