Facebook Ads integration setup

Effective October 29th, 2021, only aggregate reporting is available to advertisers. This means that both view-through and click-through attribution data appear as “restricted” in raw data reports. Other fields related to the media source aren't populated. See Raw data content restriction. 

This applies to all advertisers, operating systems, and MMPs. It relates to the device-level data for all iOS and Android users, regardless of ATT consent status or ads personalization.

AppsFlyer continues to receive device-level data from Facebook, meaning that our attribution and reporting abilities (including multi-touch attribution, LTV, ROI, cohort, retention reports, fraud protection, Audiences, and other services) remain unchanged. See aggregate and analytics reporting tools.

How to get user-level data for Android installs?

Although user-level data is restricted, Facebook Ads shares campaign metadata with advertisers for Android app ads that direct to Google Play Store. In this case, attribution fields are available to advertisers in the Google Install Referrer which must be integrated into your app. The fields provided via the referrer populate AppsFlyer raw data reports available to you once the decryption key is submitted and an install is attributed to Facebook Ads. This enables AppsFlyer to attribute users who don't have an advertising ID (LAT-enabled). 

Campaign attribution fields available via the referrer:

• Ad ID
• Ad name
• Adset ID
• Adset name
• Campaign ID
• Campaign name
• Account ID
• Channel

Note! AppsFlyer SDK must be V5.4.0+ for the referrer data to be passed properly. Referrer data has priority over data provided by API and isn't restricted. This solution applies to click-through attribution and not view-through attribution.  

Data in the referrer is encrypted by Facebook and is decrypted using a key available to you in your Facebook developer account. You must provide us with the decryption key described in the actions required row. The decryption key needs to be submitted only once per app.

Note that if the key is not provided or was deleted, there are some cases in which Facebook Ads is still attributed for the install based on the referrer - even without the campaign attribution fields (mentioned in the list above). This happens when:

• Facebook Ads didn’t claim the install
• The Facebook install referrer was received but wasn’t decoded
• And this was the last click.
  

To get your decryption key from Facebook:

1. Log in to your Facebook developer portal.
2. Navigate to My Apps in the upper right-hand corner.
3. Select the app for which you would like to access your decryption key.
4. Navigate to Settings > Basic on the left-hand side of the page.
   

   

5. Scroll down to the Android section and you will see your decryption key labeled Install Referrer decryption key underneath the Package Names field. Note: This is the same section in which you configured your package name and the Google Play Store.

To set the decryption key in AppsFlyer:

1. [Mandatory] Verify that AppsFlyer SDK V5.4+ is adopted in your app. Don't rely on earlier versions.
2. In AppsFlyer, go to Configuration > Integrated Partners.
3. Select Facebook.
   

   

4. In the Integration tab, paste the key in Install Referrer Decryption Key. This needs to be done only once per app.
5. Click Save integration.

Enabling the Facebook Cost feature gets you the cost data for your Facebook campaigns, adsets, ads, and channel levels. It also gets you the aggregated clicks and impressions data for them. See the ad network cost integration table for full details on the supported dimensions, metrics, and features. Note: Cost data requires an Xpend subscription. 

To enable the cost API:

1. Make sure you are logged into the Facebook user account, which is enabled to handle the account's campaigns on Facebook. The user signing in must have permission to run all the campaigns in Facebook Business Manager.
2. Go to the Cost tab.
3. Turn on Get Cost, Clicks and Impressions Data.
4. Click the Facebook Login button.
5. When prompted, allow AppsFlyer to access your Facebook campaign data.
   Note: In the first data sync after integration, as well as subsequent syncs, AppsFlyer receives Facebook cost data for up to the last 7 days retroactively.

Read more about how Facebook defines clicks and views.

To delete a connected Facebook account: In the actions column, hover over an account and click Delete connection.

Cost data sync status

View your cost API status and the last time AppsFlyer managed to pull matching cost data in either the cost (and ad revenue) integration status dashboard, or in the individual ad network dashboard.

Facebook allows you to sync several accounts for pulling cost data. For each synced account, AppsFlyer shows the status of cost integration and the last time AppsFlyer managed to pull matching cost data.

Learn more about enriching your Facebook information with cost, clicks and impressions data.

To map in-app events:

1. Turn on In-App Event Postbacks.
   When enabling the Facebook in-app events mapping for an app for the first time, af_app_open is automatically mapped to session_start.
2. Fill in the following parameters:

   Parameter Name	Description
   SDK Event Name	The name of the event, as received by AppsFlyer either from the SDK integrated in your app, or from server-to-server events. Tip - Don't see the event you want in the list? Make sure to activate the event on a device with a non-organic installation and recheck. You can also type the event name, click Create custom, and map normally. Read more about custom event mapping.
   Partner Event Identifier	Select the most suitable predefined Facebook event tag for your event. You can also send Facebook CUSTOM events.
   Sending option	Select the sending option for the event: This partner only for events coming only from users attributed to Facebook Ads. All media sources, including organic to have your entire user base available to be reported to Facebook Ads.
   Send Revenue	No values & no revenue: sends only the event itself without the event value. Values & no revenue: sends all the parameters excluding the revenue value. Values & revenue: sends all the event parameters, including the revenue value (if exists in the event).

3. To add an SDK event to the list, click Add Event.

Limitations regarding event names:

• Length limitation of event names: 2-40 characters 
• The following characters are not allowed:
  • Colon (:)
  • Period (.)
  • Non-Latin (English) character sets: As of January 12, 2020, Facebook rejects Chinese characters. AppsFlyer has not tested other character sets and you should use these only after verifying with Facebook if they support these character sets in postbacks. 
• Event names are case-sensitive. To avoid discrepancies, make sure you use the correct case in the event names for all media sources and app versions.

Learn more about Facebook Ads in-app event mapping.

AppsFlyer retargeting attribution for Facebook lets advertisers attribute an existing user's engagement with a Facebook ad, and measure the quality of the user, post engagement, using the AppsFlyer reports.

It should be used only if you are actively running campaigns targeted at your own users in Facebook.

1. Turn on retargeting in the App Settings page.
2. On Facebook Ads partner page, turn on Re-engagement attribution.
3. Set the Re-engagement click-through lookback window.
   The re-engagement lookback window is the period of time, starting from ad click, during which the app must be launched for the click to be recorded as a re-engagement.
   Select a lookback window in hours or days, and set the slider to the desired value.
4. Set the Re-engagement window.
   This is the period when the user's in-app events are attributed to the retargeting media source, as primary source.
   You can set the value in days (1-90), hours (up to 23), or even lifetime. The default is 30 days.
   

   

Learn more about AppsFlyer retargeting attribution.

Learn more about deep linking users from SRNs such as Facebook.

Complying with CCPA privacy regulations limits the data coming from Facebook users based in California, USA.

To enable compliance with CCPA: Turn on Limit Facebook use of users' personal information (CCPA) in the Integration tab.

Learn more about CCPA compliance.

If your app uses Facebook Audience Network Ad Revenue for ad monetization, you can record your revenues from Facebook on AppsFlyer. This, with or without in-app purchase revenue data, gives you a complete picture of your user revenues.

To start recording Facebook Audience Network Ad Revenue:

1. On the Ad Revenue tab, set Get Ad Revenue Data to ON.
2. Select the type of aggregated ad revenue data you want to receive: Attributed revenue and/or Aggregated monetization revenue:
   • Attributed Revenue: Revenue based on the user acquisition source.
     Set the Event Source, which is the event representing your ad revenue model in the best possible way. For example, if your revenue is based on impressions, it is recommended to send AppsFlyer an ad_viewed event. The best event can be configured for each monetization platform separately. However, it is also possible to use the af_app_opened event. In this case, ad revenue is attributed for every app open performed by the user.
   • Aggregated monetization revenue: Revenue based on the ad source.
3. The Ad Revenue Event is displayed. It is a read-only field presenting the new ad revenue event called [source event]_monetized (for example, Ad_Watched_Monetized as displayed above). The ad revenue event is presented in the dashboard as an additional event.
4. Click Connect to Facebook to enable collection of Facebook Audience Network Ad Revenue on Facebook. Log in with your Facebook credentials to authorize Facebook Audience Network Ad Revenue.
5. Enter the Audience Network App ID (Facebook App ID). Get this from Facebook Audience Network (FAN).
   • Get the Facebook App ID.
   • Copy the ID to the Audience Network App ID field in AppsFlyer.
6. Click Save ad revenue.

Enable Facebook Ads to perform various actions and to access your data according to the available permissions.

Learn more about granting permissions to integrated partners.