Facebook data source

Getting started

  1. Inside the admin panel go to Google BigQuery ▸ Data Sources page and click Add data source.
  2. Choose Facebook from the list.
  3. Click Authenticate with Facebook and go through the authentication flow.
  4. Select accounts which cost data you would like to import.
  5. Enable required reports.
  6. Click Save.

Available reports

SegmentStream allows to import the following reports from Facebook.

Ads Insights

https://developers.facebook.com/docs/marketing-api/insights/parameters/v7.0#fields

Table name

facebookCampaignStatistics_{ACCOUNT_ID}_{YYYYMMDD}

Table schema

Field name Type Mode
publisher_platform STRING NULLABLE
date_start DATE NULLABLE
impression_device STRING NULLABLE
impressions INTEGER NULLABLE
campaign_id INTEGER NULLABLE
campaign_name STRING NULLABLE
platform_position STRING NULLABLE
date_stop DATE REQUIRED
frequency FLOAT NULLABLE
account_id INTEGER NULLABLE
account_name STRING NULLABLE
spend FLOAT NULLABLE
clicks INTEGER NULLABLE
adset_id INTEGER NULLABLE
adset_name STRING NULLABLE
ad_id STRING NULLABLE
ad_name STRING NULLABLE
account_currency STRING NULLABLE
inline_link_clicks INTEGER NULLABLE
reach INTEGER NULLABLE
unique_clicks INTEGER NULLABLE
cpm FLOAT NULLABLE
cpc FLOAT NULLABLE
ctr FLOAT NULLABLE
actions RECORD NULLABLE
actions.action_type STRING NULLABLE
actions.value FLOAT NULLABLE
actions._1d_view FLOAT NULLABLE
actions._7d_view FLOAT NULLABLE
actions._28d_view FLOAT NULLABLE
actions._1d_click FLOAT NULLABLE
actions._7d_click FLOAT NULLABLE
actions._28d_click FLOAT NULLABLE
actions.dda FLOAT NULLABLE
conversions RECORD NULLABLE
conversions.action_type STRING NULLABLE
conversions.value FLOAT NULLABLE
conversions._1d_view FLOAT NULLABLE
conversions._7d_view FLOAT NULLABLE
conversions._28d_view FLOAT NULLABLE
conversions._1d_click FLOAT NULLABLE
conversions._7d_click FLOAT NULLABLE
conversions._28d_click FLOAT NULLABLE
conversions.dda FLOAT NULLABLE
cost_per_action_type RECORD NULLABLE
cost_per_action_type.action_type STRING NULLABLE
cost_per_action_type.value FLOAT NULLABLE
cost_per_action_type._1d_view FLOAT NULLABLE
cost_per_action_type._7d_view FLOAT NULLABLE
cost_per_action_type._28d_view FLOAT NULLABLE
cost_per_action_type._1d_click FLOAT NULLABLE
cost_per_action_type._7d_click FLOAT NULLABLE
cost_per_action_type._28d_click FLOAT NULLABLE
cost_per_action_type.dda FLOAT NULLABLE

If some of the fields you need are missing, please, let us know!

Additional transformation settings

Besides default reports import, SegmentStream allows to apply additional transformations for the data and help prepare cost data reports grouped by UTM.

This might be very handy if you need to stitch cost data with website sessions or send cost data into Google Analytics.

To enable this transformation use “Import cost data grouped by UTM” setting. Once enabled, a new table with cost data grouped by UTM will appear in your data warehouse.

Table name

facebookCosts_{ACCOUNT_ID}_{YYYYMMDD}

Table schema

Field name Type Mode
cost FLOAT REQUIRED
clicks INTEGER NULLABLE
impressions INTEGER NULLABLE
utmTerm STRING NULLABLE
utmCampaign STRING NULLABLE
utmContent STRING NULLABLE
utmMedium STRING REQUIRED
utmSource STRING REQUIRED
currency STRING NULLABLE

Supported dynamic URL parameters

By default Facebook allows to use a lot of dynamic URL tagging parameters to track campaigns.

SegmentStream supports the following parameters:

Name Description
{{ad.id}} The unique ID of the ad.
{{adset.id}} The unique ID of the ad set. An ad set is a group of ads that share the same budget, schedule, delivery optimization and targeting.
{{campaign.id}} The unique ID number of the ad campaign. A campaign contains ad sets and ads.
{{ad.name}} The name of the ad
{{adset.name}} The name of the ad set. An ad set is a group of ads that share the same budget, schedule, delivery optimization and targeting.
{{campaign.name}} The name of the ad campaign. A campaign contains ad sets and ads.
{{site_source_name}} Depending on where the ad appeared this parameter has four possible values.
fb - Facebook
ig - Instagram
msg - Messenger
an - the Audience Network
{{placement}} Depending on where the ad appeared this parameter has possible values.
Facebook_Mobile_Feed
Facebook_Right_Column
Facebook_Instant_Articles
Facebook_Instream_Video
Facebook_Marketplace
Instagram_Stories
Instagram_Feed
Instagram_Explore
Messenger_Inbox
Messenger_Stories
Facebook_Desktop_Feed
an (for Audience Network)
Others (for all other placements)

Default source/medium

Facebook allows running ads that do not lead directly to your website (for example Facebook page promo, Facebook post promo, events promo, etc). This means that these types of campaigns can not have UTM-params and it is not possible to import them into Google Analytics or match them with website sessions due to limitations that require all imported costs to have campaign source and medium defined.

As a workaround, you can define default UTM-source and UTM-medium for your Facebook data source to manually attribute these costs to sessions with specified utm_source and utm_medium.

This document was last updated on September 23, 2020. If you notice any gaps, outdated information or simply want to leave some feedback to help us improve our documentation, please let us know!