Skip to main content

Facebook Marketing

This connector captures data from the Facebook Marketing API into Flow collections.

It is available for use in the Flow web application. For local development or open-source workflows, ghcr.io/estuary/source-facebook-marketing:dev provides the latest version of the connector as a Docker image. You can also follow the link in your browser to see past image versions.

This connector is based on an open-source connector from a third party, with modifications for performance in the Flow system. You can find their documentation here, but keep in mind that the two versions may be significantly different.

Supported data resources

The following data resources are supported:

By default, each resource associated with your Facebook Business account is mapped to a Flow collection through a separate binding.

Prerequisites

There are two ways to authenticate with Facebook when capturing data into Flow: signing in with OAuth2, and manually supplying an access token. Their prerequisites differ.

OAuth is recommended for simplicity in the Flow web app; the manual method is the only supported method using the command line.

Signing in with OAuth2

To use OAuth2 in the Flow web app, you'll need A Facebook Business account and its Ad Account ID.

Configuring manually with an access token

To configure manually with an access token, you'll need:

  • A Facebook Business account, and its Ad Account ID.
  • A Facebook app with:
    • The Marketing API enabled.
    • A Marketing API access token generated.
    • Access upgrade from Standard Access (the default) to Advanced Access. This allows a sufficient rate limit to support the connector.

Follow the steps below to meet these requirements.

Setup

  1. Find your Facebook Ad Account ID.

  2. In Meta for Developers, create a new app of the type Business.

  3. On your new app's dashboard, click the button to set up the Marketing API.

  4. On the Marketing API Tools tab, generate a Marketing API access token with all available permissions (ads_management, ads_read, read_insights, and business_management).

  5. Request Advanced Access for your app. Specifically request the Advanced Access to the following:

    • The feature Ads Management Standard Access

    • The permission ads_read

    • The permission ads_management

    Once your request is approved, you'll have a high enough rate limit to proceed with running the connector.

Configuration

You configure connectors either in the Flow web app, or by directly editing the catalog specification file. See connectors to learn more about using connectors. The values and specification sample below provide configuration details specific to the Facebook Marketing source connector.

Properties

Endpoint

By default, this connector captures all data associated with your Business Ad Account.

You can refine the data you capture from Facebook Marketing using the optional Custom Insights configuration. You're able to specify certain fields to capture and apply data breakdowns. Breakdowns are a feature of the Facebook Marketing Insights API that allows you to group API output by common metrics. Action breakdowns are a subset of breakdowns that must be specified separately.

PropertyTitleDescriptionTypeRequired/Default
/access_tokenAccess TokenThe value of the access token generated.stringRequired
/account_idAccount IDThe Facebook Ad account ID to use when pulling data from the Facebook Marketing API.stringRequired for manual authentication only
/custom_insightsCustom InsightsA list which contains insights entries. Each entry must have a name and can contains fields, breakdowns or action_breakdownsarray
/custom_insights/-/action_breakdownsAction BreakdownsA list of chosen action_breakdowns to applyarray[]
/custom_insights/-/action_breakdowns/-ValidActionBreakdownsGeneric enumeration. Derive from this class to define new enumerations.string
/custom_insights/-/breakdownsBreakdownsA list of chosen breakdowns to applyarray[]
/custom_insights/-/breakdowns/-ValidBreakdownsGeneric enumeration. Derive from this class to define new enumerations.string
/custom_insights/-/end_dateEnd DateThe date until which you'd like to replicate data for this stream, in the format YYYY-MM-DDT00:00:00Z. All data generated between the start date and this date will be replicated. Not setting this option will result in always syncing the latest data.string
/custom_insights/-/fieldsFieldsA list of chosen fields to capturearray[]
/custom_insights/-/fields/-ValidEnumsGeneric enumeration. Derive from this class to define new enumerations.string
/custom_insights/-/nameNameThe name of the insightstring
/custom_insights/-/start_dateStart DateThe date from which you'd like to replicate data for this stream, in the format YYYY-MM-DDT00:00:00Z.string
/custom_insights/-/time_incrementTime IncrementTime window in days by which to aggregate statistics. The sync will be chunked into N day intervals, where N is the number of days you specified. For example, if you set this value to 7, then all statistics will be reported as 7-day aggregates by starting from the start_date. If the start and end dates are October 1st and October 30th, then the connector will output 5 records: 01 - 06, 07 - 13, 14 - 20, 21 - 27, and 28 - 30 (3 days only).integer1
/end_dateEnd DateThe date until which you'd like to capture data, in the format YYYY-MM-DDT00:00:00Z. All data generated between start_date and this date will be replicated. Not setting this option will result in always syncing the latest data.string
/fetch_thumbnail_imagesFetch Thumbnail ImagesIn each Ad Creative, fetch the thumbnail_url and store the result in thumbnail_data_urlbooleanfalse
/include_deletedInclude DeletedInclude data from deleted Campaigns, Ads, and AdSetsbooleanfalse
/insights_lookback_windowInsights Lookback WindowThe attribution windowinteger28
/max_batch_sizeMaximum size of Batched RequestsMaximum batch size used when sending batch requests to Facebook API. Most users do not need to set this field unless they specifically need to tune the connector to address specific issues or use cases.integer50
/page_sizePage Size of RequestsPage size used when sending requests to Facebook API to specify number of records per page when response has pagination. Most users do not need to set this field unless they specifically need to tune the connector to address specific issues or use cases.integer25
/start_dateStart DateThe date from which you'd like to begin capturing data, in the format YYYY-MM-DDT00:00:00Z. All data generated after this date will be replicated.stringRequired

Bindings

PropertyTitleDescriptionTypeRequired/Default
/streamStreamResource of your Facebook Marketing account from which collections are captured.stringRequired
/syncModeSync modeConnection method.stringRequired

Sample

This sample specification reflects the manual authentication method.

captures:
${PREFIX}/${CAPTURE_NAME}:
endpoint:
connector:
image: ghcr.io/estuary/source-facebook-marketing:dev
config:
access_token: <secret>
account_id: 000000000000000
start_date: 2022-03-01T00:00:00Z
custom_insights:
- name: my-custom-insight
fields: [ad_id, account_currency]
breakdowns: [device_platform]
action_breakdowns: [action_type]
start_date: 2022-03-01T00:00:00Z
bindings:
- resource:
stream: ad_account
syncMode: incremental
target: ${PREFIX}/ad_account
- resource:
stream: ad_sets
syncMode: incremental
target: ${PREFIX}/ad_sets
- resource:
stream: ads_insights
syncMode: incremental
target: ${PREFIX}/ads_insights
- resource:
stream: ads_insights_age_and_gender
syncMode: incremental
target: ${PREFIX}/ads_insights_age_and_gender
- resource:
stream: ads_insights_country
syncMode: incremental
target: ${PREFIX}/ads_insights_country
- resource:
stream: ads_insights_region
syncMode: incremental
target: ${PREFIX}/ads_insights_region
- resource:
stream: ads_insights_dma
syncMode: incremental
target: ${PREFIX}/ads_insights_dma
- resource:
stream: ads_insights_platform_and_device
syncMode: incremental
target: ${PREFIX}/ads_insights_platform_and_device
- resource:
stream: ads_insights_action_type
syncMode: incremental
target: ${PREFIX}/ads_insights_action_type
- resource:
stream: campaigns
syncMode: incremental
target: ${PREFIX}/campaigns
- resource:
stream: activities
syncMode: incremental
target: ${PREFIX}/activities
- resource:
stream: ads
syncMode: incremental
target: ${PREFIX}/ads
- resource:
stream: ad_creatives
syncMode: full_refresh
target: ${PREFIX}/ad_creatives

Learn more about capture definitions.