Skip to content

Commit 976f61d

Browse files
JustinASmithJustinASmith
committed
docs: source-facebook-marketing-native
Documentation for estuary/connectors#3409
1 parent 1c86b49 commit 976f61d

File tree

3 files changed

+230
-28
lines changed

3 files changed

+230
-28
lines changed

‎site/docs/reference/Connectors/capture-connectors/README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,9 +80,12 @@ All Estuary connectors capture data in real time, as it appears in the source sy
8080
- Dropbox
8181
- [Configuration](./dropbox.md)
8282
- Package - ghcr.io/estuary/source-dropbox:dev
83-
- Facebook Marketing
83+
- Facebook Marketing (deprecated)
8484
- [Configuration](./facebook-marketing.md)
8585
- Package - ghcr.io/estuary/source-facebook-marketing:dev
86+
- Facebook Marketing
87+
- [Configuration](./facebook-marketing-native.md)
88+
- Package - ghcr.io/estuary/source-facebook-marketing-native:dev
8689
- Front
8790
- [Configuration](./front.md)
8891
- Package - ghcr.io/estuary/source-front:dev

‎site/docs/reference/Connectors/capture-connectors/facebook-marketing-native.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
2+
# Facebook Marketing
3+
4+
This connector captures data from the Facebook Marketing API into Flow collections.
5+
6+
It is available for use in the Flow web application. For local development or open-source workflows, [`ghcr.io/estuary/source-facebook-marketing-native:dev`](https://ghcr.io/estuary/source-facebook-marketing-native: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.
7+
8+
## Supported data resources
9+
10+
The following data resources are supported:
11+
12+
* [Ads](https://developers.facebook.com/docs/marketing-api/reference/adgroup)
13+
* [Ad activities](https://developers.facebook.com/docs/marketing-api/reference/ad-activity)
14+
* [Ad creatives](https://developers.facebook.com/docs/marketing-api/reference/ad-creative)
15+
* [Ad insights](https://developers.facebook.com/docs/marketing-api/reference/adgroup/insights/)
16+
* [Ad sets](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign/v19.0)
17+
* [Business ad accounts](https://developers.facebook.com/docs/marketing-api/reference/business/adaccount/)
18+
* [Campaigns](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group)
19+
* [Custom Conversions](https://developers.facebook.com/docs/marketing-api/reference/custom-conversion/v19.0)
20+
* [Images](https://developers.facebook.com/docs/marketing-api/reference/ad-image)
21+
* [Videos](https://developers.facebook.com/docs/graph-api/reference/video/)
22+
23+
By default, each resource associated with your Facebook Business account is mapped to a Flow collection through a separate binding.
24+
25+
## Prerequisites
26+
27+
There are two ways to authenticate with Facebook when capturing data into Flow: signing in with OAuth2, and manually supplying an access token.
28+
Their prerequisites differ.
29+
30+
OAuth is recommended for simplicity in the Flow web app;
31+
the manual method is the only supported method using the command line.
32+
33+
### Signing in with OAuth2
34+
35+
To use OAuth2 in the Flow web app, you'll need a Facebook Business account and its [Ad Account ID](https://www.facebook.com/business/help/1492627900875762).
36+
37+
### Configuring manually with an access token
38+
39+
To configure manually with an access token, you'll need:
40+
41+
* A Facebook Business account, and its Ad Account ID.
42+
* A Facebook app with:
43+
* The [Marketing API](https://developers.facebook.com/products/marketing-api/) enabled.
44+
* A Marketing API access token generated.
45+
* Access upgrade from Standard Access (the default) to Advanced Access. This allows a sufficient [rate limit](https://developers.facebook.com/docs/marketing-api/overview/authorization#limits) to support the connector.
46+
47+
Follow the steps below to meet these requirements.
48+
49+
#### Setup
50+
51+
1. Find your Facebook [Ad Account ID](https://www.facebook.com/business/help/1492627900875762).
52+
53+
2. In Meta for Developers, [create a new app](https://developers.facebook.com/docs/development/create-an-app/) of the type Business.
54+
55+
3. On your new app's dashboard, click the button to set up the Marketing API.
56+
57+
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`).
58+
59+
5. [Request Advanced Access](https://developers.facebook.com/docs/marketing-api/overview/authorization/#access-levels) for your app. Specifically request the Advanced Access to the following:
60+
61+
* The feature `Ads Management Standard Access`
62+
63+
* The permission `ads_read`
64+
65+
* The permission `ads_management`
66+
67+
Once your request is approved, you'll have a high enough rate limit to proceed with running the connector.
68+
69+
## Configuration
70+
71+
You configure connectors either in the Flow web app, or by directly editing the catalog specification file.
72+
See [connectors](../../../concepts/connectors.md#using-connectors) to learn more about using connectors. The values and specification sample below provide configuration details specific to the Facebook Marketing source connector.
73+
74+
### Properties
75+
76+
#### Endpoint
77+
78+
By default, this connector captures all data associated with your Business Ad Account.
79+
80+
You can refine the data you capture from Facebook Marketing using the optional Custom Insights configuration.
81+
You're able to specify certain fields to capture and apply data breakdowns.
82+
[Breakdowns](https://developers.facebook.com/docs/marketing-api/insights/breakdowns) are a feature of the Facebook Marketing Insights API that allows you to group API output by common metrics.
83+
[Action breakdowns](https://developers.facebook.com/docs/marketing-api/insights/breakdowns#actionsbreakdown)
84+
are a subset of breakdowns that must be specified separately.
85+
86+
| Property | Title | Description | Type | Required/Default |
87+
| ----------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ---------------- |
88+
| **`/access_token`** | Access Token | The value of the access token generated. | string | Required |
89+
| **`/account_ids`** | Account IDs | A comma delimited string of Facebook Ad account IDs to use when pulling data from the Facebook Marketing API. | string | Required |
90+
| `/custom_insights` | Custom Insights | A list which contains insights entries. | array | |
91+
| _`/custom_insights/-/action_breakdowns`_ | Action Breakdowns | A comma separated string of chosen action_breakdowns to apply | string | |
92+
| _`/custom_insights/-/breakdowns`_ | Breakdowns | A comma separated string of chosen breakdowns to apply | string | |
93+
| _`/custom_insights/-/fields`_ | Fields | A comma separated string of chosen fields to capture | string | |
94+
| _`/custom_insights/-/name`_ | Name | The name of the insight | string | |
95+
| _`/custom_insights/-/start_date`_ | Start Date | The date from which you'd like to replicate data for this stream, in the format YYYY-MM-DDT00:00:00Z. | string | |
96+
| _`/custom_insights/-/level`_ | Level | The level of the insight. Possible values are `ad`, `adset`, `campaign`, or `account`. | string | `ad` |
97+
| _`/custom_insights/-/insights_lookback_window`_ | Insights Lookback Window | The lookback window for custom insights. | integer | `28` |
98+
| `/insights_lookback_window` | Insights Lookback Window | The lookback window for insights. | integer | `28` |
99+
| **`/start_date`** | Start Date | The 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. | string | Required |
100+
| `/advanced/fetch_thumbnail_images` | Fetch Thumbnail Images | In each Ad Creative, fetch the thumbnail_url and store the result in thumbnail_data_url | boolean | `false` |
101+
| `/advanced/include_deleted` | Include Deleted | Include data from deleted Campaigns, Ads, and AdSets | boolean | `false` |
102+
103+
#### Bindings
104+
105+
| Property | Title | Description | Type | Required/Default |
106+
| ----------- | ------------- | --------------------------- | ------ | ---------------- |
107+
| **`/name`** | Data resource | Name of the data resource. | string | Required |
108+
| `/interval` | Interval | Interval between data syncs | string | |
109+
110+
### Sample
111+
112+
This sample specification reflects the manual authentication method.
113+
114+
```yaml
115+
captures:
116+
${PREFIX}/${CAPTURE_NAME}:
117+
endpoint:
118+
connector:
119+
image: ghcr.io/estuary/source-facebook-marketing-native:dev
120+
config:
121+
account_ids: "111111111111111"
122+
credentials:
123+
credentials_title: OAuth Credentials
124+
client_id: placeholder_client_id
125+
client_secret: placeholder_client_secret
126+
access_token: placeholder_access_token
127+
start_date: "2023-03-24T00:00:00Z"
128+
custom_insights:
129+
- name: ads_insights_publisher_platform
130+
action_breakdowns: ""
131+
breakdowns: publisher_platform
132+
fields: "ad_id,ad_name,account_id,account_name,adset_id,adset_name,campaign_id,campaign_name,date_start,date_stop,clicks,impressions,reach,inline_link_clicks,outbound_clicks"
133+
insights_lookback_window: 28
134+
level: ad
135+
start_date: "2023-03-23T00:00:00Z"
136+
insights_lookback_window: 28
137+
advanced:
138+
fetch_thumbnail_images: false
139+
include_deleted: false
140+
bindings:
141+
- resource:
142+
stream: ad_account
143+
syncMode: incremental
144+
target: ${PREFIX}/ad_account
145+
- resource:
146+
stream: ad_sets
147+
syncMode: incremental
148+
target: ${PREFIX}/ad_sets
149+
- resource:
150+
stream: ads_insights
151+
syncMode: incremental
152+
target: ${PREFIX}/ads_insights
153+
- resource:
154+
stream: ads_insights_age_and_gender
155+
syncMode: incremental
156+
target: ${PREFIX}/ads_insights_age_and_gender
157+
- resource:
158+
stream: ads_insights_country
159+
syncMode: incremental
160+
target: ${PREFIX}/ads_insights_country
161+
- resource:
162+
stream: ads_insights_region
163+
syncMode: incremental
164+
target: ${PREFIX}/ads_insights_region
165+
- resource:
166+
stream: ads_insights_dma
167+
syncMode: incremental
168+
target: ${PREFIX}/ads_insights_dma
169+
- resource:
170+
stream: ads_insights_platform_and_device
171+
syncMode: incremental
172+
target: ${PREFIX}/ads_insights_platform_and_device
173+
- resource:
174+
stream: ads_insights_action_type
175+
syncMode: incremental
176+
target: ${PREFIX}/ads_insights_action_type
177+
- resource:
178+
stream: campaigns
179+
syncMode: incremental
180+
target: ${PREFIX}/campaigns
181+
- resource:
182+
stream: custom_conversions
183+
syncMode: full_refresh
184+
target: ${PREFIX}/custom_conversions
185+
- resource:
186+
stream: activities
187+
syncMode: incremental
188+
target: ${PREFIX}/activities
189+
- resource:
190+
stream: ads
191+
syncMode: incremental
192+
target: ${PREFIX}/ads
193+
- resource:
194+
stream: ad_creatives
195+
syncMode: full_refresh
196+
target: ${PREFIX}/ad_creatives
197+
```
198+
199+
[Learn more about capture definitions.](../../../concepts/captures.md)

0 commit comments

Comments
 (0)