Amplitude
How to integrate OneSignal with Amplitude to send events and receive cohorts
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
-
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
-
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.
- Setting the OneSignal External ID that matches a selected Amplitude user property.
1. Turn on Integration
In OneSignal, navigate to Settings > Integrations > Amplitude and click Activate.
2. Add Amplitude Project API Key to OneSignal's Settings
You can find your Amplitude project API Key under Organization Settings > Projects > Select your project > API Key. You may need to press Show then copy-paste the API Key into OneSignal.
If you are using Amplitude EU servers, select Send events exclusively to Amplitude EU data center. You can check this by your Amplitude URL. If you see eu.amplitude.com
then you are using Amplitude's EU servers.
At this step, you'll also select which OneSignal Events you want to send back to your Amplitude project. More details on what events are available and the data properties are attached to each event.
Once you've added the API Key and selected events, you can Activate your integration.
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 your project's Data > Destinations > Add Destination 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.
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.
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.
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.
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?
These are the message event kinds that OneSignal sends to Amplitude. You can select which of these events you want to send to your Amplitude project within the OneSignal Integrations Settings.
Message Event Kind (OneSignal) | Message Event Name (Mixpanel) | Event Description |
---|---|---|
Push Sent | [OneSignal] Push Sent | Push notification successfully sent |
Push Received | [OneSignal] Push Confirmed delivery | Push notification successfully received |
Push Clicked | [OneSignal] Push Clicked | Push notification touched on device |
In-App Message Displayed | [OneSignal] IAM Displayed | In-App Message successfully displayed on device |
In-App Message Clicked | [OneSignal] IAM Clicked | In-App Message clicked on device |
In-App Message Page Displayed | [OneSignal] IAM Page Displayed | In-App Message page is displayed |
Email Sent | [OneSignal] Email Sent | Email successfully sent |
Email Opened | [OneSignal] Email Opened | Email opened by recipient |
Email Link Clicked | [OneSignal] Email Clicked | Email link clicked on |
Email Unsubscribed | [OneSignal] Email Unsubscribed | Email unsubscribed by recipient |
Email Received | [OneSignal] Email Confirmed delivery | Email received by recipient |
Email Reported As Spam | [OneSignal] Email Reported As SPAM | Email reported as spam by recipient |
Email Bounced | [OneSignal] Email Hard Bounced | Email returned to sender due to permanent error |
Email Failed | [OneSignal] Email Failed delivery | Could not deliver the email to the recipient’s inbox |
Email Supressed | [OneSignal] Email Not delivering to suppressed email address | Email not delivered as the recipient had suppressed the email address it was sent from |
SMS Sent | [OneSignal] SMS Sent | SMS sent to recipient |
SMS Delivered | [OneSignal] SMS Confirmed deliveery | SMS successfully delivered |
SMS Failed | [OneSignal] SMS Failed delivery | SMS failed to send |
Event Properties
These are the properties that are present on any events sent from OneSignal to Amplitude
PROPERTY NAME | DESCRIPTION |
---|---|
Distinct ID | The external_id associated with the message |
*delivery_id | The identifier of the discrete message |
Message Name | The message name |
Message Title | The message title |
Message Contents | The message contents |
message_type | The type of message sent, push, in-app, email, SMS |
template_id | The message template used (API and Journey Messages) |
subscription_id | The OneSignal set device/email/sms identifier |
device_type | The device type that received the message |
language | The two-character language code of the device |
source | onesignal (is indicated as the source for all events) |
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 is the OneSignal Subscription ID added to Amplitude as a device_id?
Amplitude recommends including insert_id
when sending events, as it prevents duplicate events being recorded. insert_id
is ignored if there is no device_id
.
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_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 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.
Updated about 2 months ago