Facebook Ads

Facebook Ads

This document provides instructions for integrating Facebook Ads data into Panoply. The following items will be covered:

Facebook Ads Data Integration

To integrate Facebook Ads data into Panoply using default selections, complete the following steps. For more advanced options, complete the following and refer to the subsequent sections for detailed information.

  1. Click Data Sources in the navigation menu.
  2. Click the Add Data Source button.
  3. In the Data Sources – Choose Source Type window, select Facebook Ads. Facebook Ads is listed under APIs.
  4. In the Data Sources – Facebook Ads screen, click Login With Facebook.
  5. A Facebook dialog box confirms whether you want to allow Panoply to access your Facebook public profile. Click Continue as {Your Name} to continue.
  6. A second Facebook dialog box confirms whether you want to allow Panoply to access your Facebook Ads data. Click OK.
  7. In the Data Sources – Facebook Ads screen, select the Facebook Ad Account from which to import data.
  8. (Optional) To customize the ingestion from your data source, review the additional available selections and advanced options.
  9. Click Collect.

The Data Sources – Facebook Ads window will appear grayed out while the data integration is pending. A small green progress bar appears below Facebook Ads.

You will be prompted to set up the integration of another data source. You can set up multiple data integrations without impacting the ingestion of the already scheduled or pending data integrations.

From the Data Sources main menu, you can monitor the data ingestion status of the scheduled and pending data integrations. After the data ingestion is complete, you can clean or transform your data in the Tables menu.

Additional Available Selections

Date Range

To pull Ads data for a subset of the dates available, select one of the following Date Range options:

  • Today
  • Yesterday
  • This Month
  • This Quarter
  • Last 3 Days
  • Last 7 Days
  • Last 30 Days (default)
  • Last 90 Days
  • This Year
  • Last Year
  • Lifetime

Breakdowns

To group the Insights results into different sets, select one of the following Breakdowns options:

  • Country (default)
  • Age
  • DMA
  • Gender
  • Region
  • Age & Gender

Advanced Options

Clicking Show next to Advanced will expand the Data Sources - Facebook Ads window to include Destination, Primary Key, Exclude, Parse string, and Truncate table.

Data Schema

The resources available in the Facebook Ads data source include Insights, Ads, and Adsets. For additional information on the Facebook Ads Marketing API.

Insights

Column Data Type Description
account_id numeric string The ID number of your ad account, which groups your advertising activity. Your ad account includes your campaigns, ads and billing.
account_name string The name of your ad account, which groups your advertising activity. Your ad account includes your campaigns, ads and billing.
action_values list<AdsActionStats> The total value of all conversions attributed to your ads.
actions list<AdsActionStats> The total number of actions people took that are attributed to your ads. Actions may include engagement, clicks or conversions.
ad_id numeric string The unique ID of the ad you’re viewing in reporting.
ad_name string The name of the ad you’re viewing in reporting.
adset_id numeric string The unique ID of the ad set you’re viewing in reporting. An ad set is a group of ads that share the same budget, schedule, delivery optimization and targeting.
adset_name string The name of the ad set you’re viewing in reporting. An ad set is a group of ads that share the same budget, schedule, delivery optimization and targeting.
buying_type string The method by which you pay for and target ads in your campaigns: through dynamic auction bidding, fixed-price bidding, or reach and frequency buying. This field is currently only visible at the campaign level.
campaign_id numeric string The unique ID number of the ad campaign you’re viewing in reporting. Your campaign contains ad sets and ads.
campaign_name string The name of the ad campaign you’re viewing in reporting. Your campaign contains ad sets and ads.
clicks unsigned int32 The number of clicks on your ads.
cost_per_action_type list<AdsActionStats> The average cost of a relevant action.
cost_per_unique_click float The average cost for each unique click (all). This metric is estimated.
cost_per_inline_post_engagement float The average cost of each inline post engagement.
cpm float The average cost for 1,000 impressions.
cpp float The average cost to reach 1,000 people. This metric is estimated.
ctr float The percentage of times people saw your ad and performed a click (all).
date_start string The start date for your data. This is controlled by the date range you’ve selected for your reporting view.
date_stop string The end date for your data. This is controlled by the date range you’ve selected for your reporting view.
frequency float The average number of times each person saw your ad. This metric is estimated.
impressions string The number of times your ads were on screen.
inline_link_clicks unsigned int32 The number of clicks on links to select destinations or experiences, on or off Facebook-owned properties. Inline link clicks use a fixed 1-day-click attribution window.
inline_post_engagement unsigned int32 The total number of actions that people take involving your ads. Inline post engagements use a fixed 1-day-click attribution window.
mobile_app_purchase_roas list<AdsActionStats> The total return on ad spend (ROAS) from mobile app purchases. This is based on the value that you assigned when you set up the app event.
objective string The objective you selected for your campaign. Your objective reflects the goal you want to achieve with your advertising.
reach unsigned int32 The number of people who saw your ads at least once. Reach is different from impressions, which may include multiple views of your ads by the same people. This metric is estimated.
social_spend float The total amount you’ve spent so far for your ads showed with social information. (ex: Jane Doe likes this).
total_action_value float The total value of all conversions attributed to your ads.
spend float The estimated total amount of money you’ve spent on your campaign, ad set or ad during its schedule. This metric is estimated.
total_action_value float The total value of all conversions attributed to your ads.
unique_clicks unsigned int32 The number of people who performed a click (all). This metric is estimated.
unique_ctr float The percentage of people who saw your ad and performed a unique click (all). This metric is estimated.
video_p25_watched_actions list<AdsActionStats> The number of times your video was played at 25% of its length, including plays that skipped to this point.
video_p50_watched_actions list<AdsActionStats> The number of times your video was played at 50% of its length, including plays that skipped to this point.
video_p75_watched_actions list<AdsActionStats> The number of times your video was played at 75% of its length, including plays that skipped to this point.
video_p95_watched_actions list<AdsActionStats> The number of times your video was played at 95% of its length, including plays that skipped to this point.
video_p100_watched_actions list<AdsActionStats> The number of times your video was played at 100% of its length, including plays that skipped to this point.
video_avg_percent_watched_actions list<AdsActionStats> The average percentage of your video that people played.
website_purchase_roas list<AdsActionStats> The total return on ad spend (ROAS) from website purchases. This is based on the value of all conversions recorded by the Facebook pixel on your website and attributed to your ads.

Ads

Column Data Type Description
id numeric string The ID of this ad.
account_id numeric string The ID of the ad account that this ad belongs to.
adlabels list<AdLabel> Ad labels associated with this ad
adset_id numeric string ID of the ad set that contains the ad
bid_amount int32 Bid amount for this ad which will be used in auction instead of the ad set bid_amount, if specified. Any updates to the ad set bid_amount will overwrite this value with the new ad set value.
bid_info map<string, unsigned int32> A dictionary of {objective}:{value} that you place on your bid, based on the bid_type of ad set.
Values are defined in your currency’s minimum denomination:
For bid_type=CPM, bid_info={‘IMPRESSIONS’:<value>}
For bid_type=CPC, bid_info={‘CLICKS’:<value>}
For bid_type=ABSOLUTE_OCPM, bid_info={‘ACTIONS’:<value>, ‘REACH’:<value>, ‘CLICKS’:<value>, ‘SOCIAL’:<value>}
For bid_type=CPA, bid_info={‘ACTIONS’:<value>}
bid_type enum {CPC, CPM, MULTI_PREMIUM, ABSOLUTE_OCPM, CPA} Bid type
campaign_id numeric string ID of the ad campaign that contains this ad
configured_status enum {ACTIVE, PAUSED, DELETED, ARCHIVED} The configured status of the ad. Prefer using ‘status’ instead of this.
conversion_specs list<ConversionActionQuery> Conversion specs
created_time datetime Created time
effective_status enum {ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, ADSET_PAUSED} The effective status of the ad. The status could be effective either because of its own status, or the status of its parent units.
last_updated_by_app_id id Last Updated By App ID
name string Name of the ad.
recommendations list<AdRecommendation> If there are recommendations for this ad, this field includes them. Otherwise, will not be included in the response. (This field is not included in redownload mode.)
source_ad_id numeric string The source ad id that this ad is copied from
status enum {ACTIVE, PAUSED, DELETED, ARCHIVED} The configured status of the ad. The field returns the same value as ‘configured_status’, and is the suggested one to use.
updated_time datetime Updated time

Adsets

Column Data Type Description
id numeric string Ad set ID
account_id numeric string Ad Account ID
adlabels list<AdLabel> Ad Labels associated with this ad set
adset_schedule list<DayPart> Ad set schedule, representing a delivery schedule for a single day
attribution_spec list<AttributionSpec> Conversion attribution spec used for attributing conversions for optimization. Supported window lengths differ by optimization goal and campaign objective. See Validation, Attribution Spec.
bid_amount unsigned int32 Bid cap or target cost for this ad set. The bid cap used in a lowest cost bid strategy is defined as the maximum bid you want to pay for a result based on your optimization_goal. The target cost used in a _target cost bid strategy+ lets Facebook bid on your behalf to meet your target on average and keep costs stable as you raise budget. This field is not returned if is_autobid is true. The bid amount’s unit is cents for currencies like USD, EUR, and the basic unit for currencies like JPY, KRW. The bid amount for ads with IMPRESSION or REACH as billing_event is per 1,000 occurrences of that event, and the bid amount for ads with other billing_events is for each occurrence.
bid_info map<string, unsigned int32> Map of bid objective to bid value. This field is not available if is_autobid is true.
billing_events enum {APP_INSTALLS, CLICKS, IMPRESSIONS, LINK_CLICKS, NONE, OFFER_CLAIMS, PAGE_LIKES, POST_ENGAGEMENT, VIDEO_VIEWS} The billing event for this ad set:
APP_INSTALLS: Pay when people install your app.
CLICKS: Pay when people click anywhere in the ad.
IMPRESSIONS: Pay when the ads are shown to people.
LINK_CLICKS: Pay when people click on the link of the ad.
OFFER_CLAIMS: Pay when people claim the offer.
PAGE_LIKES: Pay when people like your page.
POST_ENGAGEMENT: Pay when people engage with your post.
VIDEO_VIEWS: Pay when people watch videos.
budget_remaining numeric string Remaining budget
configured_status enum {ACTIVE, PAUSED, DELETED, ARCHIVED} The status set at the ad set level. It can be different from the effective status due to its parent campaign. Prefer using ‘status’ instead of this.
created_time datetime Created time
creative_sequence list<numeric string> Order of the adgroup sequence to be shown to users
daily_budget numeric string The daily budget of the set defined in your account currency.
detination_type string Destination of ads in this Ad Set (e.g. Website, App, Messenger)
effective_status enum {ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, ADSET_PAUSED} The effective status of the ad set, which can be either its own status or caused by its parent campaign.
end_time datetime End time, in UTC UNIX timestamp
is_autobid bool Uses the LOWEST_COST_WITHOUT_CAP bid strategy, which is designed to get the most results for your budget based on your ad set optimization_goal without limiting your bid amount. This is the best strategy if you care most about cost efficiency. However with this strategy it may be harder to get stable average costs as you spend.
lifetime_budget numeric string The lifetime budget of the set defined in your account currency.
lifetime_imps int32 Lifetime impressions. Available only for campaigns with buying_type=FIXED_CPM
name string Name of ad set
optimization_goal enum {NONE, APP_INSTALLS, BRAND_AWARENESS, AD_RECALL_LIFT, CLICKS, ENGAGED_USERS, EVENT_RESPONSES, IMPRESSIONS, LEAD_GENERATION, LINK_CLICKS, OFFER_CLAIMS, OFFSITE_CONVERSIONS, PAGE_ENGAGEMENT, PAGE_LIKES, POST_ENGAGEMENT, REACH, SOCIAL_IMPRESSIONS, VIDEO_VIEWS, APP_DOWNLOADS, LANDING_PAGE_VIEWS, VALUE, REPLIES} Which optimization goal this ad set is using:
NONE: Only available in read mode for campaigns created pre v2.4.
APP_INSTALLS: Optimize for people more likely to install your app.
BRAND_AWARENESS: Optimize to reach the most number of users who are likely to spend at least a minimum amount of time on the image or video.
AD_RECALL_LIFT: Optimize for people more likely to remember seeing your ads.
CLICKS: Deprecated. Only available in read mode.
ENGAGED_USERS: Optimize for people more likely to take a particular action in your app.
EVENT_RESPONSES: Optimize for people more likely to attend your event.
IMPRESSIONS: Show the ads as many times as possible.
LEAD_GENERATION: Optimize for people more likely to fill out a lead generation form.
LINK_CLICKS: Optimize for people more likely to click in the link of the ad.
OFFER_CLAIMS: Optimize for people more likely to claim the offer.
OFFSITE_CONVERSIONS: Optimize for people more likely to make a conversion in the site
PAGE_ENGAGEMENT: Optimize for people more likely to engage with your page.
PAGE_LIKES: Optimize for people more likely to like your page.
POST_ENGAGEMENT: Optimize for people more likely to engage with your post.
REACH: Optimize to reach the most unique users of each day or interval specified in frequency_control_specs.
SOCIAL_IMPRESSIONS: Increase the number of impressions with social context. I.e. with the names of one or more of the user’s friends attached to the ad who have already liked the page or installed the app.
VIDEO_VIEWS: Optimize for people more likely to watch videos.
VALUE: Optimize for maximum total purchase value within the specified attribution window.
REPLIES: REPLIES optimization will direct ads to people more likely to have a conversation with the business.
pacing_type list<string> Defines the pacing type, standard or using ad scheduling
recurring_budget_semantics bool If this field is true, your daily spend may be more than your daily budget while your weekly spend will not exceed 7 times your daily budget. More details explained in Facebook’s Ad Set Budget document. If this is false, your amount spent daily will not exceed the daily budget. This field is not applicable for lifetime budgets.
rf_prediction_id id Reach and frequency prediction ID
rtb_flag bool Whether this ad set is using RTB or not
source_adset_id numeric string The source ad set id that this ad set was copied from
start_time datetime Start time, in UTC UNIX timestamp
status enum {ACTIVE, PAUSED, DELETED, ARCHIVED} The status set at the ad set level. It can be different from the effective status due to its parent campaign. The field returns the same value as ‘configured_status’, and is the suggested one to use.
time_based_ad_rotation_id_blocks list<list<integer>> Specify ad creative that displays at custom date ranges in a campaign as an array. A list of Adgroup IDs. The list of ads to display for each time range in a given schedule. For example display first ad in Adgroup for first date range, second ad for second date range, and so on. You can display more than one ad per date range by providing more than one ad ID per array. For example set time_based_ad_rotation_id_blocks to [[1], [2, 3], [1, 4]]. On the first date range show ad 1, on the second date range show ad 2 and ad 3 and on the last date range show ad 1 and ad 4. Use with time_based_ad_rotation_intervals to specify date ranges.
time_based_ad_rotation_intervals list<unsigned int32> Date range when specific ad creative displays during a campaign. Provide date ranges in an array of UNIX timestamps where each timestamp represents the start time for each date range. For example a 3-day campaign from May 9 12am to May 11 11:59PM PST can have three date ranges, the first date range starts from May 9 12:00AM to May 9 11:59PM, second date range starts from May 10 12:00AM to May 10 11:59PM and last starts from May 11 12:00AM to May 11 11:59PM. The first timestamp should match the campaign start time. The last timestamp should be at least 1 hour before the campaign end time. You must provide at least two date ranges. All date ranges must cover the whole campaign length, so any date range cannot exceed campaign length. Use with time_based_ad_rotation_id_blocks to specify ad creative for each date range.
updated_time datetime Updated time
use_new_app_click bool If set, allows Mobile App Engagement ads to optimize for LINK_CLICKS