- Send onboarding messages to users who start a free trial or subscribe.
- Re-engage churned users with surveys or discounts.
- Send transactional messages for purchases, renewals, and billing issues.
- Start a Journey the moment a user starts a trial, cancels, or hits a billing issue.
Requirements
- A RevenueCat account with the Purchases SDK in your app.
- A OneSignal app with the OneSignal SDK installed.
- To receive Custom Events, a paid OneSignal plan. Custom Events are not available on the Free plan. Tags work on every plan.
Setup
Pass the OneSignal ID to RevenueCat
RevenueCat uses the OneSignal ID to find the user in OneSignal. RevenueCat only updates users that have a OneSignal ID saved in RevenueCat.1
Set the External ID in OneSignal
Set the External ID to your main user ID with the SDK
login method.2
Get the OneSignal ID
Use the user state observer so you get the OneSignal ID whenever it changes. Getter methods are also available.
- User state observers:
- Getter methods:
3
Pass the OneSignal ID to RevenueCat
Save the OneSignal ID in RevenueCat as the
$onesignalUserId subscriber attribute. Use the RevenueCat helper method setOnesignalUserID(), or set the attribute directly.If your app already uses OneSignal, also send the OneSignal ID for existing users when they update to the new app version. See RevenueCat’s code examples.On OneSignal SDK v4 and below, RevenueCat uses the
$onesignalId attribute (the Player ID) and the setOnesignalID() helper method instead.Connect OneSignal to RevenueCat
1
Open the OneSignal integration
In the RevenueCat dashboard, open your project settings and choose OneSignal from the Integrations menu.
2
Add your OneSignal apps
Enter the App ID and App API key of the OneSignal app for each kind of purchase. See Keys and IDs to find them.
- Production: production purchases go to this app.
- Sandbox: sandbox purchases go to this app. It can be the same app as Production, or a separate app, such as the one your development builds use.
3
Choose whether to send Custom Events
Turn Send as Custom Events on to send each event as a Custom Event as well as updating Tags. It is on by default for new integrations. Turn it off if your OneSignal app is on the Free plan.
4
Set your tag names
Enter the tag names RevenueCat should use, or keep the defaults. See Tags RevenueCat sends.
Test the integration
1
Make a sandbox purchase
Install your app as a new user and complete a sandbox purchase. The event goes to the OneSignal app in the Sandbox section, so set that up first.
2
Check the OneSignal ID in RevenueCat
In RevenueCat, open the Customer View for the test user. Confirm
$onesignalUserId is listed in the user’s attributes.3
Check that the event was delivered
In the Customer View, open the test purchase in the Customer History. Confirm the OneSignal integration event exists and was delivered.
4
Check the user in OneSignal
In the Sandbox OneSignal app, go to Audience > Users & subscriptions and search for the OneSignal ID. Confirm the user has the Tags RevenueCat set. If Send as Custom Events is on, go to Data > Events & conversions and confirm the event, such as
INITIAL_PURCHASE, arrived.Tags in OneSignal now update automatically as users purchase, renew, or change their subscription.
Events RevenueCat sends
RevenueCat sends the following events. The event name is the value of thelast_event_type tag and the name of the Custom Event.
Not every store reports every event. See RevenueCat’s Events table for store support.
Tags RevenueCat sends
For every event, RevenueCat adds or updates these Tags on the user. When you create the integration, an empty tag name uses the default name. To stop sending a tag, clear its name in the RevenueCat dashboard after you create the integration. If every tag name is blank, RevenueCat sends nothing to OneSignal.active_subscription has no default name. RevenueCat sends it only after you enter a tag name for it in the RevenueCat dashboard.subscription_status tag
When an event changes the user’s subscription status, RevenueCat updates subscription_status to one of these values. For example, the NON_RENEWING_PURCHASE example below does not include it.
For customers with more than one active subscription,
subscription_status reflects only the subscription with the most recent event.
Tag examples
These examples show the tag update RevenueCat sends to OneSignal for each event.- INITIAL_PURCHASE
- TRIAL_STARTED
- TRIAL_CONVERTED
- TRIAL_CANCELLED
- RENEWAL
- CANCELLATION
- UNCANCELLATION
- NON_RENEWING_PURCHASE
- SUBSCRIPTION_PAUSED
- EXPIRATION
- BILLING_ISSUE
- PRODUCT_CHANGE
Custom Events RevenueCat sends
With Send as Custom Events on, RevenueCat sends every event in Events RevenueCat sends to OneSignal as a Custom Event, in addition to updating Tags. It is on by default for new integrations. Integrations set up before the option existed have it off until you turn it on. Each Custom Event:- Is named with the event name, such as
TRIAL_STARTEDorRENEWAL. - Goes to the same OneSignal user and app as the tag update.
- Uses the time of the event as its timestamp, such as the purchase or expiration time.
- Includes the subscription data as event properties, under the tag names you configured.
app_user_id, last_event_type, last_event_at, and any tag with a blank name. If every tag name is blank, RevenueCat sends neither the tag update nor the Custom Event.
- Start a Journey when a user triggers
TRIAL_STARTEDorBILLING_ISSUE. - Wait in a Journey until a user triggers
TRIAL_CONVERTED, then send a fallback if they don’t. - Personalize Journey messages with event properties, such as
{{ journey.first_event.properties.product_id }}when the event entered the user into the Journey. Property names match the tag names you configured in RevenueCat. - Segment users by the purchase events they triggered.
- Access to Event Streams for outbound message events (Plan limitations and overages apply)
- Access to Custom Events for inbound event syncing (Plan limitations and overages apply)
- Updated Account Plan (not available on free apps)
Custom Events
Trigger Journeys, personalize messages, and segment users with Custom Events.
FAQ
How do I know if the integration is working?
Search for the user’s OneSignal ID in Audience > Users & subscriptions and check for the Tags RevenueCat set. In RevenueCat, the Customer History shows whether each OneSignal integration event was delivered. To check Custom Events, go to Data > Events & conversions.Why are RevenueCat events not reaching OneSignal?
The most common cause is a missing or outdated OneSignal ID in RevenueCat. Confirm$onesignalUserId is set on the user in RevenueCat, and that you call login before you send it. Also check that the purchase went to the right app: sandbox purchases, including TestFlight and Google Play license testers, go to the app in the Sandbox section.
Why are my sandbox purchases updating the wrong app?
RevenueCat sends sandbox purchases to the app in the Sandbox section and production purchases to the app in the Production section. Update the Sandbox section in the RevenueCat dashboard to change where sandbox purchases go.Can I use RevenueCat Custom Events on the Free plan?
No. Custom Events require a paid OneSignal plan. On the Free plan, turn off Send as Custom Events in RevenueCat. Tag updates still work.Does RevenueCat send revenue amounts to OneSignal?
No. RevenueCat does not send prices or revenue to OneSignal. It sends subscription data, such as the product, store, status, and dates.How many tags can I set?
OneSignal limits how many Tags each user can have at once. The limit depends on your plan. See Pricing. To send fewer Tags, clear the names of the tags you don’t need in the RevenueCat dashboard.Related pages
Custom Events
Trigger Journeys, personalize messages, and segment users with events.
Tags
Store user properties and use them for segmentation and personalization.
Journey settings
Enter users into Journeys when they trigger a Custom Event.
Keys and IDs
Find your OneSignal App ID and App API key.