Amplitude

Learn how to integrate OneSignal with Amplitude to sync user cohorts and message events for smarter, behavior-based notifications across push, email, SMS, and in-app channels.

OneSignal + Amplitude Integration Overview

Integrate OneSignal with Amplitude to send detailed message events, custom events, and import behavioral user cohorts. This enables real-time targeting based on user behavior to improve onboarding, re-engagement, and conversion.

Key benefits

• Send message events to Amplitude: Track delivery, clicks, failures, and more across push, in-app, email, and SMS.
• Send custom events to OneSignal: Send your custom events from Amplitude to OneSignal.
• Import cohorts from Amplitude: Automatically sync behavior-based cohorts into OneSignal as filters for targeting.

This is an app-level integration, giving you granular control over which apps and events are linked.

---

Requirements

• Amplitude Account
• OneSignal Paid Plan
• OneSignal app with Users and External ID set.

This integration does not create users. It maps the users in Amplitude to those in OneSignal.

---

Setup

Add Amplitude to OneSignal

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

Amplitude Integration card in OneSignal

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.

Amplitude settings in OneSignal

Add OneSignal to Amplitude

In your Amplitude Destinations, search for OneSignal.

Add OneSignal Destination in Amplitude

Options:

• Cohorts: Sync cohorts from Amplitude to OneSignal.
• Events User Properties: Send custom events from Amplitude to OneSignal.

Once you select either or both options, you will be prompted to enter the following information:

• Name: How you identify the destination in Amplitude. Set this to something identifiable like OneSignal - APP_NAME where APP_NAME is the name of the app in OneSignal.
• App ID: The OneSignal App ID. Available in OneSignal Settings > Keys & IDs
• API Key: The OneSignal API Key. Available in OneSignal Settings > Keys & IDs

Send events

Beta feature. You must have the Custom Events feature enabled in OneSignal to send custom events to OneSignal.

Enable this option if you would like to send custom events from Amplitude to OneSignal. Select the Amplitude Events that you would like to send to OneSignal.

Amplitude Events to send to OneSignal

USER ID mapping

This step is essential for cohort syncing and event tracking to work properly.

To match users across both systems:

• Use a shared identifier: The External ID in OneSignal must match an Amplitude User ID Property selected (like user_id).
• Verify that the selected user property exists across your Amplitude and OneSignal User Profiles.

Additional properties

You can send additional properties to OneSignal that will be included in the custom events.

This is helpful for processing events in OneSignal only if they contain a specific property.

Click Save when finished.

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

---

Testing custom events

1. In the Amplitude > OneSignal Events Destination, click the Test Connection button.

Amplitude > OneSignal Events Destination

2. Make sure the "user_id" in the payload is set to an existing User’s External ID in your OneSignal App.
3. Click the Send Test Event button
4. The Response box should remain empty and you should see a message that says "OneSignal has successfully received test event."

Response example

If you get an error, make sure your OneSignal App ID and REST API key are added to Amplitude correctly and the app is configured for custom events.

5. In OneSignal, navigate to Data > Custom Events and you should see the test event in the list.

Custom Event in OneSignal

If you do not see the event, make sure the "user_id" is set to an existing User’s External ID in your OneSignal App.

Custom events are now being sent from Amplitude to OneSignal! Learn more about how to use Custom Events.

If you have any questions or feedback on this early access integration, you can reach out to [e-mail].

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 previous step.

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:

1. In Amplitude, create a cohort. See Amplitude’s docs on cohorts.
2. Click Sync and choose OneSignal as the destination.
3. Choose sync frequency.

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

OneSignal Segment creation

• The synced cohort appears in OneSignal as an Amplitude Segment filter.
• A Segment for the cohort will automatically be created if the following conditions are met:
  • The users in the Amplitude Cohort also exist in OneSignal with matching External ID.
  • 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.

How to create a Segment from an Amplitude Cohort

Common questions:

• Why don’t my cohort & segment counts match?
• Do unsubscribed users sync from Amplitude?

---

Track message events in Amplitude

Once connected, OneSignal will send message events to Amplitude in real time.

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.

Message Event Kind (OneSignal)	Message Event Name (Amplitude)	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
Push Failed	[OneSignal] Push Failed	Push failed to be sent. Check the failed message report in OneSignal.
Push Unsubscribed	[OneSignal] Push Unsubscribed	The Subscription unsubscribed from push.
In-App Impression	[OneSignal] IAM Displayed	In-App Message successfully displayed on device
In-App Clicked	[OneSignal] IAM Clicked	In-App Message clicked on device
In-App Page Displayed	[OneSignal] IAM Page Displayed	In-App Message page is displayed
Email Sent	[OneSignal] Email Sent	Email successfully sent
Email Received	[OneSignal] Email Confirmed delivery	Email received by recipient
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 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 Suppressed	[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 Failed	[OneSignal] SMS Failed delivery	SMS failed to send
SMS Delivered	[OneSignal] SMS Confirmed deliveery	SMS successfully delivered
SMS Undelivered	[OneSignal] SMS Undelivered	The SMS could not be sent.

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
Message 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)

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

---

FAQ

Why don’t my cohort & segment counts match?

1. Missing or mismatched External IDs Only users with a matching OneSignal External ID and Amplitude User ID are included. This integration doesn’t create users or subscriptions.

2. Unsubscribed users OneSignal segments only display the count for subscribed Subscriptions. Unsubscribed Subscriptions are 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:

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

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

Do unsubscribed users sync from Amplitude?

Yes, but they are excluded from the OneSignal segment counts at this time. You can still message them via Journeys or In-app messsages if they have other Subscriptions or their Subscription type supports it.

Why doesn’t delivery data match?

A single user may have multiple Subscriptions (push devices, email addresses, phone numbers). Each Subscription generates its own delivery event. For example:

• 1 user = 2 Android + 1 iOS + 2 Web = 5 push Subscriptions
• 1 push message = up to 5 sent/received/clicked events

Use the subscription_id in event properties to trace the exact source.

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.

How can we send user/subscription events?

User and subscription-level events (e.g., permission granted, user login/logout) are not automatically sent.

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 expects a device_id for deduplication. OneSignal uses subscription_id for this, which maps into device_id automatically.

See Amplitude’s docs for more information.

---