ο»Ώ

The OneSignal integration is available on the [Pro](πŸ”—ο»Ώ) plan.

OneSignal can be a useful integration tool for understanding what stage a customer is in to react accordingly. RevenueCat can automatically update user tags in OneSignal with their latest subscription status.

With our OneSignal integration, you can:

  • Send an onboarding campaign to a user in a free trial

  • Send a push notification to churned users and [offer them a discount](πŸ”—ο»Ώ)

With accurate and up-to-date subscription data in OneSignal, you'll be set to turbocharge your campaigns ⚑️

For every auto-renewing subscription event in RevenueCat, the following tags get added or updated on the user in OneSignal. By leaving the tag blank in the RevenueCat dashboard, you can choose to not send any value for specific tag(s).

TagDescription
`app_user_id`The RevenueCat App User Id that triggered the event
`period_type`The latest period type for the purchase or renewal. Either: - `TRIAL` (for free trials) - `INTRO` (or introductory pricing) - `NORMAL` (standard subscription)
`purchased_at`epoch time in seconds of the latest subscription purchase or renewal
`expiration_at`epoch time in seconds of the latest subscription expiration date
`store`Either `APP_STORE `, `PLAY_STORE`, or `STRIPE`
`environment`Either `SANDBOX` or `PRODUCTION`
`last_event_type`The latest event type from the user. Either: - `INITIAL_PURCHASE` - `TRIAL_STARTED` - `TRIAL_CONVERTED` - `TRIAL_CANCELLED` - `RENEWAL` - `CANCELLATION `
`product_id`The latest subscription product identifier that the user has purchased or renewed
`entitlement_ids`Comma separated string of RevenueCat Entitlement identifiers that the user unlocked
`active_subscription`The value will be set to `true` on any purchase/renewal event, and `false` on `EXPIRATION`
`grace_period_expiration_at`If a billing issue occurs we will send the date of the grace period expiration.

Auto-renewing subscriptions only

RevenueCat only updates data tags in OneSignal in response to auto-renewing subscription events.

# Events

The OneSignal integration tracks the following events:

EventDefault Event NameDescriptionApp StorePlay StoreAmazonStripePromo
Initial Purchaseinitial_purchaseA new subscription has been purchased.βœ…βœ…βœ…βœ…βŒ
Trial Startedtrial_startedThe start of an auto-renewing subscription product free trial.βœ…βœ…βœ…βœ…βŒ
Trial Convertedtrial_convertedWhen an auto-renewing subscription product converts from a free trial to normal paid period.βœ…βœ…βœ…βœ…βŒ
Trial Cancelledtrial_cancelledWhen a user turns off renewals for an auto-renewing subscription product during a free trial period.βœ…βœ…βœ…βœ…βŒ
RenewalrenewalAn existing subscription has been renewed or a lapsed user has resubscribed.βœ…βœ…βœ…βœ…βŒ
CancellationcancellationA subscription or non-renewing purchase has been cancelled. See [cancellation reasons](πŸ”—ο»Ώ) for more details.βœ…βœ…βœ…βœ…βœ…
UncancellationuncancellationA non-expired cancelled subscription has been re-enabled.βœ…βœ…βœ…βŒβŒ
ExpirationexpirationA subscription has expired and access should be removed. If you have [Platform Server Notifications](πŸ”—ο»Ώ) configured, this event will occur as soon as we are notified (within seconds to minutes) of the expiration. If you do not have notifications configured, delays may be approximately 1 hour.βœ…βœ…βœ…βœ…βœ…
Billing Issuebilling_issueThere has been a problem trying to charge the subscriber. This does not mean the subscription has expired. Can be safely ignored if listening to CANCELLATION event + cancel_reason=BILLING_ERROR.βœ…βœ…βœ…βœ…βŒ

# 1. Send device data to RevenueCat

The OneSignal integration requires some device-specific data. RevenueCat will only update users in OneSignal if the below data has been added as [Subscriber Attributes](πŸ”—ο»Ώ) for the user.

KeyDescriptionRequired
`$onesignalId`The [OneSignal Player Id](πŸ”—ο»Ώ) for the user.βœ…

This property can be set manually, like any other [Subscriber Attributes](πŸ”—ο»Ώ), or through the helper method `setOnesignalID()`.

You can listen for changes to the OneSignal Id through their SDK, and send the value to RevenueCat. If you already have OneSignal set up, you should make sure that you're also sending the OneSignal Id for users that are updating to the latest version of your app.

ο»Ώ

# 2. Send RevenueCat events into OneSignal

After you've set up the _Purchases SDK_ to send device data to RevenueCat, you can "turn on" the integration and configure the tag names from the RevenueCat dashboard.

  1. Navigate to your project in the RevenueCat dashboard and find the _Integrations_ card in the left menu. Select **+ New**

ο»Ώ

  1. Choose **OneSignal** from the Integrations menu.

  2. Add your **OneSignal App Id** and **OneSignal API key**.

  3. Enter the tag names that RevenueCat should use, or choose the default tag names.

OneSignal configuration screen
ο»Ώ

OneSignal configuration screen

# 3. Testing the OneSignal integration

You can test the OneSignal integration end-to-end before going live. It's recommended that you test the integration is working properly for new users, and any existing users that may update their app to a new version.

## Make a sandbox purchase with a new user

Simulate a new user installing your app, and go through your app flow to complete a sandbox purchase.

## Check that the required device data is collected

Navigate the the [Customer View](πŸ”—ο»Ώ) for the test user that just made a purchase. Make sure that all of the required data from step 1 above is listed as attributes for the user.

## Check that the OneSignal event delivered successfully

While still on the Customer View, click into the test purchase event in the [Customer History](πŸ”—ο»Ώ) and make sure that the OneSignal integration event exists and was delivered successfully.

ο»Ώ

# Sample Events

Below are sample JSONs that are delivered to OneSignal for events.

ο»Ώ

Why are tags not working?

If your tags aren't working and RevenueCat is sending events successfully with 200 codes, check out [OneSignal's troubleshooting guide](πŸ”—ο»Ώ).

You've done it!

You should start seeing subscription data from RevenueCat appear on users in OneSignal.