diff --git a/docs/integrations/sources/google-ads.inapp.md b/docs/integrations/sources/google-ads.inapp.md index 4804f0603539..ff2b18e3edc9 100644 --- a/docs/integrations/sources/google-ads.inapp.md +++ b/docs/integrations/sources/google-ads.inapp.md @@ -1,17 +1,50 @@ ## Prerequisites -- A [Google Ads Account](https://support.google.com/google-ads/answer/6366720) [linked](https://support.google.com/google-ads/answer/7459601) to a [Google Ads Manager account](https://ads.google.com/home/tools/manager-accounts/) +- A [Google Ads Account](https://support.google.com/google-ads/answer/6366720) [linked](https://support.google.com/google-ads/answer/7459601) to a Google Ads Manager account + +- (For Airbyte Open Source): + - A Developer Token + - OAuth credentials to authenticate your Google account + ## Setup guide -1. Enter a **Name** for your source. -2. Click **Sign in with Google** to authenticate your Google Ads account. -3. Enter a comma-separated list of the [Customer ID(s)](https://support.google.com/google-ads/answer/1704344) for your account. -4. Enter the **Start Date** in YYYY-MM-DD format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data. -5. (Optional) Enter a custom [GAQL](#custom-query-understanding-google-ads-query-language) query. -6. (Optional) If the access to your account is through a [Google Ads Manager account](https://ads.google.com/home/tools/manager-accounts/), enter the [**Login Customer ID for Managed Accounts**](https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid) of the Google Ads Manager account. -7. (Optional) Enter a [**Conversion Window**](https://support.google.com/google-ads/answer/3123169?hl=en). -8. (Optional) Enter the **End Date** in YYYY-MM-DD format. The data added after this date will not be replicated. -9. Click **Set up source**. + + + +To set up the Google Ads source connector with Airbyte Open Source, you will first need to obtain a developer token, as well as credentials for OAuth authentication. For more information on the steps involved, please refer to our [full documentation](https://docs.airbyte.com/integrations/sources/google-ads#setup-guide). + + + + +### For Airbyte Cloud: + +1. Enter a **Source name** of your choosing. +2. Click **Sign in with Google** to authenticate your Google Ads account. In the pop-up, select the appropriate Google account and click **Continue** to proceed. +3. Enter a comma-separated list of the **Customer ID(s)** for your account. These IDs are 10-digit numbers that uniquely identify your account. To find your Customer ID, please follow [Google's instructions](https://support.google.com/google-ads/answer/1704344). +4. Enter a **Start Date** using the provided datepicker, or by programmatically entering the date in YYYY-MM-DD format. The data added on and after this date will be replicated. +5. (Optional) You can use the **Custom GAQL Queries** field to enter a custom query using Google Ads Query Language. Click **Add** and enter your query, as well as the desired name of the table for this data in the destination. Multiple queries can be provided. For more information on formulating these queries, refer to our [guide below](#custom-query-understanding-google-ads-query-language). +6. (Required for Manager accounts) If accessing your account through a Google Ads Manager account, you must enter the [**Customer ID**](https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid) of the Manager account. +7. (Optional) Enter a **Conversion Window**. This is the number of days after an ad interaction during which a conversion is recorded in Google Ads. For more information on this topic, refer to the [Google Ads Help Center](https://support.google.com/google-ads/answer/3123169?hl=en). This field defaults to 14 days. +8. (Optional) Enter an **End Date** in YYYY-MM-DD format. Any data added after this date will not be replicated. Leaving this field blank will replicate all data from the start date onward. +9. Click **Set up source** and wait for the tests to complete. + + + + +### For Airbyte Open Source: + +1. Enter a **Source name** of your choosing. +2. Enter the **Developer Token** you obtained from Google. +3. To authenticate your Google account, enter your Google application's **Client ID**, **Client Secret**, **Refresh Token**, and optionally, the **Access Token**. +4. Enter a comma-separated list of the **Customer ID(s)** for your account. These IDs are 10-digit numbers that uniquely identify your account. To find your Customer ID, please follow [Google's instructions](https://support.google.com/google-ads/answer/1704344). +5. Enter a **Start Date** using the provided datepicker, or by programmatically entering the date in YYYY-MM-DD format. The data added on and after this date will be replicated. +6. (Optional) You can use the **Custom GAQL Queries** field to enter a custom query using Google Ads Query Language. Click **Add** and enter your query, as well as the desired name of the table for this data in the destination. Multiple queries can be provided. For more information on formulating these queries, refer to our [guide below](#custom-query-understanding-google-ads-query-language). +7. (Required for Manager accounts) If accessing your account through a Google Ads Manager account, you must enter the [**Customer ID**](https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid) of the Manager account. +8. (Optional) Enter a **Conversion Window**. This is the number of days after an ad interaction during which a conversion is recorded in Google Ads. For more information on this topic, refer to the [Google Ads Help Center](https://support.google.com/google-ads/answer/3123169?hl=en). This field defaults to 14 days. +9. (Optional) Enter an **End Date** in YYYY-MM-DD format. Any data added after this date will not be replicated. Leaving this field blank will replicate all data from the start date onward. +10. Click **Set up source** and wait for the tests to complete. + + ## Custom Query: Understanding Google Ads Query Language Additional streams for Google Ads can be dynamically created using custom queries. @@ -36,4 +69,4 @@ Follow Google's guidance on [Selectability between segments and metrics](https:/ For an existing Google Ads source, when you are updating or removing Custom GAQL Queries, you should also subsequently refresh your source schema to pull in any changes. ::: -For detailed information on supported sync modes, supported streams, performance considerations, refer to the full documentation for [Google Ads](https://docs.airbyte.com/integrations/sources/google-ads/). +For detailed information on supported sync modes, supported streams, performance considerations, refer to the [full documentation for Google Ads](https://docs.airbyte.com/integrations/sources/google-ads/). diff --git a/docs/integrations/sources/google-ads.md b/docs/integrations/sources/google-ads.md index 9b0304d61ffc..c20255ed6e0a 100644 --- a/docs/integrations/sources/google-ads.md +++ b/docs/integrations/sources/google-ads.md @@ -4,9 +4,11 @@ This page contains the setup guide and reference information for the Google Ads ## Prerequisites -- A [Google Ads Account](https://support.google.com/google-ads/answer/6366720) [linked](https://support.google.com/google-ads/answer/7459601) to a [Google Ads Manager account](https://ads.google.com/home/tools/manager-accounts/) +- A [Google Ads Account](https://support.google.com/google-ads/answer/6366720) [linked](https://support.google.com/google-ads/answer/7459601) to a Google Ads Manager account -- (For Airbyte Open Source) [A developer token](#step-1-for-airbyte-oss-apply-for-a-developer-token) +- (For Airbyte Open Source): + - A Developer Token + - OAuth credentials to authenticate your Google account ## Setup guide @@ -15,63 +17,76 @@ This page contains the setup guide and reference information for the Google Ads ### Step 1: (For Airbyte Open Source) Apply for a developer token +To set up the Google Ads source connector with Airbyte Open Source, you will need to obtain a developer token. This token allows you to access your data from the Google Ads API. Please note that Google is selective about which software and use cases are issued this token. The Airbyte team has worked with the Google Ads team to allowlist Airbyte and ensure you can get a developer token (see [issue 1981](https://github.com/airbytehq/airbyte/issues/1981) for more information on this topic). + +1. To proceed with obtaining a developer token, you will first need to create a [Google Ads Manager account](https://ads.google.com/home/tools/manager-accounts/). Standard Google Ads accounts cannot generate a developer token. + +2. To apply for the developer token, please follow [Google's instructions](https://developers.google.com/google-ads/api/docs/first-call/dev-token). + +3. When you apply for the token, make sure to include the following: + - Why you need the token (example: Want to run some internal analytics) + - That you will be using the Airbyte Open Source project + - That you have full access to the code base (because we're open source) + - That you have full access to the server running the code (because you're self-hosting Airbyte) + :::note -You'll need to create a [Google Ads Manager account](https://ads.google.com/home/tools/manager-accounts/) since Google Ads accounts cannot generate a developer token. +You will _not_ be able to access your data via the Google Ads API until this token is approved. You cannot use a test developer token; it has to be at least a basic developer token. The approval process typically takes around 24 hours. ::: -To set up the Google Ads source connector with Airbyte Open Source, you'll need a developer token. This token allows you to access your data from the Google Ads API. However, Google is selective about which software and use cases can get a developer token. The Airbyte team has worked with the Google Ads team to allowlist Airbyte and make sure you can get a developer token (see [issue 1981](https://github.com/airbytehq/airbyte/issues/1981) for more information). +### Step 2: (For Airbyte Open Source) Obtain your OAuth credentials -Follow [Google's instructions](https://developers.google.com/google-ads/api/docs/first-call/dev-token) to apply for the token. Note that you will _not_ be able to access your data via the Google Ads API until this token is approved. You cannot use a test developer token; it has to be at least a basic developer token. It usually takes Google 24 hours to respond to these applications. +If you are using Airbyte Open Source, you will need to obtain the following OAuth credentials to authenticate your Google Ads account: -When you apply for a token, make sure to mention: +- Client ID +- Client Secret +- Refresh Token -- Why you need the token (example: Want to run some internal analytics) -- That you will be using the Airbyte Open Source project -- That you have full access to the code base (because we're open source) -- That you have full access to the server running the code (because you're self-hosting Airbyte) +Please refer to [Google's documentation](https://developers.google.com/identity/protocols/oauth2) for detailed instructions on how to obtain these credentials. -### Step 2: Set up the Google Ads connector in Airbyte +### Step 3: Set up the Google Ads connector in Airbyte -**For Airbyte Cloud:** +#### For Airbyte Cloud: To set up Google Ads as a source in Airbyte Cloud: -1. [Log into your Airbyte Cloud](https://cloud.airbyte.com/workspaces) account. -2. Click **Sources** and then click **+ New source**. -3. On the Set up the source page, select **Google Ads** from the Source type dropdown. -4. Enter a **Name** for your source. -5. Click **Sign in with Google** to authenticate your Google Ads account. -6. Enter a comma-separated list of the [Customer ID(s)](https://support.google.com/google-ads/answer/1704344) for your account. -7. Enter the **Start Date** in YYYY-MM-DD format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data. -8. (Optional) Enter a custom [GAQL](#custom-query-understanding-google-ads-query-language) query. -9. (Optional) If the access to your account is through a [Google Ads Manager account](https://ads.google.com/home/tools/manager-accounts/), enter the [**Login Customer ID for Managed Accounts**](https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid) of the Google Ads Manager account. -10. (Optional) Enter a [**Conversion Window**](https://support.google.com/google-ads/answer/3123169?hl=en). -11. (Optional) Enter the **End Date** in YYYY-MM-DD format. The data added after this date will not be replicated. -12. Click **Set up source**. +1. [Log in to your Airbyte Cloud](https://cloud.airbyte.com/workspaces) account. +2. In the left navigation bar, click **Sources**. In the top-right corner, click **+ New source**. +3. Find and select **Google Ads** from the list of available sources. +4. Enter a **Source name** of your choosing. +5. Click **Sign in with Google** to authenticate your Google Ads account. In the pop-up, select the appropriate Google account and click **Continue** to proceed. +6. Enter a comma-separated list of the **Customer ID(s)** for your account. These IDs are 10-digit numbers that uniquely identify your account. To find your Customer ID, please follow [Google's instructions](https://support.google.com/google-ads/answer/1704344). +7. Enter a **Start Date** using the provided datepicker, or by programmatically entering the date in YYYY-MM-DD format. The data added on and after this date will be replicated. +8. (Optional) You can use the **Custom GAQL Queries** field to enter a custom query using Google Ads Query Language. Click **Add** and enter your query, as well as the desired name of the table for this data in the destination. Multiple queries can be provided. For more information on formulating these queries, refer to our [guide below](#custom-query-understanding-google-ads-query-language). +9. (Required for Manager accounts) If accessing your account through a Google Ads Manager account, you must enter the [**Customer ID**](https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid) of the Manager account. +10. (Optional) Enter a **Conversion Window**. This is the number of days after an ad interaction during which a conversion is recorded in Google Ads. For more information on this topic, refer to the [Google Ads Help Center](https://support.google.com/google-ads/answer/3123169?hl=en). This field defaults to 14 days. +11. (Optional) Enter an **End Date** in YYYY-MM-DD format. Any data added after this date will not be replicated. Leaving this field blank will replicate all data from the start date onward. +12. Click **Set up source** and wait for the tests to complete. -**For Airbyte Open Source:** +#### For Airbyte Open Source: To set up Google Ads as a source in Airbyte Open Source: -1. Log into your Airbyte Open Source account. -2. Click **Sources** and then click **+ New source**. -3. On the Set up the source page, select **Google Ads** from the Source type dropdown. -4. Enter a **Name** for your source. -5. Enter the [**Developer Token**](#step-1-for-airbyte-oss-apply-for-a-developer-token). -6. To authenticate your Google account via OAuth, enter your Google application's [**Client ID**, **Client Secret**, **Refresh Token**, and optionally, the **Access Token**](https://developers.google.com/google-ads/api/docs/first-call/overview). -7. Enter a comma-separated list of the [Customer ID(s)](https://support.google.com/google-ads/answer/1704344) for your account. -8. Enter the **Start Date** in YYYY-MM-DD format. The data added on and after this date will be replicated. If this field is blank, Airbyte will replicate all data. -9. (Optional) Enter a custom [GAQL](#custom-query-understanding-google-ads-query-language) query. -10. (Optional) If the access to your account is through a [Google Ads Manager account](https://ads.google.com/home/tools/manager-accounts/), enter the [**Login Customer ID for Managed Accounts**](https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid) of the Google Ads Manager account. -11. (Optional) Enter a [**Conversion Window**](https://support.google.com/google-ads/answer/3123169?hl=en). -12. (Optional) Enter the **End Date** in YYYY-MM-DD format. The data added after this date will not be replicated. -13. Click **Set up source**. +1. Log in to your Airbyte Open Source account. +2. In the left navigation bar, click **Sources**. In the top-right corner, click **+ New source**. +3. Find and select **Google Ads** from the list of available sources. +4. Enter a **Source name** of your choosing. +5. Enter the **Developer Token** you obtained from Google. +6. To authenticate your Google account, enter your Google application's **Client ID**, **Client Secret**, **Refresh Token**, and optionally, the **Access Token**. +7. Enter a comma-separated list of the **Customer ID(s)** for your account. These IDs are 10-digit numbers that uniquely identify your account. To find your Customer ID, please follow [Google's instructions](https://support.google.com/google-ads/answer/1704344). +8. Enter a **Start Date** using the provided datepicker, or by programmatically entering the date in YYYY-MM-DD format. The data added on and after this date will be replicated. +9. (Optional) You can use the **Custom GAQL Queries** field to enter a custom query using Google Ads Query Language. Click **Add** and enter your query, as well as the desired name of the table for this data in the destination. Multiple queries can be provided. For more information on formulating these queries, refer to our [guide below](#custom-query-understanding-google-ads-query-language). +10. (Required for Manager accounts) If accessing your account through a Google Ads Manager account, you must enter the [**Customer ID**](https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid) of the Manager account. +11. (Optional) Enter a **Conversion Window**. This is the number of days after an ad interaction during which a conversion is recorded in Google Ads. For more information on this topic, see the section on [Conversion Windows](#note-on-conversion-windows) below, or refer to the [Google Ads Help Center](https://support.google.com/google-ads/answer/3123169?hl=en). This field defaults to 14 days. +12. (Optional) Enter an **End Date** in YYYY-MM-DD format. Any data added after this date will not be replicated. Leaving this field blank will replicate all data from the start date onward. +13. Click **Set up source** and wait for the tests to complete. + + ## Supported sync modes @@ -82,11 +97,6 @@ The Google Ads source connector supports the following [sync modes](https://docs - [Incremental Sync - Append](https://docs.airbyte.com/understanding-airbyte/connections/incremental-append) - [Incremental Sync - Deduped History](https://docs.airbyte.com/understanding-airbyte/connections/incremental-deduped-history) -**Important note**: - - Usage of Conversion Window may lead to duplicates in Incremental Sync, - because connector is forced to read data in the given range (Last Sync - Conversion window) - ## Supported Streams The Google Ads source connector can sync the following tables. It can also sync custom queries using GAQL. @@ -100,21 +110,21 @@ The Google Ads source connector can sync the following tables. It can also sync - [ad_group_labels](https://developers.google.com/google-ads/api/fields/v11/ad_group_label) - [campaign_labels](https://developers.google.com/google-ads/api/fields/v11/campaign_label) - [click_view](https://developers.google.com/google-ads/api/reference/rpc/v11/ClickView) -- [keyword](https://developers.google.com/google-ads/api/fields/v11/keyword_view) - [geographic](https://developers.google.com/google-ads/api/fields/v11/geographic_view) +- [keyword](https://developers.google.com/google-ads/api/fields/v11/keyword_view) Note that `ad_groups`, `ad_group_ads`, and `campaigns` contain a `labels` field, which should be joined against their respective `*_labels` streams if you want to view the actual labels. For example, the `ad_groups` stream contains an `ad_group.labels` field, which you would join against the `ad_group_labels` stream's `label.resource_name` field. ### Report Tables +- [account_performance_report](https://developers.google.com/google-ads/api/docs/migration/mapping#account_performance) - [ad_groups](https://developers.google.com/google-ads/api/fields/v14/ad_group) +- [ad_group_ad_report](https://developers.google.com/google-ads/api/docs/migration/mapping#ad_performance) - [ad_group_criterions](https://developers.google.com/google-ads/api/fields/v14/ad_group_criterion) - [ad_group_criterion_labels](https://developers.google.com/google-ads/api/fields/v14/ad_group_criterion_label) - [campaigns](https://developers.google.com/google-ads/api/fields/v11/campaign) -- [campaign budget](https://developers.google.com/google-ads/api/fields/v13/campaign_budget) +- [campaign_budget](https://developers.google.com/google-ads/api/fields/v13/campaign_budget) - [customer_labels](https://developers.google.com/google-ads/api/fields/v14/customer_label) -- [account_performance_report](https://developers.google.com/google-ads/api/docs/migration/mapping#account_performance) -- [ad_group_ad_report](https://developers.google.com/google-ads/api/docs/migration/mapping#ad_performance) - [display_keyword_report](https://developers.google.com/google-ads/api/docs/migration/mapping#display_keyword_performance) - [display_topics_report](https://developers.google.com/google-ads/api/docs/migration/mapping#display_topics_performance) - [labels](https://developers.google.com/google-ads/api/fields/v14/label) @@ -127,8 +137,6 @@ Due to Google Ads API constraints, the `click_view` stream retrieves data one da For incremental streams, data is synced up to the previous day using your Google Ads account time zone since Google Ads can filter data only by [date](https://developers.google.com/google-ads/api/fields/v11/ad_group_ad#segments.date) without time. Also, some reports cannot load data real-time due to Google Ads [limitations](https://support.google.com/google-ads/answer/2544985?hl=en). - - ## Custom Query: Understanding Google Ads Query Language Additional streams for Google Ads can be dynamically created using custom queries. @@ -155,7 +163,16 @@ Follow Google's guidance on [Selectability between segments and metrics](https:/ For an existing Google Ads source, when you are updating or removing Custom GAQL Queries, you should also subsequently refresh your source schema to pull in any changes. ::: - +## Note on Conversion Windows + +In digital advertising, a 'conversion' typically refers to a user undertaking a desired action after viewing or interacting with an ad. This could be anything from clicking through to the advertiser's website, signing up for a newsletter, making a purchase, and so on. The conversion window is the period of time after a user sees or clicks on an ad during which their actions can still be credited to that ad. + +For example, imagine an online shoe store runs an ad and sets a conversion window of 30 days. If you click on that ad today, any purchases you make on the shoe store's site within the next 30 days will be considered conversions resulting from that ad. +The length of the conversion window can vary depending on the goals of the advertiser and the nature of the product or service. Some businesses might set a shorter conversion window if they're promoting a limited-time offer, while others might set a longer window if they're advertising a product that consumers typically take a while to think about before buying. + +In essence, the conversion window is a tool for measuring the effectiveness of an advertising campaign. By tracking the actions users take after viewing or interacting with an ad, businesses can gain insight into how well their ads are working and adjust their strategies accordingly. + +In the case of configuring the Google Ads source connector, each time a sync is run the connector will retrieve all conversions that were active within the specified conversion window. For example, if you set a conversion window of 30 days, each time a sync is run, the connector will pull all conversions that were active within the past 30 days. Due to this mechanism, it may seem like the same campaigns, ad groups, or ads have different conversion numbers. However, in reality, each data record accurately reflects the number of conversions for that particular resource at the time of extracting the data from the Google Ads API. ## Performance considerations @@ -246,4 +263,3 @@ Due to a limitation in the Google Ads API which does not allow getting performan | `0.1.2` | 2021-07-06 | [4539](https://github.com/airbytehq/airbyte/pull/4539) | Add `AIRBYTE_ENTRYPOINT` for Kubernetes support | | `0.1.1` | 2021-06-23 | [4288](https://github.com/airbytehq/airbyte/pull/4288) | Fix `Bugfix: Correctly declare required parameters` | -