Setting Up Facebook

Cost Aggregation
Set up data connector

Attribution Integration
Configure tracking and postbacks

SKAdNetwork Data
Set up SKAN integration

Ad Mon Aggregation
Set up ad mon data connector

Data Discrepancy
Compare Singular & Facebook data

Multiple SDKs
Use both Singular & Facebook

Update [Oct 27th, 2021]: Singular supports Facebook's new Install Referrer measurement solution for Android app installs. To take advantage of this feature, enter your Install Referrer Decryption Key in Singular (see Configure Facebook as a Partner in Singular below).

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 only (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 installs only (i.e., not supported for install referrer-based installs in Android)
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

Make sure your app is integrated with Singular via an SDK or S2S integration (see Getting Started with the Singular SDK/S2S).
Accept Facebook’s Advanced Mobile Measurement Agreement. To accept the agreement or check your status, see Facebook Advanced Mobile Measurements.

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.

Configure Facebook as a Partner in Singular

Go to the Facebook App Dashboard. Find your app from your list of apps and copy the App ID.
In Singular, go to Attribution > Partner Configuration and type "Facebook" in the search box.
Enter your Facebook App ID. You can add multiple Facebook App IDs by separating them with a comma.
For Android apps only: Enter your Install Referrer Decryption Key, (see Where can Ifind the Install Referrer Decryption Key? below). This step is required for Singular to be able to attribute installs via Facebook's install referrer solution.

Specify Attribution Settings

Enable View-through Attribution if you want to give higher priority to ad views.
Enable Re-engagement Tracking if you want to use inactivity windows.
Choose your Click-through attribution lookback window to specify how long an ad can be credited with an install.
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.

Send Event Postbacks to Facebook

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

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.

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];

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

FAQ

How does Singular track Facebook attributions?

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:

In the Facebook Developers Portal, go to My Apps and select the relevant app.
Go to Basic settings and scroll down to the Android App Store section.
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.

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

California Consumer Privacy Act

Starting July 2020, Facebook allows advertisers to notify Facebook if end-users choose to limit or allow data processing for California users, using a "limit data use" flag. Learn more in Facebook's developer documentation.

Singular uses the limitDataSharing value passed to Singular SDK and S2S in integrations with CCPA-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 resident. If a limitDataSharing value is not explicitly provided, Singular defaults to notifying Facebook that "limit data use" should be applied for California residents.

For implementation details and examples, see our iOS SDK, Android SDK, and S2S API guides.