Facebook Ads

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.

Integration at a Glance

Includes Revenue	Supports Negative Revenue	Sends Sandbox Events	Includes Customer Attributes	Sends Transfer Events	Optional Event Types
✅	❌	Requires sandbox Client Token and sandbox App ID	❌	❌	❌

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 Attribute 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)
$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)

⚠️Android ID deprecation

Due to policy changes from the Play Store, Android ID is no longer collected by RevenueCat's Android SDKs starting on versions 6.9.8+, 7.11.1+, and later major versions.

Therefore, Google's Advertising ID acts as the primary device identifier for Android devices in RevenueCat and when connecting with third-party integrations.

These properties can be set manually, like any other Attribute, 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.

Swift

import AdSupport

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

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

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

// Optionally set additional user data
Purchases.shared.attribution.setEmail("test@example.com")
Purchases.shared.attribution.setPhoneNumber("+16505551234")

Flutter

// NOTE: There is no official Facebook Ads plugin for Flutter. 

// NOTE: You can find a community-supported alternative for the SDK here: https://github.com/oddbit/flutter_facebook_app_events

// Automatically collect the device and advertising identifiers
Purchases.collectDeviceIdentifiers() 

// Set the Facebook anonymous Id
Purchases.setFBAnonymousID()

Kotlin

//..
Purchases.configure(this, "public_sdk_key")
//..
  
// Automatically collect the $gpsAdId and $ip values
Purchases.sharedInstance.collectDeviceIdentifiers()

// Optionally set additional user data
Purchases.sharedInstance.setEmail("test@example.com")
Purchases.sharedInstance.setPhoneNumber("+16505551234")

React Native

// 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.setLogLevel(Purchases.LOG_LEVEL.DEBUG);
Purchases.configure({ apiKey: <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("test@example.com");
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:

Swift

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

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

You can see Facebook's App Events Reference here.

3. Send RevenueCat events into Facebook Ads Manager

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

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

2. Choose Facebook from the Integrations menu.
3. Add your Facebook App ID for production events (and optionally an App ID for sandbox events).
4. 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.
5. (Optional) You can toggle between different names for Facebook events.
6. Select whether you want sales reported as gross revenue (before app store commission), or after store commission and/or estimated taxes.

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 Events Manager, 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 Events Manager dashboard.

Events Manager

The events sent from RevenueCat will appear throughout Facebook Events Manager 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.

Advanced Matching

RevenueCat will send Customer information that you specify as Attributes to Facebook. This information includes email, name, phone number, etc. Make sure the Automatic Advanced Matching toggle is turned on under your app settings.

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.

2. 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.