A unique MD5 hash combining date, creative
ID, keyword, etc., used to de-duplicate entries.
| | ------ | --------------------------------------------------------------------------------------------------------- | | **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. * 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**. * 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.hockeystack.com/integrations/ad-platforms/google-ads.md?ask=