Facebook Ads Connector reference

This reference explains in detail how to configure data collection from Facebook Ads.


Before you complete the procedure in this guide, perform all of the following actions:

Configuring advanced data collection options for Facebook Ads

Accessing Facebook Ads configuration page

To access the Facebook Ads configuration page, follow these steps:

  1. Click the Connect element and select the Workspace you work with in Connect, Enrich & Transfer.

  1. Select the Facebook Ads Datastream.

  1. In the top navigation panel, click Settings.

  2. In the General section of the page, configure the fields accordingly.

Understanding advanced Facebook Ads configuration options

This section provides explanation for various advanced configuration options of the Facebook Ads Connector.

  1. In the General section of the page, fill in the following fields:


    Select how the aggregated, collected data is separated (or broken down) within the Data Extract. For example, select age to view a breakdown of the age groups interacting with your ad campaigns.

    Action breakdowns

    Select how the aggregated, collected data is separated (or broken down) within the Data Extract in terms of actions on a campaign. For example, select action_reaction to view a breakdown of the number of reactions each campaign received.

  2. In the Advanced section of the page, fill in the following fields:

    Adset Targeting Fields

    The Adset targeting fields are contained in a single, long JSON string. Adset Targeting Fields is a filter that allows you to select certain fields within this long JSON field to ensure they are included in the fetched data. Each selected Adset targeting field is displayed as a separate column within the Data Extract. Select the Adset targeting fields to include in your Data Extract.

    Custom Filter

    To filter the data to collect from Facebooks 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"}]

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

    Translate custom conversions

    Select this checkbox to collect the names for custom conversions.

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

    Force action fields

    Select this checkbox to create a column of every possible action field in the Data Extract, even if the action field is empty. By default, Facebook does not return empty values. This feature resolves Destination import issues where certain Destinations may require a set number of columns to be imported. For more information on action fields, see the Facebook documentation.

    Pivot action fields

    Select this checkbox to display action data 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 breakdown field.

    Include future campaigns

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

    Use unified attribution setting

    Select this checkbox to apply the attribution settings defined at the ad set level in the Facebook administration. This allows you to apply default attribution settings to all ads within an ad set.

    If this checkbox is enabled, Adverity ignores your selection in the Action attribution windows field.

    Action report time

    Ad impressions and conversion actions can occur on different dates. A recorded action can be attributed to one of the following:

    • The date when an impression occurred.

    • Time when a conversion action occurred.

    Some actions can only be attributed to the date of a conversion, and these actions are not reported by Facebook Ads if you select Impression in the Action report time field. Adverity recommends the Mixed option because it returns data on both impressions and conversion actions.

    To specify which actions to report, select one of the following options:

    • (Default, Recommended) Select Mixed to report the following:

      • The date of an impression that occurs on your ad (for example ad-views and ad-clicks).

      • The conversion action dates that occur off your ad (for example purchases on your website).

    • Select Conversion to report all off-ad and off-Facebook action dates.

    • Select Impression (only data before May 3, 2021) to report all impression dates. This option is only supported for impression data before May 3, 2021. For more information on the discontinuation of impression collection, see the Facebook documentation.

    For more information on off-Facebook actions, see the Facebook documentation.

    Product id limit

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

    Time increment

    Select the time increment in which to collect data. Choose from one of the following options:

    • Select a whole number of days such as 1 day or 7 days.

    • Select all_days to collect all data in one Data Extract.

    • Select monthly to collect data for each calendar month in a different Data Extract. For example, when you collect data for the date range 2021-03-15 to 2021-05-16, Adverity collects data in three Data Extracts, one for calendar month.

    Media Screenshots enabled

    To take screenshots of your ads, select this checkbox and populate Ad Preview fields below.

    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.

    Ad Preview fields

    To take screenshots of your ads, select at least one field in Ad Preview fields.

    (Recommended) Select ad_preview_default_url to generate a screenshot.

Obtaining campaign results metric

The results_by_adverity metric shows you how well a campaign performed, calculated based on campaign objectives and metrics.

To add the results_by_adverity metric to your Datastream, follow these steps:

  1. Click the Connect element and select the Workspace you work with in Connect, Enrich & Transfer.

  1. Select the Facebook Ads Datastream.

  1. In the top navigation panel, click Settings.

  2. In the Fields section, write results_by_adverity and select the value from the drop-down list.

  3. Click Save.

  4. In the top right corner, click Fetch Data.

  5. Choose the time period for which data is collected.

  6. Click Run Fetch.

The results metric provided by Facebook cannot be fetched from the Facebook Ads Connector because it is only available in the Facebook Ads user interface and cannot be retrieved using the API. Adverity calculates the results metric through a different metric called results_by_adverity. Therefore, the results metric in Facebook Ads may differ from the results_by_adverity metric in Adverity.

For more information on results, see the Facebook documentation:

List of all campaign objectives and metrics used for calculating the results_by_adverity metric:

Campaign objective

Metric used for calculation

App installs


Brands awareness




Event responses


Lead generation


Link clicks


Local awareness




Offer claims


Page likes


Post engagement


Product catalog sales




Store visits


Video views


Facebook Ads store visits

The store visits objective allows you to create Facebook ad campaigns to increase sales at physical stores.

The store visits optimization (called store traffic as well) is currently only available to users on the Facebook allow list. Contact your Facebook representative for access. For more information, see Facebook documentation.