# Google Ads

## Getting Started

First find the Connect button for Google Ads in the your Atlas > Ingest.  

<figure><img src="https://318687664-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FedLASfWbQxGa0eYkwALS%2Fuploads%2FDjNJyHKd5RuH1y8tbOd3%2FScreenshot%202025-01-16%20at%203.17.06%E2%80%AFPM.png?alt=media&#x26;token=1cb2908b-7a6f-40fb-8d16-18dc54f190ee" alt=""><figcaption></figcaption></figure>

Sign in with your Google Account that has access to Google Ads

<figure><img src="https://318687664-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FedLASfWbQxGa0eYkwALS%2Fuploads%2FPhfBFg9v1zsRwAeNUvU3%2FScreenshot%202025-01-16%20at%203.18.13%E2%80%AFPM.png?alt=media&#x26;token=522fcd5d-5776-41a7-88f5-3b3da166925e" alt=""><figcaption></figcaption></figure>

Allow HockeyStack access to your account

<figure><img src="https://318687664-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FedLASfWbQxGa0eYkwALS%2Fuploads%2FQfgxPEwBcL2aYQ15phH6%2FScreenshot%202025-01-16%20at%203.21.00%E2%80%AFPM.png?alt=media&#x26;token=55414f01-5e4d-4aec-a6b8-5178d9788125" alt=""><figcaption></figcaption></figure>

Select the ad account that you want to connect.  After granting permissions, you'll be redirected back to the ad reporting platform, confirming the successful connection.

Data will then get pulled **daily** so that it can be synced to users' tables.

## What gets tracked as Metadata

Information collected from each ad gets stored in our `metadata`  table. Each row has the following format:&#x20;

| **Property** | **Description** |
| ------------ | --------------- |

| **account\_id\_hashed** | Domain's API Key hashed        |
| ----------------------- | ------------------------------ |
| **type**                | Type will always be `paid-ads` |

| **id** | <p>A unique MD5 hash combining date, creative </p><p>ID, keyword, etc., used to de-duplicate entries.</p> |
| ------ | --------------------------------------------------------------------------------------------------------- |

| **date** | The date of the metrics (in `YYYY-MM-DD` format). |
| -------- | ------------------------------------------------- |

| **account\_id** | The Google Ads customer ID (e.g., `"123-456-7890"`). |
| --------------- | ---------------------------------------------------- |

| **network** | The advertising network (always `"Google Ads"` in this integration). |
| ----------- | -------------------------------------------------------------------- |

| **campaign\_id** | The identifier of the campaign (e.g., `"123456789"`). |
| ---------------- | ----------------------------------------------------- |

| **campaign\_name** | The display name of the campaign (e.g., `"Brand Awareness 2024"`). |
| ------------------ | ------------------------------------------------------------------ |

| **adgroup\_id** | The identifier of the ad group within that campaign. |
| --------------- | ---------------------------------------------------- |

| **adgroup\_name** | The display name of the ad group. |
| ----------------- | --------------------------------- |

| **ad\_id** | The identifier of the specific ad (e.g., `"987654321"`). |
| ---------- | -------------------------------------------------------- |

| **utm\_source** | The UTM source parameter extracted from the ad’s final/tracking URL or defaulted to `"google"`. |
| --------------- | ----------------------------------------------------------------------------------------------- |

| **utm\_campaign** | The UTM campaign parameter extracted from the ad’s URL or fallback to the campaign name. |
| ----------------- | ---------------------------------------------------------------------------------------- |

| **utm\_medium** | The UTM medium parameter extracted from the ad’s URL (e.g., `"cpc"`). |
| --------------- | --------------------------------------------------------------------- |

| **utm\_content** | The UTM content parameter extracted from the ad’s URL. |
| ---------------- | ------------------------------------------------------ |

| **utm\_term** | The UTM term parameter extracted from the ad’s URL (or `keyword`). |
| ------------- | ------------------------------------------------------------------ |

| **keyword** | The matched keyword text (if applicable to the ad type). |
| ----------- | -------------------------------------------------------- |

| **impressions** | The total impressions for that ad on the specified date. |
| --------------- | -------------------------------------------------------- |

| **clicks** | The total clicks for that ad on the specified date. |
| ---------- | --------------------------------------------------- |

| **cost** | The total cost of those clicks, expressed in the account’s currency (converted from `costMicros`). |
| -------- | -------------------------------------------------------------------------------------------------- |

| **currency** | The currency code (e.g., `"USD"`), usually derived from `account.currency` or defaulted to `"USD"`. |
| ------------ | --------------------------------------------------------------------------------------------------- |

## High-Level Integration Flow

1. **OAuth Connection**
   * A user connects their Google Ads account via OAuth, granting us read access.
2. **Refresh/Validate Tokens**
   * We periodically refresh the OAuth token with `refreshOAuth` to keep our access valid.
   * We validate permissions with `testPermission`.
3. **Fetching Account and Campaign Data**
   * We call `getAdAccounts` to list accessible accounts.
   * For each account, we run `fetchCustomerCurrencies` to map currency codes to customer IDs.
   * We call `processAccount` (the main function to pull historical performance data in daily batches).
4. **Data Processing**
   * Within `processAccount`, we break date ranges into smaller windows (e.g., 30 days).
   * For each window, we call `processRequest` (which internally calls `createRequestConfig` and processes multiple pages of results).
   * **`createRequestConfig`** is the function responsible for **building the request** that goes to Google Ads.&#x20;
     * It starts with a **base configuration** (like headers, tokens, and the account’s customer ID), then **adds a custom query** based on your needs—such as whether you want **keyword data**, **Performance Max** campaigns, **YouTube** campaigns, or a specific **date range**.&#x20;
     * It also handles **pagination** (by adding a `pageToken` when there’s more data). Essentially, this function combines all the **who, what, and when** into a single request so we can **precisely fetch** the desired metrics from Google Ads.
   * We parse the raw results in `formatData`, combine them with any extracted UTMs in `extractURL`, and then store them in our system with `insertToMetadata`.
5. **Reporting & Utilities**
   * We can also call `pullCampaignReporting` to get summarized campaign-level data.
   * `getDuplicateUTMs` can help identify multiple different UTMs attached to the same campaign.
   * If the user removes the connection, we call `revokeOAuth` to invalidate tokens.