Amplitude

How to integrate OneSignal with Amplitude to send events and receive cohorts

👍

This Integration is supported for User Model

OneSignal is migrating from a device-centric model (player ID) to a new user-centric data model. This integration is supported if you upgrade your application to use our new user-centric APIs and SDKs. To learn more about this migration, check out the User Model Migration Guide.

Please reach out to [email protected] with any questions.

In this tutorial you’ll learn how to set up OneSignal with Amplitude to send events over and receive back intelligent behavioral cohorts.

Amplitude provides actionable, 360-degree-insight into your entire digital product and customer experience delivered across every digital team. Now you can integrate with OneSignal to send intelligent and timely notifications based on your users’ actions and behaviors.

1. Send data to Amplitude: send all of your users’ responses to your messages. This includes data across Push, In-App Messages, Email, and SMS.

2. Receive Cohorts from Amplitude: Within Amplitude you can create a whole set of cohorts based on your users' behavior and actions. Now you can sync this hourly, daily, or weekly with OneSignal.

This integration can be set up on an application basis, to ensure you have control over what application data is synced from and to Amplitude.

Use Cases

  1. Action-driven Onboarding: Prompt your user to complete signup, or other onboarding actions, through syncing a relevant cohort, to ensure they become a converted user

  2. Gamification: Provide positive reinforcement when a user completes an action within your application, for example. submitting a post or article for the first time.

Requirements

  • Accounts: If you don't already have them, sign up for an Amplitude and a OneSignal account. Amplitude's Quick Start Guide will walk you through how to set up your Amplitude organization and create your first project. To create a OneSignal account, visit www.onesignal.com.
  • OneSignal Pricing Plan: In order to use our Amplitude Integration, we ask you to please be on a Growth Plan or higher. If you need help with pricing, please check out our Pricing Page and reach out to us with any questions.
  • Amplitude Pricing: Find out more about Amplitude Price Plans.
  • The OneSignal Mobile SDK and/or Web SDK from which you want to send data. Email or SMS only integrations do not require the SDK.

1. Turn on Integration

In OneSignal, navigate to Settings > Integrations > Amplitude and click Activate.

678

Image. Showing Amplitude Integration card

2. Add Amplitude Token in OneSignal Dashboard

You can find your Amplitude API Key Token under Settings > Projects. Copy-paste the API Key into OneSignal.

1376

Image showing Amplitude API Key

If you are using Amplitude EU servers, select Send events exclusively to Amplitude EU data center.

Once done Activate your integration.

700

Image. Showing modal to add Amplitude card to enter in API Key

3. Add OneSignal to Amplitude Integrations

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

In Amplitude, navigate to Data Destinations and add OneSignal to your project.

To connect to OneSignal, name the connection (to recognize later) and copy-paste the "App ID" and "REST API Key" from the OneSignal dashboard.

Important: The User ID section refers to any Amplitude property that you want to use and needs to sync to the OneSignal External ID. This can be any property available but we recommend using the "User ID" set to Amplitude within their setUserId property.

Click Save when finished.

612

Image showing where to paste your OneSignal API Key in Amplitude

4. Sync Amplitude & OneSignal Users

Syncing users across OneSignal and Amplitude requires setting the OneSignal External ID property to the same "User ID" property set in Amplitude during step 3.

OneSignal's External ID is a user-level identifier to associate different subscriptions (Push, Email, and SMS) to the same user.

Moving Current Amplitude 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_id property which must match the selected User ID property in Amplitude.

5. Syncing your Cohorts

To export users from Amplitude to OneSignal, first create the cohort of users you wish to export. You can read more about cohorts in Amplitude here.

Once you have created the cohort, click Sync to export these users to OneSignal. You can then go into your OneSignal dashboard to use these cohorts within your segments.

1189

Image showing where to view your Active Integrations to Sync with OneSignal

Note that you can select how frequently you’d like to sync your cohorts with OneSignal. These can be done as a One-Time Sync, or on a Scheduled basis.

1102

Image showing how you can set a sync for your cohorts with OneSignal


6. How to use an Amplitude Cohort within your Segment

Cohorts you send to OneSignal are automatically created as Segments and also create a special "Amplitude" filter to be used again. See Segments for more details.

In OneSignal, navigate to Audience > Segments select New Segment.

Select Amplitude within the segment filters and choose which cohort you’d like to use.

1027

Image showing the ability to create a segment

1027

Image showing how to create a segment from an Amplitude Cohort

Name the Segment and select Create Segment

📘

OneSignal Segments Display Subscriptions, Not Users

The segment in OneSignal counts all the opted-in subscriptions associated with the user.

If your users have unsubscribed from push or email or are missing the External ID, they will not be counted in the segment.

If the External ID is set but they have no opted-in subscriptions, they are still included in the segment when using Journeys or In-app messages, they are just not shown in the segment counts.


FAQ

What Events are sent?

Below we have a table showing you what events are sent per channel.

OneSignal EventAmplitude EventAmplitude Message Event Property
Push Notification Clicked Which Opens the App/Website[OneSignal] Push ClickedMessage Name = The name of the message.

Message = Push Notification Title/Headings

Message Contents = Push Notification Message/Contents

delivery_id = OneSignal Notification Id.

message_type = push
Push Notification Sent from OneSignal[OneSignal] Push DeliveredMessage Name = The name of the message.

Message = Push Notification Title/Headings

Message Contents = Push Notification Message/Contents

delivery_id = OneSignal Notification Id.

message_type = push
Push Notification Received on Device (Confirmed Deliveries)[OneSignal] Push Confirmed deliveryMessage Name = The name of the message.

Message = Push Notification Title/Headings

Message Contents = Push Notification Message/Contents

delivery_id = OneSignal Notification Id.

message_type = push
In-App Message Clicked[OneSignal] IAM ClickedMessage Name set within OneSignal Dashboard - does not track what was clicked. Use the Click Action ID to send event to Amplitude.

message_type = in-app
In-App Message Impression (shown to user)[OneSignal] IAM DisplayedMessage Name set within OneSignal Dashboard

message_type = in-app
Email sent from OneSignal[OneSignal] Email DeliveredMessage Name = The name of the message.

Message = Subject of the email sent from OneSignal

delivery_id = OneSignal Notification Id.

message_type = email
Email opened/viewed from OneSignal[OneSignal] Email OpenedMessage Name = The name of the message.

Message = Subject of the email sent from OneSignal

delivery_id = OneSignal Notification Id.

message_type = email
Email Link Clicked[OneSignal] Email ClickedMessage Name = The name of the message.

Message = Subject of the email sent from OneSignal

delivery_id = OneSignal Notification Id.

message_type = email
SMS sent from OneSignal[OneSignal] SMS DeliveredMessage Name = The name of the message.

Message = Contents of the SMS sent from OneSignal

Message Contents = Contents of the SMS sent from OneSignal

delivery_id = OneSignal Notification Id.

message_type = sms
SMS delivered to device[OneSignal] SMS Confirmed deliveryMessage Name = The name of the message.

Message = Contents of the SMS sent from OneSignal

Message Contents = Contents of the SMS sent from OneSignal

delivery_id = OneSignal Notification Id.

message_type = sms

How can we pass Subscription events?

Subscription events are not currently being sent automatically. This can be done with the OneSignal SDK Subscription Observer Methods. See Subscription Tracking for more details.

What ID should we use?

In order to sync your data effectively between OneSignal and Amplitude, we use External ID. This allows you to recognize your user from Amplitude to OneSignal.

Additionally, External ID can be used across other integrations to ensure you have a connected data ecosystem.

Why do we set up the integration on an Application level as opposed to Organization Level?

We set up the Amplitude on an Application level, as this allows you some control over what is synced and the amount of data synced both to and from Amplitude.

Why do my cohort user counts not match the OneSignal segment counts?

There are a couple reasons for this:

  • OneSignal tracks devices while Amplitude tracks users. A single Amplitude User may have 1+ devices within OneSignal.
  • OneSignal's segments only show devices that are subscribed. Unsubscribed devices are not counted or shown in segments.
  • The channel record must already exist within OneSignal and each record needs the external_user_id Property to match the corresponding property in Amplitude.

Why does my delivery data not match between Amplitude and OneSignal?

There may be a couple reasons for this:

  • The Amplitude User Id property specified and OneSignal's External User Id property needs to be set for message data of that device to be tracked.
  • Amplitude measures Users, OneSignal measures Devices. If a user has multiple devices, the sent, clicked and confirmed events will be higher in OneSignal.