Google Ads
With HockeyStack you can seamlessly authenticate, fetch, and analyze ad performance metrics from Google Ads.
Last updated
With HockeyStack you can seamlessly authenticate, fetch, and analyze ad performance metrics from Google Ads.
Last updated
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.
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".
OAuth Connection
A user connects their Google Ads account via OAuth, granting us read access.
Refresh/Validate Tokens
We periodically refresh the OAuth token with refreshOAuth to keep our access valid.
We validate permissions with testPermission.
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).
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.
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.
