Meta ads integration setup

At a glance: Learn about integrating Meta ads with AppsFlyer.

Meta ads setup guide

How long does it take to start attributing your Meta ads mobile app ads with AppsFlyer?

If you already have the AppsFlyer SDK integrated into your app, and already have defined your app on Meta ads, the answer is less than a minute! 

You don't need to implement Facebook Login or integrate your app with Facebook's SDK for mobile attribution. Just follow the basic step-by-step setup instructions below. Afterward, check out advanced setup options for Meta ads.

Facebook App ID

To integrate Meta ads with AppsFlyer, first, create a Facebook App ID, then retrieve it. 

To create a Facebook App ID:

  1. On Meta ads, go to your App Dashboard.
  2. Under Apps, click Create New App.
  3. Complete the name for your app, and enter a unique namespace. Make sure to add the correct platform for your app, otherwise, installs might not be attributed correctly.

To retrieve the Facebook App ID:

  1. On Meta ads, go to your App Dashboard.
  2. Click the required app.
  3. Click the App ID, appearing at the top left of the screen, to copy it.

    FB-app-id-2-blur.png

AppsFlyer attributes data per App ID. The same Facebook App ID can be used for both your Android and iOS apps. Note that for iOS 14+, Meta ads limits ad accounts to nine accounts per app.

Basic Meta ads attribution setup

To start attributing Meta ads campaigns with AppsFlyer, follow these steps:

 Watch
 Read
  1. To activate the integration with Meta ads:
    1. Go to your apps on Meta for developers.
    2. Select the app.

      FB-for-devs-app-selecrion-en_us.png

    3. To copy your app ID, click on it at the top of the screen.

      FB-for-devs-app-ID-copy-en_us.png

    4. In AppsFlyer, from the side menu, select Collaborate > Partner Marketplace
    5. Search for Meta ads and select it.
    6. Click Set up integration. You’re directed to the integration setup page.
    7. In the Integration tab, turn on Activate partner.
      Note: The toggle must stay on (activated) for as long as you work with the partner.
    8. Under General settings:

      meta_ads_general_settings2.png

    9. Click Save Integration.
  2. [optional] Configure recommended settings:

    meta_ads_install_attribution.png

    • To match with the click-through lookback window of Meta ads, set it to 7 days.
      (Note that there are some specific cases where the default is different).
    • To match Meta ads' view-through lookback window, set it to one day.
    • To attribute users who reinstall the app during the re-attribution window, turn on Reinstall attribution.
      You don't need to enable view-through attribution or configure lookback windows for reinstall attribution, as it takes its configuration from the install attribution settings.

Still not seeing results on AppsFlyer? Refer to Meta ads integration troubleshooting.

Advanced Meta ads attribution setup

With basic attribution already set up for Meta ads, it's time for some quick advanced attribution setup.

 Watch
 Read

User-level data

Meta ads restricted attribution data

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 Meta ads, 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.

Getting user-level data for Android installs and in-app events

Google Play Install Referrer API

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

Meta install referrer

In addition to the Google Play Install Referrer API, Meta install referrer allows AppsFlyer to receive ad campaign metadata from a device’s local storage. This data is used for attribution measurement. The primary differences between the Google Play Install Referrer API and the Meta install referrer are:

  • The Meta install referrer can include impression and click data, whereas the Google Play Install Referrer API is limited to click data
  • The Meta install referrer potentially includes data from multiple sessions, whereas the Google Play Install Referrer API is limited to data from last-session only (the device must install the app in the same session as the click occurred)

As a result, you may see an increase in Meta-attributed installs in raw data reports. When an install is attributed via the Google Play Install Referrer API or the Meta install referrer, the data is available in raw data reports. The fields that may be available for attribution via the Meta install referrer populate AppsFlyer raw data reports with match type fb_referrer for attribution from the Facebook app and ig_referrer for attribution from the Instagram app. This is only available once the decryption key is submitted and an install is attributed to Meta ads. The Meta install referrer decryption key is the same key used for the Google Play Install Referrer and does not need to be provided to AppsFlyer a second time.

Campaign attribution fields available via the referrer:

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

 Note

  • For the Google Play Install Referrer API:
    • 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.
    • The Channel field is determined by the channel value received from the Google Play Referrer API (sent to Google Play by Meta). If an empty string is received, the Channel field shows "None".
  • For the Meta install referrer: Refer to the prerequisites and required actions described in the bulletin.

Meta install referrer—FAQ

In which cases is the Meta install referrer applicable for attribution?

  • For install attribution:
    • Click-through attribution, for all campaigns
    • View-through attribution is supported for all Advantage+ App Campaigns and Manual App Promotion Campaigns with broad targeting (for example, where age and gender are set to Default).
  • Compatibility: Google Play Store and non-Google Play Android app stores
  • Exclusions: This doesn't include campaigns redirecting to landing pages

What is "broad targeting" used for in Meta ads?

Broad targeting is required for receiving view-through install data. The supported campaign configuration includes:

  • Age: Default setting (18-65+) is applied
  • Gender: Default setting (All genders) is applied
  • Location: Country groups and countries are supported. Note: For more targeted locations (such as cities or zip codes) campaigns utilizing inclusion targeting with these need to be set as relaxed.
  • Detailed Targeting: Interest segments, behaviors, and advanced demographics are set as relaxed.
  • Custom Audiences: Set as relaxed.
  • For "relaxed", the "Advantage detailed targeting" box for ad campaigns must be selected:

Encrypted data from Google Play Referrer API or Meta install referrer

Data from either the Google Play Referrer API or the Meta install referrer is encrypted by Meta. This data can be decrypted using a key available to you in your Meta 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 Meta 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:

  • Meta ads didn’t claim the install
  • The data received from the Google Play Install Referrer API was received but not decoded
  • And this was the last click

To get your decryption key from Meta:

  1. Log in to your Meta 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, from the side menu, select Collaborate > Active Integrations.
  3. Select Meta ads.
    meta_ads_general_settings2.png
  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.

Cost, clicks, and impressions

meta_cost_tab.png

This integration provides aggregated data on cost, clicks, and impressions for your campaigns, adsets, ads, and geos/countries. See the ad network cost integration table for full details on the supported dimensions, metrics, and features.

Note: Data on clicks and impressions is included in the integration. However, cost data requires an ROI360 subscription.

To enable the cost API:

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

Read more about how Meta ads defines clicks and views.

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

 Notes

  • If you are already logged into Meta ads, when you click the f login button, the window immediately opens and closes. This is regular behavior.
  • If you have several users with permissions to Meta ads, the best practice is to perform the login for all of them, to avoid getting partial data.

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.

You can 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 data with cost, clicks, and impressions data.

In-app event mapping

meta_iae_postbacks.png

To map in-app events:

  1. Turn on In-app event postbacks.
    When enabling the Meta ads in-app events mapping for an app for the first time, af_app_open is automatically mapped to fb_mobile_activate_app.
  2. Fill in the following parameters:
    Parameter Name Description
    AppsFlyer event

    The name of the event, as received by AppsFlyer either from the SDK integrated into your app or from server-to-server events.
    Tip: Don't see the event you are looking for?

    • Make sure to activate the event on a device with a non-organic installation and recheck.
    • Type it in AppsFlyer event, then click Create custom. Read more about custom event mapping.
    mapped to partner event

    The unique name or ID of each event, as defined on Meta ads. Possible mapping configurations are:

    • Text field: Get the corresponding event ID from Meta ads
    • Drop-down box: Select the most suitable pre-defined AppsFlyer event.
    • As is: Send the events as they are, without name mapping.
    for users from

    Select the sending option for the event:

    • This partner only: send postbacks only when this event is attributed to Meta ads.
    • All media sources, including organic: send postbacks for events attributed to any partner and organic events.
    including
    • No data (default): send only the event itself without the event value.
    • Values and revenue: send all the event parameters, including the revenue value (if exists in the event).
    • Values without revenue: send all the parameters excluding the revenue value.
  3. To add an SDK or server-to-server 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, Meta ads rejects Chinese characters. AppsFlyer has not tested other character sets and you should use these only after verifying with Meta ads 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.

 Note

Retargeting attribution

AppsFlyer retargeting attribution for Meta ads 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 Facebook users.

  1. Turn on retargeting on the App Settings page.
  2. On the Meta 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 the lookback window units (hours or days), and set the slider to the desired value.

    re-engagement_attribution_toggle.png

  4. Enable Re-engagement view-through attribution.
  5. Set the Re-engagement view-through lookback window slider to the desired value (up to 24 hours). This is the period of time starting from an ad impression, during which the app must be launched for the impression to be recorded as a re-engagement.

    re-engagement_view-through_toggle.png

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

    re-engagement_window.png

Learn more about AppsFlyer retargeting attribution.

Learn more about deep linking users from SRNs such as Meta ads.

Comply with California Consumer Privacy Act (CCPA)

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

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

Learn more about data protection laws.

Ad revenue recording

meta_ads_ad_revenue.png

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

Record Meta Audience Network Ad Revenue

  1. On the Ad Revenue tab and turn on Get ad revenue data.
  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 Meta ads to enable the collection of Meta Audience Network Ad Revenue on Meta ads. Log in with your Meta ads credentials to authorize Meta Audience Network Ad Revenue.
  5. Enter the Audience Network App ID (Facebook App ID). Get this from Meta Audience Network.
    • Get the Facebook App ID.
    • Copy the ID to the Audience Network App ID field in AppsFlyer.
  6. Click Save ad revenue.

Permissions

Enable Meta ads to perform various actions and to access your data according to the available permissions.

Learn more about granting permissions to integrated partners.

Aggregate Event Measurement (AEM) for iOS

AppsFlyer supports the Meta ads Aggregated Event Measurement (AEM). This solution helps optimize iOS conversions and in-app events while also attributing iOS re-engagements on Meta ads.

Meta ads integration troubleshooting

If you have completed the basic integration and still not seeing results from Meta ads on the AppsFlyer dashboard, first verify that you have new installs from Meta ads since the integration.

If so, please consult the main reasons below for solving this issue:

No IDFA collection

As stated in the SDK Integration Guide - iOS, you must add the AdSupport.framework to your project for IDFA collection to take place. Check the Installation Raw Data report to see if the IDFA column is indeed empty or not. It is recommended to enable your app to collect IDFA in the case of iOS apps and GAID in the case of Android apps.
Starting iOS 14.5 you'll have to display the Apple ATT prompt and get user consent before you can collect IDFA.

Note: SKAdNetwork attribution isn't impacted by the availability of IDFA. However, make sure that you enable the iOS 14 Campaign toggle on Meta ads while setting up iOS 14 campaigns.

Wrong Facebook App ID

The Facebook App ID was configured incorrectly in AppsFlyer.
Verify that the app ID is correct and matches the value in the Meta ads dashboard.

Note - you can also use Facebook's Graph API to validate your Facebook App ID.

App status on Meta ads

The app must be defined on Meta ads as Live rather than In development for attribution to work.

fb-app-status.png

Wrong type of Meta ads campaign

Make sure the Meta ads campaign is Mobile app install ads or Mobile App Engagement. For other campaign objectives (for example, Link Click for landing pages), to measure mobile installs, the advertiser must check the App Event recording option when defining the Meta ads campaign.

Meta ads app install

When setting up the Meta ads app install campaign you can select the app from a dropdown list or paste the full store URL to the app. While both work for you on Meta ads, the second method fails AppsFlyer attribution.

Correct set-up - attribution works.

fb-app-install.png

Incorrect set-up - attribution fails.

fb-app-incorrect_setup.png

Meta ads updates

 Important!

Effective October 29th, 2021, only aggregate reporting from Meta ads is available to advertisers. This includes both installs and in-app events. This change 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.
Raw data for installs and in-app events brought before the change (October 29, 2021) continues to be available.
Note that user-level data can be received via the Google Install Referrer. 
See the news bulletin for more details.

iOS 14 updates relating to Meta ads

AppsFlyer confirms that our MMP integration with Meta ads always implements the Advertiser Tracking Enabled flag. Meaning, no action is required of you in AppsFlyer. This information is provided pursuant to the Meta ads app guidance iOS 14 checklist dated February 2021.