Skip to content

Commit 6ae2248

Browse files
JustinASmithJustinASmith
committed
docs: source-facebook-marketing-native
Documentation for estuary/connectors#3409
1 parent 9e934b9 commit 6ae2248

File tree

3 files changed

+206
-2
lines changed

3 files changed

+206
-2
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: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
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+
| **`/credentials/credentials_title`** | Authentication Method | Set to `OAuth Credentials`. | string | Required |
89+
| **`/credentials/client_id`** | Client ID | The client ID obtained from your Facebook app. | string | Required for OAuth2 authentication |
90+
| **`/credentials/client_secret`** | Client Secret | The client secret obtained from your Facebook app. | string | Required for OAuth2 authentication |
91+
| **`/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 |
92+
| `/custom_insights` | Custom Insights | A list which contains insights entries. | array | |
93+
| _`/custom_insights/-/action_breakdowns`_ | Action Breakdowns | A comma separated string of chosen action_breakdowns to apply | string | |
94+
| _`/custom_insights/-/breakdowns`_ | Breakdowns | A comma separated string of chosen breakdowns to apply | string | |
95+
| _`/custom_insights/-/fields`_ | Fields | A comma separated string of chosen fields to capture | string | |
96+
| _`/custom_insights/-/name`_ | Name | The name of the insight | string | |
97+
| _`/custom_insights/-/start_date`_ | Start Date | The date from which you'd like to replicate data for this stream, in the format YYYY-MM-DDTHH:mm:ssZ. | string | |
98+
| _`/custom_insights/-/level`_ | Level | The level of the insight. Possible values are `ad`, `adset`, `campaign`, or `account`. | string | `ad` |
99+
| _`/custom_insights/-/insights_lookback_window`_ | Insights Lookback Window | The lookback window for custom insights. | integer | `28` |
100+
| `/insights_lookback_window` | Insights Lookback Window | The lookback window for insights. | integer | `28` |
101+
| **`/start_date`** | Start Date | The date from which you'd like to begin capturing data, in the format YYYY-MM-DDTHH:mm:ssZ. All data generated after this date will be replicated. | string | Required |
102+
| `/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` |
103+
| `/advanced/include_deleted` | Include Deleted | Include data from deleted Campaigns, Ads, and AdSets | boolean | `false` |
104+
105+
#### Bindings
106+
107+
| Property | Title | Description | Type | Required/Default |
108+
| ----------- | ------------- | --------------------------- | ------ | ---------------- |
109+
| **`/name`** | Data resource | Name of the data resource. | string | Required |
110+
| `/interval` | Interval | Interval between data syncs | string | |
111+
112+
### Sample
113+
114+
This sample specification reflects the manual authentication method.
115+
116+
```yaml
117+
captures:
118+
${PREFIX}/${CAPTURE_NAME}:
119+
endpoint:
120+
connector:
121+
image: ghcr.io/estuary/source-facebook-marketing-native:dev
122+
config:
123+
account_ids: "111111111111111"
124+
credentials:
125+
credentials_title: OAuth Credentials
126+
client_id: placeholder_client_id
127+
client_secret: placeholder_client_secret
128+
access_token: placeholder_access_token
129+
start_date: "2023-03-24T00:00:00Z"
130+
custom_insights:
131+
- name: ads_insights_publisher_platform
132+
action_breakdowns: ""
133+
breakdowns: publisher_platform
134+
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"
135+
insights_lookback_window: 28
136+
level: ad
137+
start_date: "2023-03-23T00:00:00Z"
138+
insights_lookback_window: 28
139+
advanced:
140+
fetch_thumbnail_images: false
141+
include_deleted: false
142+
bindings:
143+
- resource:
144+
stream: ad_account
145+
syncMode: incremental
146+
target: ${PREFIX}/ad_account
147+
- resource:
148+
stream: ad_sets
149+
syncMode: incremental
150+
target: ${PREFIX}/ad_sets
151+
- resource:
152+
stream: ads_insights
153+
syncMode: incremental
154+
target: ${PREFIX}/ads_insights
155+
- resource:
156+
stream: ads_insights_age_and_gender
157+
syncMode: incremental
158+
target: ${PREFIX}/ads_insights_age_and_gender
159+
- resource:
160+
stream: ads_insights_country
161+
syncMode: incremental
162+
target: ${PREFIX}/ads_insights_country
163+
- resource:
164+
stream: ads_insights_region
165+
syncMode: incremental
166+
target: ${PREFIX}/ads_insights_region
167+
- resource:
168+
stream: ads_insights_dma
169+
syncMode: incremental
170+
target: ${PREFIX}/ads_insights_dma
171+
- resource:
172+
stream: ads_insights_platform_and_device
173+
syncMode: incremental
174+
target: ${PREFIX}/ads_insights_platform_and_device
175+
- resource:
176+
stream: ads_insights_action_type
177+
syncMode: incremental
178+
target: ${PREFIX}/ads_insights_action_type
179+
- resource:
180+
stream: campaigns
181+
syncMode: incremental
182+
target: ${PREFIX}/campaigns
183+
- resource:
184+
stream: custom_conversions
185+
syncMode: full_refresh
186+
target: ${PREFIX}/custom_conversions
187+
- resource:
188+
stream: activities
189+
syncMode: incremental
190+
target: ${PREFIX}/activities
191+
- resource:
192+
stream: ads
193+
syncMode: incremental
194+
target: ${PREFIX}/ads
195+
- resource:
196+
stream: ad_creatives
197+
syncMode: full_refresh
198+
target: ${PREFIX}/ad_creatives
199+
```
200+
201+
[Learn more about capture definitions.](../../../concepts/captures.md)

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11

2-
# Facebook Marketing
2+
# Facebook Marketing (deprecated)
33

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

0 commit comments

Comments
 (0)