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

Mixpanel

Integrating OneSignal with Mixpanel

Mixpanel and OneSignal have joined forces to provide:

Feature

Details

Personalized messaging

Boost engagement with more contextualized messaging from OneSignal, triggered when users enter or exit Mixpanel cohorts

Real-time insights

Gain a holistic view of customers by combining Mixpanel in-product user actions and OneSignal message engagement metrics

Data-driven campaigns

Leverage product-level user insights for re-engaging campaigns through OneSignal

Requirements

Step 1. Turn on Integration

Navigate to Dashboard > Settings > Analytics > Mixpanel and click Activate.

Step 2. Add Mixpanel Token in OneSignal Dashboard

You can find your Mixpanel Token under Project Settings > Access Keys. Copy-paste the Project Token into OneSignal. See Mixpanel's "Find Project Token" guide for further details.

Recommended: Select the checkbox to "Use external_user_id to sync events" if you want to send multi-channel messages (Push, Email, In-App Messages, and SMS).

If you are using Mixpanel EU servers, select Send events exclusively to Mixpanel EU servers.

OneSignal messaging events will automatically show up in the activity feed of a user in Mixpanel.

Step 3. Add OneSignal to Mixpanel Integrations

Within OneSignal, navigate to Settings > Keys & IDs. Copy the "App ID" and the "REST API key".

In your mixpanel.com dashboard > Data Management > Integrations. Select "OneSignal" and press Connect.

With your OneSignal App ID & REST API Keys input them into the Mixpanel fields and press Continue.

Step 4. Send Mixpanel the OneSignal User Id

Syncing user data across OneSignal and Mixpanel requires setting the Mixpanel User Property called OneSignal User Id ($onesignal_user_id).

Unlike Mixpanel which stores email and phone number to a single User Record, OneSignal creates separate Channel Records for push, email and sms. Emails and phone numbers need to be added into OneSignal to receive messages on those channels.

πŸ“˜

Highly Important

Option 1 is required if you plan to use multi-channel messaging and is recommended even if you only plan to use OneSignal for push notifications.

Mixpanel User Profiles without this user property ($onesignal_user_id) will not export to OneSignal - it is a requirement for user matching.

Option 1: External User Id (Recommended)

  • You must use this option for multi-channel messaging: Push, Email, In-App Messages, and SMS.
  • Email Addresses and/or SMS Phone Numbers must be added to OneSignal to receive messages.
  • You must select Use external_user_id to sync events (recommended) in step 2.
  • The Mixpanel OneSignal User Id property ($onesignal_user_id) needs to equal the OneSignal External User Id property.

OneSignal's External User Id is user-level identifier that can be associate across different OneSignal Channel Records (Push, Email, In-App Messages, and/or SMS). The below examples show how to set the Mixpanel Distinct Id as the OneSignal External User Id for the push, email, and sms phone number channel record when collected through our SDK.

The Push/In-App Message Channel Record is created when the user subscribes to push on your website or opens your mobile app with the OneSignal SDK.

The Email and SMS Channel Record needs to be sent to OneSignal using the setEmail SDK Method and setSMSNumber SDK Method shown below.

//Get the Mixpanel Distinct Id or any User Id of choice
let distinct_id = "";
mixpanel.init('YOUR PROJECT TOKEN', {
    loaded: function(mixpanel) {
        distinct_id = mixpanel.get_distinct_id();
    }
});
//Set the OneSignal External User Id to Mixpanel Distinct Id
OneSignal.push(function() {
  OneSignal.setExternalUserId(distinct_id);
  //Set Mixpanel OneSignal User Id property to Distinct Id or any User Id
  mixpanel.people.set({
    $onesignal_user_id: distinct_id
  });
});

//Set email to OneSignal and External User Id as Mixpanel Distinct Id
OneSignal.push(function() {
  OneSignal.setEmail("[email protected]")          
    .then(function() {
      OneSignal.setExternalUserId(distinct_id);
      //Set Mixpanel OneSignal User Id property to Distinct Id or any User Id
      mixpanel.people.set({
        $onesignal_user_id: distinct_id
      }); 
   }); 
});

//Set phone number to OneSignal and External User Id as Mixpanel Distinct Id
OneSignal.push(function() {
  OneSignal.setSMSNumber("+11234567890")
    .then(function() {
      OneSignal.setExternalUserId(distinct_id);
      //Set Mixpanel OneSignal User Id property to Distinct Id or any User Id
      mixpanel.people.set({
        $onesignal_user_id: distinct_id
      }); 
   });
});
//Get the Mixpanel Distinct Id or any User Id of choice
MixpanelAPI mixpanel = MixpanelAPI.getInstance(context, "MIXPANEL_PROJECT_TOKEN");
String distinctId = mixpanel.getDistinctId();
mixpanel.getPeople().set("$onesignal_user_id", distinctId);

//Set email to OneSignal
OneSignal.setEmail("[email protected]");

//Set phone number to OneSignal
OneSignal.setSMSNumber("+11234567890");

OneSignal.setExternalUserId(distinctId, new OneSignal.OSExternalUserIdUpdateCompletionHandler() {
    @Override
    public void onSuccess(JSONObject results) {
        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, "Set external user id for email status: " + isEmailSuccess);
            }
        } catch (JSONException e) {
            e.printStackTrace();
        }
        try {
            if (results.has("sms") && results.getJSONObject("sms").has("success")) {
                boolean isSmsSuccess = results.getJSONObject("sms").getBoolean("success");
                OneSignal.onesignalLog(OneSignal.LOG_LEVEL.VERBOSE, "Set external user id for sms status: " + isSmsSuccess);
            }
        } catch (JSONException e) {
            e.printStackTrace();
        }
    }

    @Override
    public void onFailure(OneSignal.ExternalIdError error) {
        // The results will contain channel 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());
    }
});
//Get the Mixpanel Distinct Id or any User Id of choice
Mixpanel.initialize(token: "MIXPANEL_PROJECT_TOKEN")
let mixpanel = Mixpanel.mainInstance()
let distinctId = mixpanel.distinctId
mixpanel.people.set(properties: ["$onesignal_user_id":distinctId])

//Set email to OneSignal
OneSignal.setEmail("[email protected]")

//Set phone number to OneSignal
OneSignal.setSMSNumber("+11234567890")

// Setting External User Id with Callback Available in SDK Version 3.x.x
OneSignal.setExternalUserId(distinctId, 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)
    }
    if let smsResults = results!["sms"] {
        print("Set external user id sms status: ", smsResults)
    }
}, withFailure: {error in
    print("Set external user id done with error: " + error.debugDescription)
})
//Get the Mixpanel Distinct Id or any User Id of choice
- (void)identify:(NSString *)distinctId
[mixpanel.people set:@{@"$onesignal_user_id": distinctId}];

//Set email to OneSignal
[OneSignal setEmail:@"[email protected]"];

//Set phone number to OneSignal
[OneSignal setSMSNumber:@"+11234567890"];
  
// Setting External User Id with Callback Available in SDK Version 3.0.0+
[OneSignal setExternalUserId:distinctId, withSuccess:^(NSDictionary *results) {
  // The results will contain push and email success statuses
  NSLog(@"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 (results["push"] && results["push"]["success"])
    NSLog(@"Set external user id push status: %@", results["push"]["success"]);
  // Verify the email is set or check that the results have an email success status
  if (results["email"] && results["email"]["success"])
    NSLog(@"Set external user id email status: %@", results["email"]["success"]);
  // Verify the number is set or check that the results have an sms success status
  if (results["sms"] && results["sms"]["success"])
    NSLog(@"Set external user id sms status: %@", results["sms"]["success"]);
}];
//Get the Mixpanel Distinct Id or any User Id of choice
const distinctId = await mixpanel.getDistinctId();
//Set Mixpanel OneSignal User Id property to Distinct Id or any User Id
mixpanel.getPeople().set("$onesignal_user_id", distinctId);

//Set email to OneSignal
OneSignal.setEmail("[email protected]");

//Set phone number to OneSignal
OneSignal.setSMSNumber("+11234567890");

OneSignal.setExternalUserId(distinctId, (results) => {
  // The results will contain push and email success statuses
  console.log('Results of setting external user id');
  console.log(results);
  
  // Push can be expected in almost every situation with a success status, but
  // as a pre-caution its good to verify it exists
  if (results.push && results.push.success) {
    console.log('Results of setting external user id push status:');
    console.log(results.push.success);
  }
  
  // Verify the email is set or check that the results have an email success status
  if (results.email && results.email.success) {
    console.log('Results of setting external user id email status:');
    console.log(results.email.success);
  }
  
    // Verify the sms phone number is set or check that the results have an sms success status
  if (results.sms && results.sms.success) {
    console.log('Results of setting external user id sms status:');
    console.log(results.sms.success);
  }
});
//Get the Mixpanel Distinct Id or any User Id of choice
let distinctId = await mixpanel.getDistinctId();
//Set Mixpanel OneSignal User Id property to Distinct Id or any User Id
mixpanel.getPeople().set("$onesignal_user_id", distinctId);

//Set email to OneSignal
OneSignal.setEmail("[email protected]");

//Set phone number to OneSignal
OneSignal.setSMSNumber("+11234567890");

// Setting External User Id with Callback Available in SDK Version 3.9.3+
OneSignal.shared.setExternalUserId(distinctId).then((results) {
  log(results.toString());
}).catchError((error) {
  log(error.toString());
});
//Get the Mixpanel Distinct Id or any User Id of choice
string distinctId = Mixpanel.DistinctId;
Mixpanel.People.Set("$onesignal_user_id", distinctId);


//Set email to OneSignal
OneSignal.SetEmail("[email protected]");

//Set phone number to OneSignal
OneSignal.SetSMSNumber("+11234567890");

// Setting External User Id with Callback Available in SDK Version 2.13.2+
OneSignal.Current.SetExternalUserId(distinctId, OneSignalSetExternalUserId);

private static void OneSignalSetExternalUserId(Dictionary<string, object> results)
{
  // The results will contain push and email success statuses
  Debug.WriteLine("External user id updated with results: " + Json.Serialize(results));
  // Push can be expected in almost every situation with a success status, but
  // as a pre-caution its good to verify it exists
  if (results.ContainsKey("push"))
  {
    Dictionary<string, object> pushStatusDict = results["push"] as Dictionary<string, object>;
    if (pushStatusDict.ContainsKey("success"))
    {
      Debug.WriteLine("External user id updated for push with results: " + pushStatusDict["success"] as string);
    }
  }
  // Verify the email is set or check that the results have an email success status
  if (results.ContainsKey("email"))
  {
    Dictionary<string, object> emailStatusDict = results["email"] as Dictionary<string, object>;
    if (emailStatusDict.ContainsKey("success"))
    {
      Debug.WriteLine("External user id updated for email with results: " + emailStatusDict["success"] as string);
    }
  }
  // Verify the number is set or check that the results have an sms success status
  if (results.ContainsKey("sms"))
  {
    Dictionary<string, object> smsStatusDict = results["sms"] as Dictionary<string, object>;
    if (smsStatusDict.ContainsKey("success"))
    {
      Debug.WriteLine("External user id updated for sms with results: " + smsStatusDict["success"] as string);
    }
  }
}

Option 2: Player Id

Only available for push and in-app messages. Not available for omni-channel: Email & SMS.

If you did not select Use external_user_id to sync events (recommended), then use the OneSignal Player Id as the OneSignal User Id Mixpanel property. However, you will not get access to Email capabilities.

Through the Mixpanel API, set this OneSignal User ID Property $onesignal_user_id to the people property.

//Set the OneSignal Push Player ID to Mixpanel record
OneSignal.push(function() {
  // Check if the current site visitor is subscribed (no player id is created until the user subscribes to push
  OneSignal.isPushNotificationsEnabled(function(isEnabled) {
    if (isEnabled) {
      console.log("Push notifications are enabled!");
      OneSignal.getUserId(function (userId) {
        console.log("OneSignal User ID:", userId);
        mixpanel.people.set({
          $onesignal_user_id: userId
        });
      });
    } else {
      console.log("Push notifications are not enabled yet.");   
    }
  });
});
//Set the OneSignal Push Player ID to Mixpanel record
OSDeviceState device = OneSignal.getDeviceState();
String userId = device.getUserId();//String: the OS Player Id or null if device has not registered with OS Servers
mixpanel.getPeople().set("$onesignal_user_id", userId);
//Set the OneSignal Push Player ID to Mixpanel record
let deviceState = OneSignal.getDeviceState()
if let userId = deviceState?.userId {
    mixpanel.people.set(properties: ["$onesignal_user_id":userId])
}

🚧

Migrating from Player Id to External User Id

  1. In OneSignal, select Use external_user_id to sync events (recommended) in step 2, then the Mixpanel OneSignal User Id property needs to equal the OneSignal External User Id property.

  2. Send Mixpanel the External User Id set within OneSignal. See example code.

Moving Current Mixpanel Subscriptions to OneSignal

You may Import Email Addresses and Import Phone Numbers into OneSignal to immediately message your userbase. Using the CSV imports or API allows you to set the external_user_id property which must match the OneSignal User Id property in Mixpanel.

🚧

Mixpanel User Data Sync

Mixpanel cohorts and analytics will not sync with OneSignal until the Mixpanel property called OneSignal User Id matches the OneSignal External User Id for the specific channel record you are messaging.

After following the above Option 1 or 2, your user data will be synced with OneSignal as follows:

User Type

Details

Push Subscribers
(Option 1 & 2)

Automatically and silently (not prompted again) moved into OneSignal upon updating the mobile app and/or returning to the website.

Email Subscribers
(Option 1 only)

After setEmail method is called and the OneSignal External User Id for the email record matches the Mixpanel OneSignal User Id property.

SMS Subscribers
(Option 1 only)

After setSMSNumber method is called and the OneSignal External User Id for the sms record matches the Mixpanel OneSignal User Id property.

Step 5. Export Mixpanel Cohorts to OneSignal

As you start sending Mixpanel the $onesignal_user_id you will see a new User Property in Mixpanel called OneSignal User Id. You can use is set to filter all devices currently associated with the OneSignal Device Record.

In Mixpanel Users > Cohorts select the 3-dot option next to the cohort you want to send push.

Select Export to... > OneSignal

Under "Export Type" you have 2 options:

  1. "One-time export" will send OneSignal the current user data. Best if sending one message only to the current users.
  2. "Dynamic Sync" is where Mixpanel will send OneSignal the updated cohort data around every 15 minutes. Best if sending recurring messages to updated user list.

Select the option and press Begin Sync.

  1. The exported Mixpanel Cohorts will show in the onesignal.com dashboard Audience > Segments as a new segment and will become available as a segment filter for further customization.

Why am I not seeing all my cohort users inside the OneSignal segment?

There are generally 3 reasons why your Mixpanel Cohort Users will not all show up inside a OneSignal Segment:

  1. The OneSignal player_id or external_user_id must be synced. Make sure you add the $onesignal_user_id to the Mixpanel user record through our SDKs. See Step 4.
  2. The device must be subscribed. Device records with an active $onesignal_user_id in Mixpanel may not be subscribed to push notifications or emails. Any device not subscribed will not be inside the OneSignal Segment.
  3. Dynamic vs One-time export. Syncing occurs every 15 minutes for Dynamic exports. You may need to wait to see all the data sync over.

You can verify this in the Mixpanel Cohort filtering All Users where OneSignal User Id is set.

🚧

Cohort - Segment User Discrepancies

Users within Mixpanel Cohorts sent to OneSignal must satisfy 2 requirements:

  1. the $onesignal_user_id property must be set on the device. See step 4.
  2. the device must be subscribed to push. OneSignal Segments only contain subscribed users.

OneSignal will also automatically sync the $first_name and $last_name user info from Mixpanel user records to our Data Tags if they are present. This is helpful for Message Personalization.

Step 6. Send Messages

See our guides on sending messages based on the channels you use. You can also setup Automated Messages.

Step 7. Tracking Message Data in Mixpanel

In Mixpanel User Activity Feed, OneSignal Message Events will appear in activity feed like:

  • Message Sent
  • App Opened from Push (clicked event)

Those have properties
time - the time the event happened
delivery_id - OneSignal notification ID
campaign_id - the heading from the notification or title from the IAM
$source - this is always onesignal
message_type - push/in-app/email/sms

Cohort Events

You can use the following events to create cohorts in Mixpanel:

OneSignal Event

Mixpanel Event

Mixpanel Message Event Property

Push Notification Clicked Which Opens the App/Website

App Opened from Push

Message = Push Notification Title/Headings

Message Contents = Push Notification Message/Contents

delivery_id = OneSignal Notification Id.

Push Notification Sent from OneSignal

Message Sent

Message = Push Notification Title/Headings

Message Contents = Push Notification Message/Contents

delivery_id = OneSignal Notification Id.

Push Notification Received on Device (Confirmed Deliveries)

Message Received

Message = Push Notification Title/Headings

Message Contents = Push Notification Message/Contents

delivery_id = OneSignal Notification Id.

In-App Message Clicked

Message Opened

Message Name set within OneSignal Dashboard - does not track what was clicked. Use the Click Action ID to send event to Mixpanel.

In-App Message Impression (shown to user)

Message Sent

Message Name set within OneSignal Dashboard

Email sent from OneSignal

Message Sent

Message = Subject of the email sent from OneSignal

delivery_id = OneSignal Notification Id.

Email opened/viewed from OneSignal

Message Opened

Message = Subject of the email sent from OneSignal

delivery_id = OneSignal Notification Id.

SMS sent from OneSignal

Message Sent

Message = Contents of the SMS sent from OneSignal

Message Contents = Contents of the SMS sent from OneSignal

delivery_id = OneSignal Notification Id.

Those have properties
time - the time the event happened
delivery_id - OneSignal notification ID
campaign_id - the heading from the notification or title from the IAM
$source - this is always onesignal.

Example Cohorts

Did not click a push or in-app message

With this type of Cohort you can track devices that may not have received your push or in-app message to send them an email or sms text.

Checking the users that did get a Message Sent greater than 1 time in the Last Day, where Message Type equals to push.
AND
Users that Did Not have the App Opened from Push (works on web as well) in the Last day.

Were Shown a Specific Message in the Past Day

Using Message Sent at least 1 time, in the Last 7 days where Message Type equals in-app and Message equals [name of the message]

In this cast the [name of the message] is pulled from:

  • Push Notification Title
  • In-App Message Name

FAQ

Do unsubscribed devices within my Mixpanel Cohort sync to OneSignal?

Devices not subscribed to push notification or emails will not show in the OneSignal segment's device count. However, sending In-App Messages will reach the unsubscribed devices.

Can I change the cohort name and have that reflected in OneSignal?

Changing the name of a synced Mixpanel Cohort will not show in OneSignal.

Upon syncing cohorts into OneSignal Segments, 2 things happen:

  1. a OneSignal Segment is created with that cohort name
  2. a Segment Data Filter is created for that cohort

The OneSignal Segment name can be changed, but the Segment Data Filter will always reflect the original name of the Mixpanel Cohort.

If you want to reflect this change, you will need to create a new Cohort in Mixpanel and sync it to OneSignal with the new name.

Can I setup an Email-only integration?

Yes, OneSignal provides ways to setup email with another ESP for you so you can use OneSignal directly for sending emails.

If you have an account with Mailgun, Mandrill or Sendgrid already, great! You can follow the above steps, except on Step 4, follow the below requirements.

Requirements:

  • You will need to create the email record in OneSignal. Use the CSV Email Import or Add a device API.
  • You will need to setup a new Mixpanel Property called "OneSignal User Id" ($onesignal_user_id). You can set this equal to the Mixpanel Distinct Id.
  • The Mixpanel OneSignal User Id property must be the same as the OneSignal External User Id property.

Updated 17 days ago



Mixpanel


Integrating OneSignal with Mixpanel

Suggested Edits are limited on API Reference Pages

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