Facebook Data Connector


Add the Data Connector

  1. In Settings > Data Connectors, click Add Data Connector and type and select “Facebook”.
  2. Sign in using your Facebook credentials. You may have to re-navigate to Singular and open your Data Connector again.
  3. Open your added Data Connector, activate the account from which you want to pull data, and click Submit.

Quick Details

Data Connector Technology API (Facebook Graph API and Marketing API v13.0)
Data breakdown (segmentation)

Facebook provides your data broken down by all of the following  (see Data Mapping below for terminology and more details):

  • Account
  • Campaign
  • Sub-Campaign
  • Creative

In addition, Facebook offers one of the following breakdowns:

  • Country (Default)
  • Sub Ad Network (Publisher Platform) + Placement (Platform Position): Publisher Platform is which Facebook property the ad appeared in, e.g. Facebook, Instagram, Messenger, or the Facebook Audience Network. Platform Position provides more details on where the ad was displayed, e.g., the Facebook website news feed, or the Instagram mobile news feed.
  • Platform (Impression Device): E.g., iOS, Android, or iPhone.
  • Region Region-level information (you also get the Country).
  • DMA DMA-level information (you also get the country). Only available in the USA.
  • Age & Gender: Demographic breakdowns (E.g Female/Male, 20-29, etc.)   

The default out of these is Country. If you want one of the other breakdowns instead, contact your Customer Success Manager or Singular support to configure the integration for you. You can choose the breakdown for each Account ID separately.

How far back we pull data

Every day, Singular pulls data from 7 days back. Once a week on Mondays, Singular pulls data from 30 days back.

Time zone The time zone configured for the account on Facebook.
Is data available on the creative (ad) level?


Does Singular show your creative assets?

Yes, including the multiple assets within a Dynamic Creative. Note that Singular cannot pull videos from a Facebook page for a user who is not the admin of the page.

Known Limitations/ Issues If you enable Two-Factor Authentication on a Facebook account, you must then re-authenticate the Facebook data connector in Singular.

Data Mapping

Notes on Terminology:

  • "Campaign" in Singular corresponds to "Ad Campaign" in Facebook
  • "Sub-Campaign" corresponds to Facebook's "Ad Set"
  • "Creative" corresponds to Facebook's "Ad"
  • "Asset" is a new level in the hierarchy below the Creative that corresponds to Facebook's "Asset". It is used in Dynamic Creatives, e.g., in Automated App Ads [AAA] campaigns).

For descriptions of all the fields, see the Singular Metrics and Dimensions Glossary.

Field in Singular UI Field in Singular API Field in Facebook
Account ID adn_account_id 'id' from me/adaccounts
Account Name adn_account_name 'name' from me/adaccounts
Asset ID asset_id asset_id
Campaign URL adn_campaign_url Taken from one of the Creative URLs.
Country country_field Country from Insights URL
Date date_field Given as a parameter when querying Facebook
DMA ID dma_id_field targeting[geo_locations][data][key]
DMA Name dma_name_field dma
Network Campaign ID adn_campaign_id campaign_id
Network Campaign Name adn_campaign_name 'Name' from the campaign-level endpoint
Network Creative ID adn_creative_id ad_id
Network Creative Name adn_creative_name 'Name' from ad level 
Network Sub Campaign ID adn_sub_campaign_id adset_id
Network Sub Campaign Name adn_sub_campaign_name 'Name' from the sub-campaign (ad set) level endpoint
Mapped from one of the following fields: device_platforms/ publisher_platforms/ facebook_positions/ instagram_positions/ audience_network_positions/ messenger_positions
Possible values: mobile, desktop, facebook, instagram, messenger, audience_network, feed, right_hand_column, instant_article, marketplace, video_feeds, search stream, story, explore, classic, instream_video, rewarded_video, messenger_home, sponsored_messages
Platform platform
  1. If all the ads are of the same platform (see Creative Platform), Singular gives that platform to the sub-campaign.
  2. Otherwise, estimated based on the ad-set targeting: targeting[‘user_os’], targeting[‘user_device’], targeting[‘device_platforms’]
  3. If that's not possible, estimated based on the campaign objective:
Public Id site_public_id
  1. Derived from our Campaign URL and Platform dimensions if possible.
  2. Otherwise derived from the Creative URL and Platform.
Source source For Sub Ad Network ("Publisher Platform") breakdown - this field contains the sub ad network, i.e. Facebook Advertising Network, Instagram, Whatsapp, etc.
Sub Ad Network adn_subadnetwork publisher_platform
Sub Campaign ID sub_campaign_id adset_id
Sub Campaign Name sub_campaign_name ‘Name’ from sub campaign level insights
Target Countries target_countries_str targeting[‘geo_locations’]
Text creative_text Get creative(ad) data by id
  • ad[‘body’]
  • ad[‘message’] if is story or video
  • ad[‘description’] if is event or page
  • asset_feed_spec[‘title’] & asset_feed_spec[bodies] & asset_feed_spec[‘descriptions’] if asset_feed_spec in ad
Timezone adn_timezone From Account.timezone_utc_offset
UTC Offset adn_utc_offset From Account.timezone_utc_offset
Age age age
Gender gender gender
Facebook Attribution Type
A field for FB app ads campaign, which directly indicates the chosen attribution type for an app install campaign (e.g., SKAN or AEM) while creating it on FB

Average Frequency
frequency frequency
adn_comments Post comments
adn_likes Post reactions
Network Clicks adn_clicks Clicks (default) or inline_link_clicks (if specifically requested by Singular customer)
Network Impressions adn_impressions impressions
Network Installs adn_installs Mobile_installs / canvas_installs. Note that if you set up your campaign with Facebook to optimize on AEM installs, this metric will reflect AEM installs.  
Original Cost adn_original_cost spend
Original Currency adn_original_currency 'currency' from me/adaccounts endpoint
Posts saved
posts_saved Post saves
adn_shares Post shares
Video Views 25% video_views_25pct video_p25_watched_actions
Video Views 50% video_views_50pct video_p50_watched_actions
Video Views 75% video_views_75pct video_p75_watched_actions
Completed Video Views completed_video_views video_p100_watched_actions

FAQ and Troubleshooting

What metrics does Singular pull from Facebook?

Out of the various metrics provided by Facebook, the Singular integration gathers the metrics relevant to mobile marketing:

  • Impressions
  • Clicks
  • Installs - note that this metric will reflect AEM installs if you have set up your Facebook campaign to optimize for AEM installs. 
  • Cost

In addition, Singular can get statistics about user actions, which are known in Singular as conversion events. See Configuring Custom Events below for information about configuring Singular to get that data from Facebook.

Where can I see AEM installs?
If you have setup your campaign to optimize for AEM, we will pull AEM install into the network installs dimension
Why do some rows in my report say "Data is censored due to Meta/Facebook privacy requirements"?


To protect end-users' privacy, Facebook does not allow showing measurements for user segments that have fewer than 1000 impressions. If you see this message in a row in your report, it means the row has a low number of impressions. To get the data you are looking for, try running a less granular report, i.e., include fewer dimensions or select a wider date range.

What data does Singular display per asset in Dynamic Creatives?

Dynamic Creatives are a special type of creatives in Facebook that include multiple creative assets. Singular can now show these creative assets in your reports as well as show stats on the asset level.

Facebook considers assets to be a separate breakdown and does not offer asset-level data with any other allowed breakdown (e.g. country or sub ad network). In order to show you asset data per country (or any other breakdown you see in your other Facebook reports), Singular does the extra step of pulling the data per creative and then interpolating the data to give a proportional part of the metrics to each asset.

For example, if your chosen Facebook breakdown is country:


Why do I sometimes see Country or Platform data in the report even if I'm using a different breakdown?

Since the Facebook API only provides the country OR sub-ad network OR platform, Singular tries to figure out the other two dimensions another way - by checking the targeting settings of the campaign, sub-campaign, or creative.

For example, if you are breaking down the data by Campaign and Country, the data pulled from Facebook does not include the Platform. Singular looks up the targeting settings for each campaign, and if a campaign is targeting a single specific platform, such as iPhone, Singular uses the targeting information to fill out the Platform field for that campaign with the value "iPhone".

On the other hand, if a campaign is targeting multiple platforms, e.g. iOS and Android, Singular can't use that to fill out the Platform field.

This means you can get richer data in your reports by defining your campaigns or sub-campaigns (in Facebook: ad campaigns or ad sets) so that each one targets one country and/or one device.

Note: If platform data is derived from targeting settings, your reports may sometimes display the platform as "iPhone" or "iPad" and other times only say "iOS" or nothing at all. This is based on the level of targeting in each case.

What is the attribution window used to count installs? Can I change it?

By default, Facebook uses an attribution window of 7 days for clicks and 1 day for views.

If you want to use different values in your Singular analytics reports, contact Singular Support to have the windows changed for you.

How do I set up a Facebook data connector?

To start pulling data from Facebook into Singular:

  1. In the Singular platform, go to Settings > Data Connectors.
  2. Hover over the Add New Connector button and start typing "Facebook". In the list that appears, choose Facebook.
  3. Click Connect with Facebook and log into a Facebook user that has access to the required ad accounts.


    Note: Before clicking the button, make sure you are not logged into Facebook with an unrelated account (such as your personal account).

How do I work with Agency Facebook Ads accounts?

To run campaigns through your Agency Facebook Ads account, go to Settings > Data Connectors, and add your Agency Facebook account. You do not need to make any updates to your SDK integration or Partner Configuration.

You will then be able to get campaign data like impressions, clicks, and cost using our reporting tools. Use the Account ID and Account Name dimensions when running reports.

If your campaign costs include an additional fee, such as an agency fee, you can have Singular add these fees to the costs shown in your reports under Settings > Partner Fees. See Partner Fees FAQ.

You can also choose to view your data as an agency. Go to Settings > Data Connectors, open your Facebook configuration, and use the View This Source As dropdown.


What is the list of accounts that appears when I create the new connector? Which accounts should I choose?


Singular displays all the accounts that can be accessed by the user you logged in with. Select the accounts you want to connect to Singular. For example, if you have any test accounts with dummy data, you may want to leave them out.

Note: If one of the accounts you selected is invalid, you will not be able to save. This can happen if an account on Facebook is no longer active or if the signed-in user no longer has access to an account.

What should I enter in the "Source" column for each account?

The Source column lets you give a name to each account. This is the name under which the data will appear in your reports. You can use the same source name for multiple accounts.

For example, if you have one or more Facebook accounts for ad campaigns handled by a Preferred Marketing Developer (PMD) or Facebook Marketing Partner (FMP) such as Nanigans, specify "Nanigans" for those accounts. Singular reports will sum up the data from these accounts and display it in your reports under the source name "Nanigans".

By default, all accounts are given the source name "Facebook".

How do I start tracking user events (post-conversion events)?

  For general information about custom events in Singular, see Configuring Custom Events

Singular can analyze data about users' post-install events, such as registration or first purchase. It is usually preferable to pull data about these events from your attribution provider, but if you don't track Facebook activity through an attribution provider, or if you want to track non-mobile traffic, you can ingest data coming from Facebook itself. In Facebook, user events are known as actions.

To start tracking a custom event from Facebook, follow the instructions in Configuring Custom Events to add a new custom event. If you have Facebook campaigns configured, the New Custom Event box includes a Facebook drop-down list. Click the list to display all the Facebook actions available, and select an action to map the custom event to.


Why is my iOS report showing "N/A" for install numbers?

If your iOS report is not displaying install numbers, please ensure you are viewing the correct report. The SKAN report will show you the SKAN installs value; Reports will show you both network and MMP installs.

Keep in mind that:

  • SKAN Reports: Understand that SKAN reports combine network data and SKAN installs. Network data is detailed, while SKAN data is typically at the campaign level due to SKAdNetwork's limitations.
  • Report Breakdown: When breaking down by sub-campaign, SKAN installs might be under 'N/A' if partners only pass data at the campaign level. Other data will be under their respective sub-campaigns.
Why is Singular showing different data than my Facebook dashboard?