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

Event Properties

These are the properties that are present on any events sent from OneSignal to Amplitude

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