Facebook (Meta) Ads Attribution Integration

 

Integration Summary

As a Facebook Mobile Measurement Partner, Singular allows app publishers to track ad download referrals from Facebook and Instagram. Once a download has been verified by Singular, you can also track subsequent user engagement of these users in your mobile app.

Singular reports on attribution data from Facebook in various ways:

  1. Facebook's self-attributing API: Singular reports user-level app activity to a dedicated Facebook API for MMPs, which is self-attributed by Facebook and attributable in Singular. Attributions through this API are subject to Facebook's data restrictions for advertisers.
  2. Facebook's "Meta Referrer" (Android only): See "Meta Referrer"
  3. Facebook's "Aggregated Event Measurement" (iOS only): See "Aggregated Event Measurement"
  4. Facebook's SKAdNetwork Reporting (iOS only): See "Facebook SKAdNetwork Integration Guide"

(See Partner Integrations Glossary)

Partner Facebook
Partner Type

Self-attributing ad network

Creatives Supported
Publisher Supported
View-Through Supported
User-Level reporting available via Android Meta Referrer, for Advantage+ App Campaigns and Manual App Promotion Campaigns with Broad Targeting
Deep Linking Singular's integration with Facebook does not use Singular tracking links (including Singular deep links). See Facebook's documentation for setting up Facebook deep links.
Re-engagement

Supported 
User-level reporting for iOS Aggregated Event Measurement (AEM) only

Click Tag No (Self-attributing)
Receiving All Installs

Recommended (Self-attributing)
Required for iOS AEM

Receiving All Events

Recommended (Self-attributing)
Required for iOS AEM

Setup Instructions

Configuring the Facebook Ads attribution integration is required to leverage all of the measurement methods with Facebook.

Prerequisites

1

Set up Facebook Ads

Register the application on Facebook: To run Facebook Mobile App Ads, the application must be registered with Facebook. Visit the Facebook App Dashboard to set up your application.

2

Configure Facebook as a Partner in Singular

  1. Go to the Facebook App Dashboard. Find your app from your list of apps and copy the App ID.

    Where to find the Facebook App ID

  2. In Singular, go to Attribution > Partner Configuration and type "Facebook" in the search box.
  3. Enter your Facebook App ID. You can add multiple Facebook App IDs by separating them with a comma.

    fb_app_id.png

  4. For Android apps only: Enter your Install Referrer Decryption Key, (see Where can I find the Install Referrer Decryption Key? below).

    Important: This step is required to use Meta Referrer for attribution.

    fb_decryption_key.png

3

Specify Attribution Settings

  1. Enable View-through Attribution if you want to attribute view-through conversions from Facebook ads.
  2. Enable Re-engagement Tracking if you want to attribute re-engagements for existing app users that engage with a Facebook ad.
    partnerconfig_settings1.png
  3. Choose your Click-through attribution lookback window to specify how long an ad can be credited with an install.
    partnerconfig_window.png
  4. Save the integration.
    Note: By saving the Facebook Ads integration configuration here, Singular automatically tracks installs and sessions to Facebook. This corresponds to the mobile_app_install and fb_mobile_activate_app events. You do not need to configure these events separately in step 6.
4

Send Event Postbacks to Facebook

Singular supports sending event notifications to Facebook with all of Facebook's requirements.

facebook_events.png

  • First, select which events to send to Facebook from the dropdown.
  • Next, map your In-app Events:

    • Select the event name on the left field, according to the name used in the SDK, and map the name to one of Facebook's predefined conversion events.
    • Alternatively, choose "(Use SDK Event Name)" to be able to use the event in Facebook's Custom Event Optimization campaigns (Android and < iOS 14 campaigns only).
    • Check the "Include Revenue Value" checkbox if relevant. If not checked, only counts of the event will be sent.

See also: Using the Facebook SDK and Singular SDK/S2S in the Same App.

5

Set Up Facebook In-App Event Requirements

Some Facebook in-app events require certain arguments to be passed to be processed by Facebook:

Facebook Event Name Required Argument(s) Supported Values
AdClick ad_type ad_type - "banner", "interstitial", "rewarded_video", "native"
AdImpression ad_type ad_type - "banner", "interstitial", "rewarded_video", "native"

For example, if you are sending an SDK event called "Click" and would like to map it to the Facebook Event Name "AdClick", ensure that "ad_type" is being sent in the "Click" event.

Android example:

Singular.event("Click", "ad_type", "banner");

iOS example:

[Singular eventWithArgs:@"Click", @"ad_type", @"banner", nil];
6

Tracking Facebook Installs in Singular

After completing the steps above, you can see the results of your Facebook Audience Network campaigns in your Singular Reporting.

Each install attributed to a Facebook Mobile App Install Ad is reported based on the Campaign Name, Ad Set, and Ad Group Name created in Facebook.

Data Mapping

Facebook values are mapped to Singular reporting dimensions as follows:

Singular Value Facebook Value Example
Tracker Campaign Name Campaign Name “MyCampaign”
Tracker Campaign ID Campaign ID 12345678
Tracker AdGroup Name AdSet Name “MyAdGroup”
Tracker AdGroup ID AdSet ID 98123747
Tracker Creative ID Ad ID 123192873

When running a Facebook report, Singular will also match the SDK data with the marketing data provided by Facebook Ads API, including:

  • Spend by Campaign
  • Spend by Creative, including the image or video
  • Account ID

General FAQ

How does Singular track Facebook attributions?

As a Facebook Mobile Measurement Partner, Singular allows app publishers to track ad download referrals from Facebook and Instagram. Once a download has been verified by Singular, you can also track subsequent user engagement of these users in your mobile app.

Singular gets attribution data from Facebook in two ways:

  • Facebook's self-attributing API: Due to Facebook's data-sharing limitation, data about installs received from this API is only available in Singular aggregate reports (not in user-level data logs).
  • Facebook's (Meta) Install Referrer Solution: This new measurement solution for Android app installs allows for data to be displayed both in Singular's aggregate reports and in user-level data logs. See Meta Referrer FAQ. 
Are communications between Singular and Facebook secure?

Singular uses all the necessary security measures required by Facebook to ensure communications between Singular and Facebook are secure. We also comply with all of the privacy policies set forth by Facebook to protect your data.

I'm still not seeing Facebook attributed installs. Where can I get help?

If you've followed the setup steps but still aren't seeing Facebook attributed installs after performing your test, contact Singular's Support Team for additional help. Provide your account name, the applicable application, and your Facebook App ID in your initial email to help ensure a quick resolution.

Where can I find an app's Facebook App ID?

You will need to have a developer account. Go to the Facebook App Dashboard. Find your app from your list of apps and copy the App ID.

Where to find the Facebook App ID

Do I need to set the AdvertiserTrackingEnabled (ATE) flag?

As part of the updates related to iOS 14, Facebook announced new guidelines for using the Advertiser Tracking Enabled flag with MMPs, including how they use the ATE flag. Your integration with Singular automatically implements this flag, and it is set for users that opt-in to tracking via iOS App Tracking Transparency. No additional action is required in your Singular SDK implementation.

What should I do if Facebook reports missing currency and value parameters for an event?

If you encounter this error from Facebook, it indicates that the event is expected to be a revenue-type event. To resolve this, ensure that when sending the event from your application using the Singular SDK, you include the required currency and value parameters. Additionally, in your Partner Configuration settings, make sure to enable 'Include Revenue Value' for this event.

Will changes to the event mapping affect historical data?

No, any changes to the event mapping will only apply from the point of configuration going forward. Historical data will not be retroactively changed.

(iOS) Aggregated Event Measurement FAQ

What is Facebook App AEM?

App AEM is a solution that helps advertisers reach more people and measure ad performance on their platform.

App AEM utilizes conversion data that Singular sends to Facebook through the MMP integration. This includes events associated with users that haven’t provided iOS's App Tracking Transparency (ATT) permission, in which case Facebook will limit processing of those events to Aggregated Event Measurement (AEM) only. App AEM supports app promotion (installs) and app engagement (re-engagement) campaigns for iOS 14 and above.

For more information about App AEM, see Facebook’s help center article.

What are the requirements to enable App AEM?

To enable AEM for “App Promotion” campaigns (installs):

  • An active Singular iOS Facebook partner configuration
    • Reporting in-app event postbacks to Facebook are optional but recommended to enable VO and AEO optimization. Note that AEM requires reporting both ATT opt-in and opt-out data to Meta, which is the default behavior with a Facebook partner configuration.
  • A configured Singular Facebook data connector
  • The AEM option will be available when creating an App Promotion campaign in Meta:

 

To enable AEM for "App Engagement" campaigns (re-engagements):

    • An iOS app that supports deep links
    • A Singular integrated app with deep link support
      • Singular SDK integration, or
        • iOS SDK 12.0.3+, or
        • iOS SDK 11.0.7+ with supportedDomains implemented for any Universal Links used in App AEM campaigns
      • Singular Server-to-Server (S2S) integration
    • An active Singular iOS Facebook partner configuration with re-engagement enabled
How does Singular attribute and report App AEM campaigns?

Singular supports reporting both installs and re-engagements (from deep links) served by App AEM campaigns.

  • AEM installs are reported in aggregate only, as “Network Installs” via the Facebook Data Connector integration
  • AEM re-engagements are reported in both user-level and in aggregate (tracker re-engagements), from deep links served by app engagement campaigns. Supported campaign granularity include:
    • Campaign ID
    • Sub Campaign ID
    • Creative ID
If I also use the Facebook SDK for iOS, what should I do to enable App Aggregated Event Measurement?
In order to avoid duplication of app events in Facebook for AEM, it is recommended that only the Singular SDK implements and passes these events to Facebook through the MMP integration. See our guide on Facebook and Singular SDK interoperability for more information. 
How does Meta’s App AEM work with SKAdNetwork?
Meta’s App AEM and SKAdNetwork are two separate measurement methodologies. Meta documents expected differences when comparing the two metholodiges in their guide on the topic.
  • App AEM utilizes app conversion data reported through Singular’s MMP attribution integration with Meta (this article)
  • SKAdNetwork utilizes Apple’s attribution framework to attribute. For more information on Singular’s integration with Meta for SKAdNetwork, read our help center article on the topic.

(Android) Meta Referrer FAQ

What is Meta Referrer?

"Meta Referrer" is an Android-specific measurement solution introduced by Facebook to allow advertisers access to granular user-level attribution data for Android app installs (see Facebook's data policies). It is comprised of the "Google Play Install Referrer" and "Meta Install Referrer" technologies for app install measurement.

Google Play Install Referrer Meta Install Referrer

(Available as of October 2021)
Uses the "Google Play Install Referrer" to attribute Android click-through installs for Meta app install campaigns through the Google Play store.

(Available as of November 2023)
In addition to supporting the same measurement scenarios as the Google Play Install Referrer, the Meta Install Referrer also supports measurement flows that are unsupported by Google Play Install Referrer:

  • most view-through attribution scenarios (Advantage+ App Campaigns and Manual App Promotion Campaigns with Broad Targeting)
  • non-Google app stores support
  • non-same session click-through attribution

"Non-same session" referes to when a user clicks on an ad and gets redirected to the app store, but doesn't immediately click "Download/Install". User returns to app store page later to click "Download/Install".

As of November 2023, Singular's integration with Meta supports both the "Google Install Referrer" and "Meta Install Referrer", under what Singular refers to as "Meta Referrer" measurement.

How does Singular attribute installs between the self-attributed data and "Meta Referrer" data?

Singular prioritizes the Meta Referrer data to measure attributions to prioritize the availability of user-level data for advertiser. For a given Android app install, Singular will prioritize the following attribution methods as follows:

  1. (Meta Referrer) Meta Install Referrer
  2. (Meta Referrer) Google Install Referrer
  3. Meta self-attributing API

Singular uses the self-attributing claim if any Meta Referrer data is not available or loses due to last-touch methodology to a Facebook self-attributed conversion. Doing so maximizes both the user-level attribution data while ensuring accurate aggregate measurement of Facebook campaigns.

How does Meta Referrer work?

Singular's "Meta Referrer" measurement consists of two install referrer technologies used by Facebook when serving Android app install ads.

Google Play Install Referrer Meta Install Referrer

When a user clicks on an advertiser's app install ad from a Facebook app install campaign, Facebook encrypts and logs the relevant ad campaign metadata (Meta referrer) and appends it to the referrer parameter in the Play Store URL. The Play Store URL redirects the user to the Play Store app product page, and the appended Meta referrer is saved by the store.

Once the resulting install completes and the user first opens the app, Singular's SDK reads the Google Play install referrer from the Play Install Referrer API to retrieve the Meta referrer from the Google Play install referrer data. The Meta referrer is then decrypted by Singular's servers for install attribution.

When a user views or clicks on an advertiser's app install ad on Facebook's app (e.g., Facebook or Instagram), Facebook's app encrypts and logs the relevant ad campaign metadata (Meta referrer) in the Facebook app's local storage layer on-device.

Once the resulting install completes and the user first opens the app, Singular's SDK reads the Meta referrer from the Meta install referrer data retrieved from the local storage layer on device. The Meta referrer is then decrypted by Singular's servers for install attribution.

Both technologies are used concurrently and alongside Singular's self-attributing integration with Meta, to arrive at a single attribution decision. See "How does Singular attribute installs between the self-attributed data and "Meta Referrer?"

What are the requirements to enable Meta Referrer for measurement?
Meta Referrer uses both "Google Play Install Referrer" and "Meta Install Referrer" for measurement. It is recommended to implement both to maximize data availability in cases where one or the other is not available.

Singular SDK and S2S Integration Requirements

  Google Play Install Referrer Meta Install Referrer

Singular SDK

Singular S2S API

 

Partner Configuration Requirements

  • Configure the Facebook partner configuration and provide the Facebook Facebook "Install Referrer Decryption Key" according to step 2.4.
Why are there discrepancies between Meta Referrer attributions and Facebook self-attributions?

Some possible reasons for discrepancies between the two measurement methods provided by Facebook are:

  • Meta Referrer is supported for limit-ad-tracked users on Android 12+, where the Google Advertising ID is not available. Facebook self-attribution is only available when the Google advertising ID is available.
  • Meta Referrer is supported for app installs only.
  • Meta Referrer is only available clicks and view that occurred on that device. Facebook self-attribution supports cross-device claims for Facebook users with multiple devices.
  • Meta Referrer is not supported for campaigns redirecting to landing pages
  • Meta Referrer supports view-through attributions, but only for broad targeting or Advantage+ App campaigns
  • If only Google Install Referrer is used, if Meta Install Referrer is not enabled:
    • Google Install Referrer only measures app installs, specifically for campaigns leading to the Play Store. Google Install referrer is not supported for user interaction with relevant ads that did not lead directly to the Play Store
    • The Google Install Referrer supports only click-through attributions, while Facebook self-attribution supports both click-through and view-through
    • The Google Install Referrer uses the referrer value immediately preceding an app download. Repeat clicks on the same ad, after download, but before first app open, will not result in an updated referrer value. Facebook’s self-attribution logic may return with the more recent touchpoint after download, but before first app open
    • Google Install Referrer only supports Google Play Store, it is not supported for third party app stores.
What is Broad Targeting and how is it relevant for Meta Referrer attribution?

Broad targeting is required to receive view-through install data via the Meta Referrer. You can find the supported campaign configuration below:

  • Age: The default setting, "18-65+" is applied
  • Gender: The default setting, "All genders", is applied.
  • Location: Regions, country groups (e.g. Asia) or specific countries are applied as the location. 
  • Detailed Targeting: If detailed targeting such as demographics, interests or behaviors are applied, opting into Advantage detailed targeting is required.
  • Custom Audiences: If Custom Audiences are applied, opting into Advantage custom audience is required



Is the Meta Referrer solution available for iOS campaigns?

Meta Referrer attribution is only available on Android devices.

Where can I find my “Install Referrer Decryption Key”?

To find your decryption key, follow these below steps:

  1. In the Facebook Developers Portal, go to My Apps and select the relevant app.
  2. Go to Basic settings and scroll down to the Android App Store section.
  3. Under Package Names, find the key labeled Install Referrer Decryption Key.

Partner Data Policies

As a Facebook Mobile Measurement Partner integrated with Facebook's self-attributing API, Singular adheres to the following data handling requirements.

Note that these policies only apply to Facebook's self-attributed conversions and do not apply to Meta Referrer conversions on Android.

Data Retention

Facebook user-level data is removed after 6 months of original attribution. After 6 months, users attributed to Facebook are treated/marked as "Organic" and reflected as such in both aggregate and user-level reporting in Singular.

Data Access

To protect end-users' privacy, Facebook does not allow advertiser access to any user-level data that is based on self-attributed conversions. Any field normally identifying a self-attributed Facebook conversion is marked as "Unattributed". 

Limited Data Use

Facebook allows advertisers to notify Facebook if end-users choose to limit or allow data processing for users in the following states in the United States, using a "limited data use" (LDU) flag:

  • California (as of July 2020)
  • Colorado (as of June 2023)
  • Connecticut (as of June 2023)

Singular uses the limitDataSharing value passed to Singular SDK and S2S in integrations with privacy-compliant partners such as Facebook. When Singular.limitDataSharing(true), Facebook will "limit data use" for this user in Facebook targeting if they are a California, Colorado, or Connecticut resident. If a limitDataSharing value is not explicitly provided, Singular defaults to notifying Facebook that "limit data use" should be applied for California, Colorado, and Connecticut residents.

For implementation details and examples, see our iOS SDK, Android SDK, and S2S API guides. For more information about the "LDU" feature, see Facebook's developer documentation