Google Ads

With HockeyStack you can seamlessly authenticate, fetch, and analyze ad performance metrics from Google Ads.

Getting Started

First find the Connect button for Google Ads in the your "API & Integrations" settings.

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

Allow HockeyStack access to your account

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:

Property	Description

account_id_hashed	Domain's API Key hashed
type	Type will always be paid-ads

id	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.