Facebook 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 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 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 Partner Integrations Glossary)

Partner Facebook
Partner Type Self-attributing ad network + install referrer attribution in Android
Creatives Supported
Publisher Supported
View-Through Supported for self-attributed installs and re-engagements
i.e., not supported for install referrer-based installs in Android
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 for self-attributed and iOS AEM re-engagements only. Android install referrer is only supported for installs.
S2S N/A
Click Tag No (Self-attributing)
Receiving All Installs Recommended (Self-attributing)
Receiving All Events Recommended (Self-attributing)

Setup Instructions

To set up Facebook attribution tracking for an application:

Prerequisites

1

Set up Facebook Install Ads

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

Create a Facebook Mobile Install Ad: Singular supports tracking Mobile Install Ads on Facebook's Audience Network. To create your ad, consult the Facebook Mobile App Install Ads tutorial.

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). This step is required for Singular to be able to attribute installs via Facebook's install referrer solution.

    fb_decryption_key.png

3

Specify Attribution Settings

  1. Enable View-through Attribution if you want to give higher priority to ad views.
  2. Enable Re-engagement Tracking if you want to use inactivity windows.
    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 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 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.
How does Singular attribute installs where Facebook offers both self-attribution data and install referrer-based data?

Singular prioritizes the install referrer to measure attributions. If the install referrer is not available or loses due to last-click methodology to a Facebook self-attributed conversion, Singular uses the self-attributing claim. This maximizes the availability of user-level data for our customers while providing the most accurate aggregate measurement of your Facebook campaigns.

This maximizes the available user-level insights, but also ensures Singular’s aggregate reporting of your Facebook campaigns is complete.

Why are there discrepancies between install referrer-based attributions and Facebook self-attribution?

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

  • The Google Install Referrer only measure 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 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.
  • 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
  • Differences in attribution methodology: Google Install Referrer is only from clicks that occurred on that device. Facebook self-attribution supports cross-device claims for Facebook users with multiple devices.
  • Google Install Referrer only supports Google Play Store, it is not supported for third party app stores.
Is Facebook’s Install Referrer solution available for iOS campaigns?

Facebook’s Install Referrer solution is supported through Google’s Install Referrer framework, which is only available on Google-enabled Android devices.

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

To access 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.
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.

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.

Aggregated Event Measurement FAQ

(App AEM) 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.

(App AEM) 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
(App AEM) 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
(App AEM) 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. 
(App AEM) How does Meta’s App AEM work with SKAdNetwork?
Meta’s App AEM and SKAdNetwork are two separate measurement methodologies.

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.

Partner Data Policies

As a Facebook Mobile Measurement Partner, Singular adheres to the following data handling requirements. Note that these policies only apply to Facebook's self-attributed conversions (not install referrer-based conversions).

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