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

• An Amplitude Account
• Upgraded OneSignal Account. Not supported on free plans.
• Your OneSignal app needs Users. This integration does not create users. It maps the users in Amplitude to those in OneSignal. See our Channel setup docs to get started.
  • If using push notifications, you need the OneSignal Mobile SDK and/or Web SDK.
  • If using Email and/or SMS, you can Import email addresses and phone numbers.
• Set the OneSignal External ID to match a user ID set in Amplitude. More details below.

---

Setup

Add Amplitude to OneSignal

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

In Amplitude:

1. Find your project API Key then copy-paste it into OneSignal.
2. If using Amplitude's EU servers, check Send events exclusively to Amplitude's EU Residency Endpoint. You can verify this by your Amplitude URL. If you see eu.amplitude.com then you are using Amplitude's EU servers.

Select message events

Select which OneSignal message events you want to send to Amplitude. When finished, click Activate.

Add OneSignal to Amplitude

In your Amplitude Destinations, add OneSignal.

Set the Name as something identifiable like OneSignal - APP_NAME where APP_NAME is the name of the app in OneSignal.

You will need the following data available in OneSignal Settings > Keys & IDs :

1. App ID
2. API Key

USER ID PROPERTY

The Amplitude-OneSignal integration does not create users in OneSignal. It only maps users that exist within both platforms.

In order to map the users in OneSignal and Amplitude, you need to set the OneSignal External ID to match an available user property in Amplitude.

The User ID property refers to any Amplitude user property that has the same value as the OneSignal External ID.

Verify the User ID you selected is available in your Amplitude user profile properties.

The same value in Amplitude for the user profile property must match the External ID in OneSignal.

Click Save when finished.

👍

Integration setup complete!

You should now be able to export cohorts from Amplitude to OneSignal and collect message events from OneSignal to Amplitude.

---

Export Amplitude Cohorts to OneSignal

You can sync the users within your Amplitude cohorts to the users within OneSignal as long as they have the matching User ID/External ID property discussed in the setup instructions above. Exporting user data from Amplitude does not create the user in OneSignal, the user must already exist and have the matching External ID.

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.

The Amplitude Cohort will appear as an "Amplitude Segment filter" in OneSignal, allowing you to combine it with other filters. For a segment to also be created in OneSignal using this filter:

1. The users in the Amplitude Cohort must also exist in OneSignal with matching External ID.
2. You must not exceed your segment limit in OneSignal.

If both conditions are met, OneSignal will automatically generate a segment using the Amplitude Cohort filter and name of the Cohort.

See Segments for more details on filters.

🚧

Missing users in OneSignal?

See Why don't my cohort & segment counts match?

---

Track Message Events in Amplitude

Depending on which message events you enabled in the setup, they will be accessible within Amplitude in real time as they occur.

Message Events

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

🚧

Why doesn't my delivery data match between Amplitude and OneSignal?

See Why doesn't my delivery data match between Amplitude and OneSignal?

---

FAQ

Why don't my cohort & segment counts match?

There are two main reasons why your Amplitude Cohort user count may not match the OneSignal Segment user count:

1. Missing Users or Incorrect External ID

For users to sync between Amplitude and OneSignal, they must exist in OneSignal with the correct External ID matching the Amplitude User ID. The Amplitude integration does not create Users or Subscriptions in OneSignal. Users without an External ID or with a mismatched ID won’t sync.

Refer to Channel setup to get started creating users and subscriptions.

2. Segments Count Subscribed Subscriptions

OneSignal segments count only subscribed subscriptions. Users with unsubscribed subscriptions won’t be included in the segment but remain available for Journeys or In-app messages.

For example, if an Amplitude cohort has 10 users but the OneSignal segment shows 8 subscriptions, the 2 missing users may:

1. Not exist in OneSignal or have an incorrect External ID.
2. Have unsubscribed subscriptions.

To verify, check the Audience > Users tab in OneSignal to see if the users exist and have active subscriptions.

Do unsubscribed devices within my Amplitude Cohort sync to OneSignal?

Unsubscribed subscriptions are not counted in the OneSignal segment at this time. However, those users do exist within the segment so they will be counted if used for Journeys and unsubscribed mobile subscriptions can receive In-app messages.

Why doesn't my delivery data match between Amplitude and OneSignal?

In OneSignal, Users are identified by their External ID, which must match the Amplitude User ID for event tracking to align across platforms.

Each user can have multiple Subscriptions, for example, lets say a user has 2 Android devices, 1 iOS device, 2 web push subscriptions, 1 email address, and 1 phone number. This means the user has 7 subscriptions.

When sending messages to users, they are being sent to their eligible subscriptions. If you send a push notification to this user, it could potentially generate 5 sent events, 5 received events, and 5 click events.

In the message event properties, you should see the subscription_id property to know which subscription performed the event.

To troubleshoot missing events:

• Ensure OneSignal.login is called whenever a user is identified to set the External ID.
• Verify that OneSignal.logout isn't removing the External ID.
• Check API requests or CSV uploads that may alter the External ID.

For more details, see Users.

How can we pass user or subscription events?

User and subscription events like accepting/denying push permissions, user logging in/out, and other events are not currently being sent automatically.

The OneSignal SDK has event listeners that can be used to track these events for you to send to Amplitude:

• User State Observer: Mobile SDK , Web SDK
• Permission Observer: Mobile SDK , Web SDK

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.