Facebook Ads: Setup guide

On this page

This guide explains how to collect data from Facebook Ads.

Introduction

For a list of the fields that you can collect from Facebook Ads, see Facebook Ads.

This video guide explains how to create and configure a datastream to collect your ad performance data from Facebook Ads.

Limitations

Collecting data from Facebook Ads comes with the following limitations:

The Facebook Ads API allows only the last 37 months of data to be retrieved. The connector automatically adjusts the specified start date to conform to this limitation.
Reach metrics that include breakdown dimensions (such as age, gender, country, placement, or device) are limited to the last 13 months of data. Meta applies this limit, and it also applies when one of these dimensions is used as a filter rather than collected as a field. Reach metrics collected without any of these dimensions are not affected.
The level at which data is collected is determined by the fields you select, not by a separate setting. Selecting any field whose name begins with ad_ collects data at ad level, adset_ at ad set level, and campaign_ at campaign level. Adding a single ad-level field therefore changes the granularity of the whole report, which changes both the number of rows and the meaning of the metrics in it.
For certain Insights breakdowns (specifically impression_device, hourly_stats_aggregated_by_audience_time_zone, and frequency_value), data may not be returned if your ad account is not opted in with Meta. If this occurs, a warning is raised in the Adverity Issues tab.

Prerequisites

Before you start collecting data from Facebook Ads, perform all of the following actions:

Ensure that the account you use to connect to Facebook Ads has the correct roles and permissions to collect the data. Edit these roles and permissions in Facebook Business Manager. For more information, see the Facebook documentation.
Add the Employee or higher business manager role to the account.
For an ad account, add the View performance permission.
Add the View Page performance permission to the classic page.

Depending on your specific configuration, the following additional permissions may be required:

Leads Access or Manage Page: To access lead form results.
Manage catalogue: To obtain metadata for advertised catalog objects.
Manage line of business: To retrieve data specific for attribution reports.

Alternatively, if you do not use Facebook Business Manager, configure the roles and permissions on the page level. For more information, see the Facebook documentation.

Creating a datastream to collect data from Facebook Ads

The basics of creating a datastream to collect data from any data source are explained in our guide to Collecting data in Adverity. This guide contains information about the specific steps to create a datastream to fetch data from Facebook Ads.

Authorization: Allow Adverity to access Facebook Ads

Facebook Ads offers two authorization types: login-based authorization using your Meta credentials, and a System User Access Token generated in Meta Business Manager. Select the authorization type that matches how you want to authorize.

If you choose Access using your credentials or Access using someone else’s credentials, in Set up or edit Ad Accounts, you or the person granting access must choose one of the following options:
- Choose Grant access to all items, including those created in the future to give Adverity Ad Accounts to access all existing items and all items created in the future.
- Choose Select specific items to which you want to grant access to only give Adverity Ad Accounts to access the selected items. Adverity will not automatically have access to items created in the future. You will need to grant Adverity access to any items created in the future.
1. (Optional) Select the Restrict ad accounts to directly assigned accounts only checkbox.
  
  When enabled, Adverity only discovers ad accounts directly assigned to your user, or to Business Managers you administer. This can help to filter out unwanted ad accounts during authorization and datastream setup.
2. (Optional) In Businesses, select the Facebook Business Managers to which the ad accounts belong.
  
  When selected, Adverity discovers only the ad accounts associated with the chosen Business Managers, enabling you to filter and manage ad accounts more efficiently.

System User Access Token

This authorization type uses a token generated in Meta Business Manager instead of a login-based authorization. There is no consent screen, and the authorization is not tied to a personal Meta account.

Before you authorize, generate a System User Access Token in Meta Business Manager:

In Meta Business Manager, go to Settings > Users > System Users.
Select an existing system user, or create a new one.
Assign the ad accounts you want to collect data from to the system user, with the View performance permission.
Click Generate New Token, then select the ads_read and business_management permissions.

Tip
(Recommended) Generate a token with no expiration. Adverity cannot refresh a System User Access Token automatically, so an expiring token requires you to manually replace it in the authorization before it expires.
Copy the generated token.

To set up the authorization in Adverity, follow these steps:

In System User Access Token, paste the token you generated.
(Optional) Select the Restrict ad accounts to directly assigned accounts only checkbox.

When enabled, Adverity only discovers ad accounts directly assigned to the system user. This can help to filter out unwanted ad accounts during authorization and datastream setup.
(Optional) In Businesses, select the Facebook Business Managers to which the ad accounts belong.

When selected, Adverity discovers only the ad accounts associated with the chosen Business Managers, enabling you to filter and manage ad accounts more efficiently.
Click Authorize.

As a result, Adverity validates the token and lists the ad accounts assigned to the system user.

Configuration: Choose the data you want to collect from Facebook Ads

To choose what data to collect and customize the Facebook Ads datastream configuration, follow these steps:

(Optional) Rename your datastream.
In Businesses, Accounts, and Campaigns, configure which businesses, accounts, and campaigns to collect data for.

For each field, select one of the following options:

Include all
Collects data for all available items.

Include some
Collects data only for the specific items you select.

Exclude some
Collects data for all items except those you select.
In Fields, change the list of fields that you want to see in your data extract.

Note
The actions, action_values, and conversions fields are group fields. This means that if you select one or more of these fields, and later select the Force action fields checkbox, this datastream will fetch all fields in the selected groups, even if the column is empty.
This could mean that your data extract will contain lots of empty columns. If you only want to keep some of these columns, you can use the cut custom script instruction to choose which columns to keep.
Alternatively, if you know which columns you want to include in your data extract, you can use the extendmissing custom script instruction to only add these columns. You can do this instead of using the Force action fields option.
For more information about action fields, including a list of all fields you can collect by selecting these group fields, see the Facebook Ads documentation.”
(Optional) To store creative images on Adverity’s infrastructure, select Host creative images.

When enabled, Adverity downloads images from expiring Facebook CDN URLs and stores them on Adverity’s infrastructure. The ad_creative_image_url in extracts will be replaced with a stable, Adverity-hosted URL.
(Optional) To take screenshots of your ads, select Save media screenshots, then populate Ad preview fields.

In Ad preview fields, select at least one field to contain the link to the screenshot.

(Recommended) Select ad_preview_default_url to generate a screenshot. For image thumbnails, use ad_preview_url.

The screenshots are saved in the same storage as the Facebook Ads data extracts. For more information, see Setting up Storage for data extracts. The screenshots are stored until you delete them manually from the storage, or delete the Facebook Ads datastream.

What’s next?

Apply Data Mapping to your collected data to harmonize data collected from different sources in Adverity.
Transform your data to meet your needs by creating and applying transformations to your datastream.
Load your data into a warehouse to continue working with your data in Adverity.
Load your data into an external destination of your choice.

Advanced Facebook Ads tips

Configuring advanced data collection options for Facebook Ads

This section explains the advanced configuration options for your Facebook Ads datastream. You can adjust these settings in the Configuration step of the datastream creation wizard.

In the General section of the page, adjust the following settings:

Breakdowns

Select how collected data is broken down in the data extract. For example, select age to view a breakdown of the age groups interacting with your ad campaigns.

Levels of granularity include: - Account - Campaign - Ad set - Ad

Further breakdowns include age, gender, country, publisher platform. These breakdowns are not all compatible with each other. Most combinations are not valid: of the breakdowns offered, only a small number of pairs can be used together. When you select a breakdown, Adverity disables the breakdowns that cannot be combined with it, so the options that remain available are always valid.

The following breakdowns cannot be combined with any other breakdown, and must be used on their own: comscore_market, frequency_value, marketing_mix_modeling, place_page_id, product_id, and both hourly breakdowns. Additionally, comscore_market cannot be combined with action_target_id or action_video_type.

age and gender can be combined with the widest range of other breakdowns. The asset breakdowns, such as image_asset and video_asset, can only be combined with age and gender.

Action breakdowns

Select how collected data is broken down in the data extract in terms of actions on a campaign. For example, select action_reaction to view a breakdown by the number of reactions each campaign received.

Select actions (in fields) and action_type (in action breakdowns) for additional metrics.

Granularity

Select the time unit in which you want to collect data. Choose one of the following options:

Total
Monthly
Daily
Custom

Recommended setting: Time increment custom > number of days = 1 (unless you are fetching reach).

Action attribution windows

An attribution window is the time period between a user clicking on or viewing an ad, and performing an action (such as a purchase or download) as a result of the ad click or view. In Action attribution window, select the time period for which to collect attribution data.

For each action selected in the Action breakdowns field, a column will be placed next to the action column in the data extract, displaying the number of actions that occurred within the selected action attribution window.

You can select from standard attribution windows (such as 1-day click, 7-day click, or 28-day click) and the following incrementality options:

incrementality
incrementality_all_conversions
incrementality_first_conversion

Pivot action fields

Select this checkbox to display action fields as rows instead of columns in the data extract. Each action is broken down by row, with the columns action_type and action_values. This setting only is only effective if you select an action in the Action breakdowns field.

Translate custom conversions

Select this checkbox to collect the names for custom conversions.

Force action fields

Select this checkbox to create a column for each possible action field for the action_type breakdown in the data extract, even if the action field is empty. By default, Facebook does not return empty values. This feature resolves destination issues where certain destinations may require a set number of columns to be loaded. For more information on action fields, see the Facebook documentation.

Include future campaigns

Select this checkbox to collect data on campaigns that have not run yet.

Adset targeting fields

Select the adset targeting fields to include in your data extract. Each selected adset targeting field will be displayed as a separate column in the data extract.

By default, the adset targeting fields are contained in a single JSON string. Adset targeting fields defines which fields from this JSON string will be included in the fetched data.

Product ID limit

Enter the maximum number of product IDs to be returned for each ad set for the product_id breakdown. For example, a carousel ad campaign may have up to five products included in the ad, each with its own product ID.

Custom Filter

To filter the data to collect from Facebook Ads, provide a set of filters in JSON format. For example, to find data with the ID 123, enter the following:

[{"field": "id", "operator": "EQUAL", "value": "123"}]

You can also use dynamic epoch date placeholders for filtering campaigns by stop_time using relative dates:

@dt_epoch: Represents the current epoch timestamp.
@dt_epoch-Nd: Represents N days before the current epoch timestamp. For example, @dt_epoch-7d is 7 days before the current epoch timestamp.
@dt_epoch+Nd: Represents N days after the current epoch timestamp. For example, @dt_epoch+1d is 1 day after the current epoch timestamp.

Example for filtering campaigns that stop after the current date:

[{"field": "stop_time", "operator": "GREATER_THAN", "value": "@dt_epoch"}]

For more information on the parameters that can be filtered, see the Facebook documentation.