Facebook Ad Manager

The Facebook Ad Manager connector allows for automatic ingestion of Facebook ad statistics from the Facebook Insights API.

Prerequisites

The Facebook Ad Manager connector requires authentication either using the credentials of a Facebook System User or through the Facebook OAuth flow.

Facebook System User Authentication

You will need to add a Key with the Credential Type Facebook System User with the following properties.

System User Name
You with need a System Username on Business Manager
Access Token
You will need to generate a System User Token in the Graph API Explorer as described in the Facebook Developer documentation

Facebook OAuth Authentication

You will need to add a Key with the Credential Type Facebook and click the button labeled “Connect” to authenticate via OAuth.

Scheduling

Facebook Ad Manager connector can be scheduled to ingest data once per day at a user-defined hour and timezone.

By default, the connector will run once at 6am PT.

See Daily Scheduling for more information.

Parameters

The following parameters are supported. For full details on these parameters, please consult the documentation for the Facebook Insight API.

api_version
required
version of the Facebook API
account_ids
required
either act_<AD_ACCOUNT_ID>, <CAMPAIGN_ID>, <ADSET_ID>, or <AD_ID>; string list :note that the typs facebook:marketing_adcreatives_bundle, facebook:marketing_adsets_bundle, and facebook:marketing_custom_conversions_bundle do not require this parameter.
action_attribution_windows
required
provides timeframes that define when Facebook attributes an event to an ad on its platform; string list, default = ["7d_click","1d_view"]

See How Attribution Reporting Works

valid values include: 1d_view, 7d_view, 28d_view, 1d_click, 7d_click, 28d_click, default

action_breakdowns
optional
How to break down action results; string list, default = action_type

valid values include: action_device, action_canvas_component_name, action_carousel_card_id, action_carousel_card_name, action_destination, action_reaction, action_target_id, action_type, action_video_sound, action_video_type

action_report_time
optional
determines the report time of action stats; string

valid values include: impression, conversion

breakdowns
optional
How to break down the result; string list

For more than one breakdown, only certain combinations are available: See Combining Breakdowns

valid values include: ad_format_asset, age, body_asset, call_to_action_asset, country, description_asset, gender, image_asset, impression_device, link_url_asset, product_id, region, title_asset, video_asset, dma, frequency_value, hourly_stats_aggregated_by_advertiser_time_zone, hourly_stats_aggregated_by_audience_time_zone, place_page_id, publisher_platform, platform_position, device_platform

business_id
required
Represent a specific business on Facebook. Make the API call to the business ID. To find the ID of a business, go to Business Manager > Business Settings > Business Info. There, you will see information about the business, including the ID.
fields
optional
Fields to be retrieved; string list, default behavior is to return impressions and spend
level
optional
represents the level of result; string

valid values include: ad, adset, campaign, account

posts_from_days_ago
optional
used to calculate the time range for which posts are relevant.
skip_accounts
optional
allows you to skip accounts for the report
type
required
Available type values are: facebook:marketing__adcreatives, facebook:marketing_adsets, facebook:marketing_custom_conversion, facebook:marketing_adcreatives_bundle, facebook:marketing_adsets_bundle, and facebook:marketing_custom_conversions_bundle
use_account_attribution_setting
optional
when this parameter is set to true, your ads results will be shown using the attribution settings defined for the ad account; boolean, default = false

Switchboard Script Syntax

Facebook Marketing

download marketing_insights_raw from {
    type: "facebook:marketing";
    key: "<key name>";  
    account_ids:["act_XXXXXXX"]; // ENTER act_<act_AD_ACCOUNT_ID> <CAMPAIGN_ID> <ADSET_ID> or <AD_ID>
    action_attribution_windows: ["1d_view", "7d_click"];
    action_report_time: "impression";
    action_breakdowns: ["action_type"];
    breakdowns: [];
    business_id: 23656837556;
    level: "ad"; //campaign, adset, ad
    posts_from_days_ago: 0;
    use_account_attribution_setting: false;
    api_version: "v11.0";
    repull_days: 5;
    fields: ["account_id",
            "account_name",
            "campaign_id",
            "campaign_name",
            "adset_name",
            "adset_id",
            "ad_id",
            "ad_name",
            "reach",
            "inline_link_clicks",
            "clicks",
            "impressions",
            "spend",
            "objective",
            "actions"
 ];
   
} using {
    account_id: string;
    account_name: string;
    date_start: datetime;
    date_stop: datetime;
    campaign_id: string;
    campaign_name: string;
    adset_name: string;
    adset_id: string;
    ad_id: string;
    ad_name: string;
    reach: integer;
    inline_link_clicks: integer;
    clicks: integer;
    impressions: integer;
    spend: float;
    objective: string;
    actions: json;
};

Facebook Marketing Bundle

This connector is similar to the above facebook:marketing downloader but it does not require the account_ids parameter

download bundle t {
            type: "facebook:marketing_bundle";
            key: "facebook_system_user";
            action_attribution_windows: "1d_view";
            action_report_time: "impression";
            fields: ["account_id","account_name","campaign_id","campaign_name","adset_name"];
            level: "ad";
            use_account_attribution_setting: false;
            posts_from_days_ago: 2;
            timezone: "UTC";
            api_version: "v14.0";
            business_id: 42346742134;       // **New required value**
            table accounts using {*};
            table reports using {*};
        };