> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appdna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Ads

> Connect a Google Ads account to manage App campaigns (UAC), pull GAQL reports, and run AssetGroup-based creative experiments from the dashboard.

## 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, configured by your administrator. Self-serve provisioning is not currently available.
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

| Operation                                 | API endpoint                                         |
| ----------------------------------------- | ---------------------------------------------------- |
| Create / update / pause / remove campaign | `POST /customers/{id}/campaigns:mutate`              |
| Create / update ad group                  | `POST /customers/{id}/adGroups:mutate`               |
| Create / update ad-group ad               | `POST /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 insights          | `POST /customers/{id}/googleAds:searchStream` (GAQL) |
| List accessible customers                 | `GET /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 rate limited. 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:

```sql theme={null}
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"** — the developer token is missing from the platform configuration. 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.