Skip to main content

​
Overview

Connecting Google Ads lets the dashboard:
  • Create, update, pause, resume, and remove App campaigns (UAC) and ad groups.
  • Upload creative assets (image, YouTube video, text) into the connected customer.
  • Pull spend, impressions, clicks, conversions, and conversion value via GAQL.
  • Run native creative experiments by rotating multiple AssetGroups inside one App Campaign.
The integration uses the Google Ads API v17 with OAuth 2.0 authentication.

​
Prerequisites

Before connecting, make sure you have:
  1. A Google Ads account in good standing (test or production).
  2. A developer token from a Google Ads manager account. The token is set on the platform side as GOOGLE_ADS_DEVELOPER_TOKEN. Self-serve provisioning is not yet supported in Phase 2 of the rollout.
  3. (Optional) A manager (MCC) account if you operate multiple client accounts. The MCC id is forwarded as the login-customer-id header so requests target the correct child customer.

​
OAuth scopes

The connection requests the following scope: 
https://www.googleapis.com/auth/adwords
This single scope grants read and write access to all accessible customers under the authenticated Google account.

​
Connect

  1. Open the Paid UA → Integrations page in the dashboard.
  2. Click Connect on the Google Ads tile.
  3. Sign in with the Google account that has access to your Ads accounts.
  4. Approve the requested scope.
  5. After redirect, choose the customer id (and manager id, if applicable) you want this integration to operate against.
The dashboard stores the OAuth refresh token, the developer token reference, and your customer / manager ids. Access tokens are rotated automatically before expiry.

​
What happens behind the scenes

OperationAPI endpoint
Create / update / pause / remove campaignPOST /customers/{id}/campaigns:mutate
Create / update ad groupPOST /customers/{id}/adGroups:mutate
Create / update ad-group adPOST /customers/{id}/adGroupAds:mutate
Upload asset (image / video / text)POST /customers/{id}/assets:mutate
Create / update asset group (split test)POST /customers/{id}/assetGroups:mutate
List campaigns and pull insightsPOST /customers/{id}/googleAds:searchStream (GAQL)
List accessible customersGET /customers:listAccessibleCustomers
Every write request carries an Idempotency-Key HTTP header so retries do not produce duplicate resources, even if the platform connection drops mid-request.

​
Rate limiting

Requests are throttled per (client_id, customer_id) using a sliding window built on Redis. The default budget is 90 requests per minute per customer. If the platform reports RESOURCE_EXHAUSTED or HTTP 429, the request is automatically retried with exponential backoff.

​
Reporting

Metrics are pulled hourly (or on demand) via GAQL. Default columns include: 
SELECT campaign.id, segments.date,
       metrics.cost_micros, metrics.impressions, metrics.clicks,
       metrics.conversions, metrics.conversions_value
FROM campaign
WHERE segments.date BETWEEN '<start>' AND '<end>'
Spend is converted from micros to USD on ingestion. The native currency, the FX rate used, and the local-currency spend are kept alongside the USD value for downstream analytics.

​
Experiments (UAC AssetGroups)

For UAC campaigns, the dashboard creates one Asset Group per variant inside a single App Campaign. Google’s optimisation engine handles traffic rotation. Variants record per-variant metrics (impressions, clicks, conversions, spend) so you can declare a winner from the dashboard.

​
Disconnect

Click Disconnect on the integration tile. The OAuth refresh token is removed from the dashboard. To fully revoke access, also remove the third-party app authorisation from your Google account.

​
Troubleshooting

  • “Google Ads developer token not configured” — GOOGLE_ADS_DEVELOPER_TOKEN is missing from the platform environment. Ask your administrator to set it.
  • “Google Ads listAccessibleCustomers returned 401” — the OAuth token has been revoked or has expired without a valid refresh token. Re-connect the integration.
  • “RESOURCE_EXHAUSTED” — your customer’s per-minute API quota was breached. The dashboard backs off automatically; if the error persists, lower campaign-mutation frequency.
  • No customers listed after connect — the signed-in Google account does not yet have access to any Google Ads customers. Add the account to a customer (or manager) in Google Ads, then reconnect.