Build With RevenueCat

Build a customized mobile subscription business with RevenueCat. We do the heavy lifting of normalizing subscribers from any source and maintain a single source of truth for subscription status, so you can get back to building your app.

RevenueCat is a powerful, secure, reliable, and free to use in-app purchase server with global support. All you need to get started is an API key.

Get Started    REST API Endpoints

Facebook Ads

Integrate Purchases SDK with Facebook Ads for precise revenue tracking

With our Facebook Ads integration you can:

  • Accurately track subscriptions generated from Facebook Ad campaigns, allowing you to know precisely how much revenue your campaigns generate.
  • Send trial starts, trial conversions, and renewals directly from RevenueCat to Facebook Ads Manager, allowing for accurate tracking without an app open.
  • Continue to follow your cohorts for months to know the long tail revenue generated by your campaigns.

1. Install Facebook SDK

Before RevenueCat can integrate with Facebook, your app must be running the Facebook SDK. Refer to the Facebook developer documentation for the latest installation instructions.

2. Send device data to RevenueCat

The Facebook integration requires some device-specific data. RevenueCat will only send events into Facebook Ads Manager if the below Subscriber Attributes keys have been set for the device.

Key

Description

Required

$idfa

iOS advertising identifier UUID

✅ (iOS only)

$gpsAdId

Google advertising identifier

✅ (Android only)

$fbAnonId

✅ (iOS only)

$androidId

Android device identifier

✅ (Android only)

$idfv

iOS vender identifier UUID

❌ (optional)

$ip

The IP address of the device

❌ (optional)

$email

The email address of the user

❌ (optional)

$phoneNumber

The phone number of the user

❌ (optional)

These properties can be set manually, like any other Subscriber Attributes, or through the helper methods to collectDeviceIdentifiers() and setFbAnonymousId().

❗️

Device identifiers with iOS App Tracking Transparency (iOS 14.5+)

If you are requesting the App Tracking permission through ATT to access the IDFA, you can call .collectDeviceIdentifiers() again if the customer accepts the permission to update the $idfa attribute in RevenueCat.

import AdSupport

// ...
Purchases.configure(withAPIKey: "public_sdk_key")
// ...

// Automatically collect the $idfa, $idfv, and $ip values
Purchases.shared.collectDeviceIdentifiers() 

// REQUIRED: Set the Facebook anonymous Id
Purchases.shared.setFBAnonymousID(FBSDKCoreKit.AppEvents.anonymousID)

// Optionally set additional user data
Purchases.shared.setEmail("[email protected]")
Purchases.shared.setPhoneNumber("+16505551234")
//..
Purchases.configure(this, "public_sdk_key")
//..
  
// Automatically collect the $gpsAdId, $androidId, and $ip values
Purchases.sharedInstance.collectDeviceIdentifiers()

// Optionally set additional user data
Purchases.sharedInstance.setEmail("[email protected]")
Purchases.sharedInstance.setPhoneNumber("+16505551234")
// NOTE: Facebook has officially ended support for their React Native SDK. You can read more about this here: https://developers.facebook.com/blog/post/2021/01/19/introducing-facebook-platform-sdk-version-9/

// NOTE: You can find a community-supported alternative for the SDK here: https://github.com/facebookarchive/react-native-fbsdk

// The following docs are left in place for reference

import FBSDK from "react-native-fbsdk"

//...
Purchases.setDebugLogsEnabled(true);
Purchases.setup("public_sdk_key");
//...

// Automatically collect the $idfa, $idfv, and $ip values
Purchases.collectDeviceIdentifiers();

// REQUIRED: Set the Facebook anonymous Id
const anonymousId = await FBSDK.AppEventsLogger.getAnonymousID();
Purchases.setFBAnonymousID(anonymousId);

// Optionally set additional user data
Purchases.setEmail("[email protected]");
Purchases.setPhoneNumber("+16505551234");

You should make sure to set attributes after the Purchases SDK is configured, and before the first purchase occurs. It's safe to set this multiple times, as only the new/updated values will be sent to RevenueCat.

📘

Import AdSupport Framework (iOS)

The AdSupport framework is required to access the IDFA parameter on iOS. Don't forget to import this into your project.

❗️

Remove Facebook SDK Purchase Tracking

Make sure to remove all client side tracking of revenue. Since RevenueCat will be sending events for all revenue actions, tracking purchases with the Facebook SDK directly can lead to double counting of revenue in Facebook Ads Manager.

You can disable automatic In-App Purchase event logging from the Facebook SDK or from your Facebook app dashboard. Go to the iOS/Android card under Settings > Platform > Log In-App Events Automatically > No

To continue to track install and usage events in Facebook, follow the steps in the next section.

Track Install and Usage Events

As noted above, you'll need to disable all client side tracking of revenue to prevent double counting of revenue in Facebook Ads Manager. To continue tracking install and usage events, you'll need to call Facebook's 'activate app' event after configuration:

// disable automatic tracking
FBSDKCoreKit.Settings.isAutoLogAppEventsEnabled = false

// optional: call activateApp
FBSDKCoreKit.AppEvents.activateApp()

You can see Facebook's App Events Reference here.

3. Send RevenueCat events into Facebook Ads Manager

After you've set up the Purchase SDK to send attribution data to RevenueCat, you can "turn on" the integration from the RevenueCat dashboard.

  1. Navigate to your app in the RevenueCat dashboard and choose 'Facebook' from the integrations menu.
  2. Add your Facebook App ID for production events (and optionally an App ID for sandbox events).
  3. Add the Facebook Client Token for your app (and for the sandbox App ID if included). You can find your Client Token in the Facebook dashboard under your App > Settings > Advanced > Client Token. You may need to click the 'Reset' button if there's no Client Token visible.
  4. Select whether you want RevenueCat to report proceeds (after app store cut) or revenue (gross sales).

Facebook Ads configuration screen

Event Names

RevenueCat allows you to choose from different 'Standard' Facebook event names. Using 'Standard' events is recommended by Facebook for optimizing advertising campaigns and audiences.

RevenueCat Event

Recommended Facebook Event

Trial Started

StartTrial

Trial Converted

Subscribe

Initial Purchase

Subscribe

Renewal

Subscribe

Non-Renewing Purchase

Purchase

4. Testing the Facebook Ads Manager integration

You can test the Facebook 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.

Add a sandbox App Id and sandbox Client token in the RevenueCat dashboard

Before you test the integration, make sure you have a Facebook App Id and Client Token set in the "Sandbox" fields in RevenueCat. This is required if you want the integration to trigger for sandbox purchases.

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 Facebook event delivered successfully

While still on the Customer View, click into the test purchase event in the Customer History and make sure that the Facebook integration event exists and was delivered successfully.

5. View Events in Facebook

Once events are delivered to Facebook, they can be used across Analytics, Ads Manager, and Audiences.

📘

Facebook event delay

Note that there could be up to a 24 hour delay from when events are sent to when they are shown in the Facebook Analytics dashboard.

Analytics

The events sent from RevenueCat will appear throughout Facebook Analytics as 'Standard' event types. Any events sent with revenue attached will be counted toward the 'Revenue' number in Facebook. This includes trial conversions and renewals that occur when the app isn't active.

Revenue is sent directly into Facebook Analytics

Ads Manager

Within Facebook Ads Manager, you can customize the display columns to include subscription specific metrics. The 'Subscriptions' and 'Trials Started' values will be updated by the 'Subscribe' and 'StartTrial' events sent by RevenueCat, respectively.

By tracking the subscription revenue attributed to your Facebook campaigns you can quickly spot your most effective campaigns.

Audiences

Facebook allows you to create custom audiences based off of events. This means you can create an audience of subscribers, and even create a "Lookalike" audience for better ad targeting.

To create a custom audience off of subscribers:

  1. Create a Custom Audience and select 'App activity' as the source.
  1. Choose an event, such as 'Subscribe' to create your audience off of.

👍

You've done it!

You should start seeing events from RevenueCat appear in Facebook Ads Manager.

Updated 5 days ago


Facebook Ads


Integrate Purchases SDK with Facebook Ads for precise revenue tracking

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.