Docs: Add permissions to prereqs in Source Facebook Marketing (#32653)

airbytehq · Nov 28, 2023 · 70c267e · 70c267e
1 parent 56a876e
commit 70c267e
Showing 1 changed file with 32 additions and 7 deletions.
diff --git a/docs/integrations/sources/facebook-marketing.md b/docs/integrations/sources/facebook-marketing.md
@@ -5,20 +5,37 @@ This page guides you through the process of setting up the Facebook Marketing so
 ## Prerequisites
 
 - A [Facebook Ad Account ID](https://www.facebook.com/business/help/1492627900875762)
-- The credentials of your Facebook account with permission to access your ads account
+
+<!-- env:cloud -->
+
+#### For Airbyte Cloud
+
+If you are not the owner/admin of the Ad account, you must be granted [permissions to access the Ad account](https://www.facebook.com/business/help/155909647811305?id=829106167281625) by an admin.
+
+<!-- /env:cloud -->
+
 <!-- env:oss -->
-- (For Airbyte Open Source) A [Facebook app](https://developers.facebook.com/apps/) with the Marketing API enabled
+
+#### For Airbyte Open Source
+
+A [Facebook app](https://developers.facebook.com/apps/) with the Marketing API enabled and the following permissions:
+
+  - [ads_management](https://developers.facebook.com/docs/permissions#a)
+  - [ads_read](https://developers.facebook.com/docs/permissions#a)
+  - [business_management](https://developers.facebook.com/docs/permissions#b)
+  - [read_insights](https://developers.facebook.com/docs/permissions#r)
+
 <!-- /env:oss -->
 
 ## Setup guide
 
 <!-- env:oss -->
 
-### (For Airbyte Open Source) Generate an access token and request a rate limit increase:
+### (For Airbyte Open Source) Generate an access token and request a rate limit increase
 
 To set up Facebook Marketing as a source in Airbyte Open Source, you will first need to create a Facebook app and generate a Marketing API access token. You will then need to request a rate limit increase from Facebook. The following steps will guide you through this process:
 
-1. Navigate to [Meta for Developers](https://developers.facebook.com/apps/) and follow the steps provided in the [Facebook documentation](https://developers.facebook.com/docs/development/create-an-app/) to create a Facebook app. 
+1. Navigate to [Meta for Developers](https://developers.facebook.com/apps/) and follow the steps provided in the [Facebook documentation](https://developers.facebook.com/docs/development/create-an-app/) to create a Facebook app.
 2. While creating the app, when you are prompted for "What do you want your app to do?", select **Other**. You will also need to set the app type to **Business** when prompted.
 3. From your App’s dashboard, [set up the Marketing API](https://developers.facebook.com/docs/marketing-apis/get-started).
 4. Generate a Marketing API access token: From your App’s Dashboard, click **Marketing API** --> **Tools**. Select all the available token permissions (`ads_management`, `ads_read`, `read_insights`, `business_management`) and click **Get token**. Copy the generated token for later use.
@@ -30,9 +47,13 @@ To set up Facebook Marketing as a source in Airbyte Open Source, you will first
 
    See the Facebook [documentation on Authorization](https://developers.facebook.com/docs/marketing-api/overview/authorization/#access-levels) to request Advanced Access to the relevant permissions.
 
+:::tip
+You can use the [Access Token Tool](https://developers.facebook.com/tools/accesstoken) at any time to view your existing access tokens, including their assigned permissions and lifecycles.
+:::
+
 <!-- /env:oss -->
 
-### Set up Facebook Marketing as a source in Airbyte:
+### Set up Facebook Marketing as a source in Airbyte
 
 1. [Log in to your Airbyte Cloud](https://cloud.airbyte.io/workspaces) account, or navigate to your Airbyte Open Source dashboard.
 2. In the left navigation bar, click **Sources**. In the top-right corner, click **+ New source**.
@@ -47,7 +68,7 @@ To set up Facebook Marketing as a source in Airbyte Open Source, you will first
    **For Airbyte Open Source**: In the **Access Token** field, enter the access token you generated with your Facebook app.
    <!-- /env:oss -->
 
-#### Facebook Marketing Source Settings:
+#### Facebook Marketing Source Settings
 
 1. For **Account ID**, enter the [Facebook Ad Account ID Number](https://www.facebook.com/business/help/1492627900875762) to use when pulling data from the Facebook Marketing API. To find this ID, open your Meta Ads Manager. The Ad Account ID number is in the **Account** dropdown menu or in your browser's address bar. Refer to the [Facebook docs](https://www.facebook.com/business/help/1492627900875762) for more information.
 2. (Optional) For **Start Date**, use the provided datepicker, or enter the date programmatically in the `YYYY-MM-DDTHH:mm:ssZ` format. If not set then all data will be replicated for usual streams and only last 2 years for insight streams.
@@ -96,6 +117,8 @@ To set up Facebook Marketing as a source in Airbyte Open Source, you will first
 8. (Optional) For **Insights Window Lookback**, you may set a window in days to revisit data during syncing to capture updated conversion data from the API. Facebook allows for attribution windows of up to 28 days, during which time a conversion can be attributed to an ad. If you have set a custom attribution window in your Facebook account, please set the same value here. Otherwise, you may leave it at the default value of 28. For more information on action attributions, please refer to [the Meta Help Center](https://www.facebook.com/business/help/458681590974355?id=768381033531365).
 9. Click **Set up source** and wait for the tests to complete.
 
+<HideInUI>
+
 ## Supported sync modes
 
 The Facebook Marketing source connector supports the following sync modes:
@@ -302,4 +325,6 @@ The Facebook Marketing connector uses the `lookback_window` parameter to repeate
 | 0.1.4   | 2021-02-24 | [1902](https://github.com/airbytehq/airbyte/pull/1902)   | Add `include_deleted` option in params                                                                                                                                                                                                                                                                                        |
 | 0.1.3   | 2021-02-15 | [1990](https://github.com/airbytehq/airbyte/pull/1990)   | Support Insights stream via async queries                                                                                                                                                                                                                                                                                     |
 | 0.1.2   | 2021-01-22 | [1699](https://github.com/airbytehq/airbyte/pull/1699)   | Add incremental support                                                                                                                                                                                                                                                                                                       |
-| 0.1.1   | 2021-01-15 | [1552](https://github.com/airbytehq/airbyte/pull/1552)   | Release Native Facebook Marketing Connector                                                                                                                                                                                                                                                                                   |
+| 0.1.1   | 2021-01-15 | [1552](https://github.com/airbytehq/airbyte/pull/1552)   | Release Native Facebook Marketing Connector                                                                                                                                                                                                                                                                                   |
+
+</HideInUI>