Facebook Data Connector

Learn how Singular pulls data from Facebook and how you can configure and customize the integration.

For troubleshooting tips, see Troubleshooting Facebook Data Discrepancies.

 

Quick Details

Data Connector Technology

API (as of March 2020, we are using Facebook API v. 6.0 - see Marketing API documentation and Graph API documentation)

Data breakdown (segmentation)

Facebook provides your data broken down by Account, Campaign, Sub-Campaign, and Creative (see Data Mapping below for terminology and more details).

In addition, you can get one of the following breakdowns:

  • Country (default breakdown)
  • Sub Ad Network (known in Facebook as Publisher Platform) - this is where the ad appeared, e.g. Facebook, Instagram, Messenger, or the Facebook Audience Network.
  • Platform (known in Facebook as Impression Device) - e.g. iOS, Android, or iPhone.

Due to a Facebook API limitation, you cannot have your reports broken down by country AND platform, for example.

By default, your data is broken down by country. If you require another breakdown, contact us. You can choose the breakdown for each Account ID separately.

How far back we pull data

 

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

Yes.

Does Singular show your creative assets?

Yes.

Limitations:

  • For Dynamic Creatives, Singular’s Creatives page will not display the different assets included in the creative.
  • 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

  • "Campaign" in Singular corresponds to "Ad Campaign" in Facebook
  • "Sub-Campaign" corresponds to Facebook's "Ad Set"
  • "Creative" corresponds to Facebook's "Ad"

  Field in Singular UI Field in Singular API Field in Facebook
Campaign Dimensions Account ID adn_account_id ‘id’ from me/adaccounts
Campaign Dimensions Account Name adn_account_name ‘name’ from me/adaccounts
Campaign Dimensions App Site ID app_site_id
  1. Derived from our Campaign URL and Platform dimensions if possible.
  2. Otherwise derived from the Creative URL and Platform.
Campaign Dimensions Campaign URL adn_campaign_url Taken from one of the Creative URLs.
Campaign Dimensions Country country_field Country from Insights URL
Campaign Dimensions Date date_field Given as a parameter when querying Facebook
Campaign Dimensions DMA ID dma_id_field ‘Key’ from endpoint ‘search’ with type=’adgeolocation’ and location_types=’geo_market’ and relevant DMA name
Campaign Dimensions DMA Name dma_name_field dma
Campaign Dimensions Network Campaign ID adn_campaign_id campaign_id
Campaign Dimensions Network Campaign Name adn_campaign_name ‘Name’ from the campaign-level endpoint
Campaign Dimensions Network Creative ID adn_creative_id ad_id
Campaign Dimensions Network Creative Name adn_creative_name ‘Name’ from the creative-level endpoint
Campaign Dimensions Network Sub Campaign ID adn_sub_campaign_id adset_id
Campaign Dimensions Network Sub Campaign Name adn_sub_campaign_name ‘Name’ from the sub-campaign (ad set) level endpoint
Campaign Dimensions 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:
    • LINK_CLICKS, CONVERSIONS → Platform WEB
    • CANVAS_APP_INSTALL, CANVAS_APP_ENGAGEMENT → Platform CANVAS
Campaign Dimensions 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.
Campaign Dimensions Source source For Sub Ad Network ("Publisher Platform") breakdown - this field contains the sub ad network, i.e. Facebook Advertising Network, Instagram, Whatsapp, etc.
Campaign Dimensions Sub Ad Network adn_subadnetwork publisher_platform
Campaign Dimensions Sub Campaign ID sub_campaign_id adset_id
Campaign Dimensions Sub Campaign Name sub_campaign_name ‘Name’ from sub campaign level insights
Campaign Dimensions Target Countries target_countries_str targeting[‘geo_locations’]
Campaign Dimensions 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
Campaign Dimensions Timezone adn_timezone From Account.timezone_utc_offset
Campaign Dimensions UTC Offset adn_utc_offset From Account.timezone_utc_offset
Creative Dimensions Creative ID creative_id ad_id
Creative Dimensions Creative Name creative_name ‘Name’ from ad level 
Metrics Network Clicks adn_clicks Clicks or inline_link_clicks (if uan option accounts_with_inline_link_clicks)
Metrics Network Impressions adn_impressions impressions
Metrics Network Installs adn_installs Mobile_installs / canvas_installs
Metrics Original Cost adn_original_cost spend
Metrics Original Currency adn_original_currency ‘currency’ from me/adaccounts endpoint

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
  • Cost

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

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

  Default Attribution Window Options
Clicks 28 days 1 day / 7 days / 28 days
Views 1 day 1 day / 7 days / 28 days
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.

    image3.png

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

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

image1.png

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.

image2.png

Why is Singular showing different data than my Facebook dashboard?
Was this article helpful?