Facebook App Events

Send your event data from RudderStack to Facebook App Events.

Facebook App Events is Facebook’s event tracking functionality which lets you track events via your app or web page, including user activities such as app installation, purchases, etc.

Find the open source transformer code for this destination in the GitHub repository.

Connection compatibility

Destination info
  • Status: Generally Available
  • Supported sources: Android, iOS , Unity, AMP , Cloud, Warehouse, React Native , Flutter, Cordova, Shopify
  • Refer to it as FB in the Integrations object.

Connection modes
SourceCloud modeDevice modeHybrid mode
AMPsupportednot supportednot supported
Androidsupportedsupportednot supported
Cloudsupportednot supportednot supported
Cordovasupportednot supportednot supported
Fluttersupportednot supportednot supported
iOSsupportedsupportednot supported
React Nativesupportedsupportednot supported
Shopifysupportednot supportednot supported
Unitysupportednot supportednot supported
Warehousesupportednot supportednot supported
Websupportednot supportednot supported
Supported message types
SourceIdentifyPageTrackScreenGroupAlias
Cloud mode
Supported sourcesnot supportedsupportedsupportedsupportednot supportednot supported
Device mode
Androidsupportednot supportedsupportedsupportednot supportednot supported
iOSsupportednot supportedsupportedsupportednot supportednot supported
React Nativesupportednot supportedsupportedsupportednot supportednot supported

Get started

Once you have confirmed that the source platform supports sending events to Facebook App Events, follow these steps:

  1. From your RudderStack dashboard, add a source. Then, from the list of destinations, select Facebook App Events.
  2. Assign a name to the destination and click Continue.

Connection settings

To successfully configure Facebook App Events as a destination, you will need to configure the following settings:

APP ID: Enter your Facebook App ID. See FAQ for more information on getting your Facebook App ID.

The following settings are applicable only if you are sending events to Facebook using device mode:

Limited Data Use: Enable this setting to send the end user’s country and state information. Facebook processes the user data according to the data regulations set for that region. See Limited Data Use for more information on this setting.

info
You can allow Facebook to detect your country and state automatically by choosing the Use Facebook to detect Automatically option.

Add device mode integration

Depending on your platform of integration, follow the below steps to integrate App Events with your app.

Identify

warning
For Facebook App Events, RudderStack supports theidentify calls only in mobile device mode.

You can use the identify call to set the userId through the setUserID method from AppEventsLogger.

RudderStack sets the following properties (if available) using the setUserData method.

RudderStack propertyData typeApp Events property
traits.email
context.traits.email
Stringem
traits.firstName
context.traits.firstName
Stringfn
traits.lastName
context.traits.lastName
Stringln
traits.phone
context.traits.phone
Stringph
traits.gender
context.traits.gender
Stringge
traits.birthday
context.traits.birthday
Stringdb
traits.city
context.traits.city
Stringct
traits.state
context.traits.state
Stringst
traits.zip
context.traits.zip
Stringzp
traits.country
context.traits.country
Stringcn
warning
Make sure you pass the above properties in their specific format. Otherwise, RudderStack will ignore them and not map to any Facebook properties.

A sample identify call for an iOS application is shown below:

[[RSClient sharedInstance] identify:@"developer_user_id"
                                 traits:@{@"email": @"bar@foo.com"}];

Track

warning
This destination does not strictly adhere to the RudderStack Ecommerce Event Spec.

RudderStack logs the track call to Facebook using the logEvent method of the AppEventsLogger class. It uses the same eventName as you have passed in the track call along with all properties, after converting them into the accepted format.

A sample track call for an iOS application is as shown:.

[[RSClient sharedInstance] track:@"Accepted Terms of Service"
                      properties:@{
                          @"foo": @"bar",
                          @"foo_int": @134
                      }];
info

Whenrevenue andcurrency are present in the event properties of anytrack call, RudderStack makes aPurchase call to Facebook using itslogPurchase API along with the normaltrack call using thelogEvent API.

Ifcurrency is absent in the event properties, RudderStack sets the default value toUSD.

Supported mappings for iOS v2

This section lists some track event and property mappings which are applicable only when sending events via the iOS v2 device mode.

The following table lists the track event properties mappings between RudderStack and Facebook App Events:

RudderStack propertyFacebook App Events property
product_idContentID
ratingMaxRatingValue
nameAdType
order_idOrderID
currencyCurrency
queryQuery
descriptionDescription

The following table lists the ecommerce events mappings between RudderStack and Facebook App Events:

RudderStack eventFacebook App Events event
Products SearchedSearch
Products ViewedView Content
Product AddedAdd to Cart
Product Added To WishlistAdd to Wishlist
Payment Info EnteredAdd Payment Info
Checkout StartedInitiate Checkout
Order CompletedPurchase
Promotion ClickedIn-App Ad Click
Promotion ViewedIn-App Ad Impression
Product ReviewedRate
Spend CreditsSpent Credits

RudderStack also supports the following Lifecycle events and maps them as it is before sending them to Facebook App Events:

  • Complete Registration
  • Achieve Level
  • Complete Tutorial
  • Unlock Achievement
  • Subscribe
  • Start Trial

Page

The page method lets you record your website’s page views with any additional relevant information about the viewed page. You need not pass the event name as RudderStack automatically sets it to Viewed Page.

A sample page call using the RudderStack Android SDK is as shown:

rudderanalytics.page();
info
Thepage call is directly passed on to Facebook as atrack event via itslogEvent API, with the event name asViewed Page along with the the associated properties.

Screen

The screen call lets you record whenever your user views their mobile screen, with any additional relevant information about the screen.

A sample screen call using the RudderStack Android SDK is as shown:

[[RSClient sharedInstance] screen:@"Home" properties:@{
    @"category" : @"launcher"
}];

In the above snippet, RudderStack captures the information related to the viewed screen, such as screen name and category.

info
The abovescreen call is directly passed on to Facebook as atrack event via itslogEvent API, with the event name asViewed {screen name} screen along with the the associated properties. The above example will be sent as atrack event with nameViewed Home screen along with its properties.

Limited Data Use

In July 2020, Facebook released a Limited Data Use feature to give businesses better control over how their data is used in their California Consumer Privacy Act (CCPA) compliance efforts.

Using this, you can send the Limited Data Use data processing parameters to Facebook for each event via RudderStack, so that Facebook can appropriately apply the user’s data choice.

To use this feature, enable the Limited Data Use setting in the RudderStack dashboard and control its behavior via the following data processing parameters:

ParameterDefault ValueDescription
Data Processing Options State0Use Facebook’s geolocation to determine the end-user’s state.
Data Processing Options Country0Use Facebook’s geolocation to determine the end-user’s country.
success
Learn more about the different data processing options accepted by Facebook.

This section highlights the different consent-based options for configuring the App Events SDK.

Disable automatically logged events

Disable collection of advertiser IDs

Disable automatic SDK initialization

To disable automatic SDK initialization in case of the Android SDK, add the following to yourAndroidManifest.xml file:

<application>
  ...
  <meta-data androidname="com.facebook.sdk.AutoInitEnabled" androidvalue="false"></meta-data>
  ...
</application>

In some cases, you can delay the SDK initialization to obtain user consent or fulfill any legal obligations instead of disabling it entirely. To do so, call the class methodsetAutoInitEnabled and set it totrue to manually initialize the SDK after the end-user provides the required consent.

FacebookSdk.setAutoInitEnabled(true)
FacebookSdk.fullyInitialize()

Starting from iOS version 14.5, you need to get the device consent to share data with Facebook by setting the isAdvertiserTrackingEnabled property. Refer to Facebook’s Get device consent documentation for more information.

FAQ

Where do I get the Facebook App ID?

You can find the Facebook App ID by logging into your Facebook Developer account, and navigating to the Home page of your application’s dashboard:

Where do I get the Facebook Client Token?

You can find the Facebook Client Token by logging into your Facebook Developer account and navigating to Settings > Advanced > Security section in the application’s dashboard:


Questions? Contact us by email or on Slack