Learn how Singular pulls data from Facebook and how you can configure and customize the options. See also: Troubleshooting Facebook Data Discrepancies.
Update (February 2021): Singular now supports Automated App Ads (AAA) and can show the individual graphic assets within a Dynamic Creative. Singular also interpolates from the creative level to show you country/sub ad network/platform breakdown on the asset level (learn more).
See our other integrations with Facebook:
- Facebook Ads Attribution Integration: Configure if you use Singular's attribution service.
- Facebook Ads SKAdNetwork Integration
- FAN Ad Monetization ROI Integration: Use to get ad revenue information from Facebook.
Quick Details
| Data Connector Technology | API (Facebook Graph API and Marketing API v9.0) |
| Data breakdown (segmentation) |
Facebook provides your data broken down by all of the following (see Data Mapping below for terminology and more details):
In addition, you get one of the following breakdowns:
The default out of these is Country. If you want the Sub Ad Network breakdown or Platform breakdown instead, contact your Customer Success Manager or Singular support. 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, 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" (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 | |
| 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 |
|
| 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 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 |
|
| Campaign Dimensions | Public Id | site_public_id |
|
| 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
|
| Campaign Dimensions | Timezone | adn_timezone | From Account.timezone_utc_offset |
| Campaign Dimensions | UTC Offset | adn_utc_offset | From Account.timezone_utc_offset |
| Creative Dimensions | Network Creative ID | adn_creative_id | ad_id |
| Creative Dimensions | Network Creative Name | adn_creative_name | ‘Name’ from ad level |
| Creative Dimensions | Asset ID |
asset_id |
asset_id |
| Metrics | Network Clicks | adn_clicks | Clicks (default) or inline_link_clicks (if specifically requested by Singular customer) |
| 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
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.
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 showing 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:
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.
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 |
To start pulling data from Facebook into Singular:
- In the Singular platform, go to Settings > Data Connectors.
- Hover over the Add New Connector button and start typing “Facebook”. In the list that appears, choose Facebook.
-
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).
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.
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”.
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.
