Google Ads

Overview

The Google Ads provider registers as googleads and manages website conversion actions and customer conversion-goal biddability for the v0.3 conversion-tracking workflow. Credentials come from the environment. The Agoraform CLI remains provider-neutral; there is no Google Ads-specific command.

Source at tag v0.3.0. Setup details: Google Ads setup.

Supported capabilities

googleads.conversion_action — website (WEBPAGE) conversion actions; read, create, update, import
googleads.customer_conversion_goal — account-default WEBSITE conversion-goal biddability; read, adopt, update, import
Logical $ref from a customer conversion goal to a managed conversion action
Computed conversion ID / conversion label when Google Ads returns them in tag snippets

Agoraform manages Google Ads configuration. It does not emit conversion events, install gtag.js / Google Tag / Google Tag Manager, or manage campaigns, budgets, ad groups, keywords, ads, or creative.

Prerequisites

A Google Ads Manager Account and developer token (Google documentation)
A Google Cloud project with the Google Ads API enabled
A Google Auth Platform app with scope https://www.googleapis.com/auth/adwords
A Desktop app OAuth client
A previously issued OAuth 2.0 refresh token for one authorized Google user
The 10-digit customer ID Agoraform should manage

Interactive OAuth consent is not implemented in v0.3.0. Service-account and multi-user OAuth workflows are not implemented.

When testing against a production Google Ads account, review conversion-action and conversion-goal settings carefully before apply: goal biddability and primary conversion settings can affect campaign optimization.

Authentication / setup

Get a developer token from a Manager Account (Admin → API Center). Test Account Access can call test accounts only.
Enable Google Ads API on a Google Cloud project. Google permits one developer token per Cloud project.
Configure Google Auth Platform (audience, test users if the app is in Testing, and the adwords scope).
Create a Desktop app OAuth client and download credentials.json.
Generate a refresh token with gcloud:

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=./credentials.json

Copy refresh_token from the printed application_default_credentials.json. Do not commit either credentials JSON file.

Set GOOGLE_ADS_CUSTOMER_ID to the advertiser customer ID (hyphens optional). If the OAuth user accesses that advertiser through a Manager Account, also set GOOGLE_ADS_LOGIN_CUSTOMER_ID.

The Google Ads scope is restricted. OAuth apps left in Testing have tester limits and a limited refresh-token lifetime.

Environment variables

GOOGLE_ADS_DEVELOPER_TOKEN     required   Google Ads API developer token
GOOGLE_ADS_CLIENT_ID           required   OAuth 2.0 client ID
GOOGLE_ADS_CLIENT_SECRET       required   OAuth 2.0 client secret
GOOGLE_ADS_REFRESH_TOKEN       required   OAuth 2.0 refresh token
GOOGLE_ADS_CUSTOMER_ID         required   10-digit customer ID (hyphens optional)
GOOGLE_ADS_LOGIN_CUSTOMER_ID   optional   manager account customer ID

Customer IDs are normalized before API calls: hyphens, spaces, and a customers/ prefix are stripped.

Store these in .agoraform.env or the process environment. Process environment variables win.

There are no non-secret YAML fields. An empty block is valid:

providers:
  googleads: {}

Putting OAuth secrets or the developer token in the manifest is rejected.

Supported resources

`googleads.conversion_action`

Website conversion actions only. Offline, call, app, and event-upload conversions are out of scope. type is always WEBPAGE and is not configurable.

- address: googleads.conversion_action.trial_started
  attributes:
    name: Trial Started
    category: SIGNUP
    value: 0
    count: ONE
    primaryForGoal: true

Attribute	Required	Description
`name`	yes	Conversion action name. Must be unique in the customer.
`category`	yes	Website category such as `SIGNUP`, `PURCHASE`, or `SUBSCRIBE_PAID`.
`status`	no	`ENABLED` (API default), `HIDDEN`, or `REMOVED`.
`value`	no	Default conversion value. When set, `alwaysUseDefaultValue` defaults to `true`.
`currency`	no	ISO 4217 currency code for the default value.
`alwaysUseDefaultValue`	no	When true, Google Ads always uses the default value.
`count`	no	`ONE` or `MANY`. Mapped to Google Ads `ONE_PER_CLICK` / `MANY_PER_CLICK`. The API default is `MANY`.
`primaryForGoal`	no	Whether this action is primary for its conversion goal. API default is `true`.
`clickThroughLookbackWindowDays`	no	Click-through window for `WEBPAGE` actions, 1–30 days.
`viewThroughLookbackWindowDays`	no	View-through window, 1–30 days.

Provider-native IDs and resource names live in local state. Computed fields also include origin, ownerCustomer, tag snippets, and, when present, conversionId and conversionLabel for downstream website tags.

Omitted optional fields are not forced onto the remote resource. Equivalent live values, including Google Ads enum aliases and default windows, do not produce a plan diff.

Import accepts the numeric conversion action ID or customers/{customerId}/conversionActions/{id}.

`googleads.customer_conversion_goal`

Google Ads automatically creates CustomerConversionGoal objects. Agoraform reads those provider-created goals and reconciles biddable; it never creates or deletes them.

Address goals by category and origin. Provider-native identity is the computed CATEGORY~ORIGIN key stored in local state.

- address: googleads.customer_conversion_goal.signup
  attributes:
    category: SIGNUP
    origin: WEBSITE
    biddable: true
    conversionAction:
      $ref: googleads.conversion_action.trial_started

Attribute	Required	Description
`category`	yes	Website category such as `SIGNUP`, `PURCHASE`, or `SUBSCRIBE_PAID`.
`origin`	yes	Must be `WEBSITE`.
`biddable`	yes	When true, Google Ads uses the goal as an account-default optimization goal.
`conversionAction`	no	`$ref` to a `googleads.conversion_action` so apply creates it first.

Campaign conversion goals and custom conversion goals are out of scope.

If the expected provider-created goal is still missing after the matching conversion action exists, Agoraform reports that Google Ads creates the object automatically and that Agoraform cannot create or delete it.

Import accepts CATEGORY~ORIGIN or customers/{customerId}/customerConversionGoals/{category}~{origin}. Import does not emit a conversionAction $ref.

Example manifest

See the quick start and the tagged conversion example.

After the conversion action exists, find conversion ID and label in Google Ads under Goals → Conversions → Trial Started → Tag setup. Website tags typically report AW-{conversionId}/{conversionLabel}. Those values are computed runtime metadata, not manifest attributes.

Known limitations

Website (WEBPAGE) conversion actions and WEBSITE customer conversion-goal biddability only
No Search campaigns, budgets, ad groups, keywords, targeting, ads, or creative
No offline, call, app, or conversion-event upload workflows
Customer conversion goals cannot be created or deleted by Agoraform
Application instrumentation, gtag.js, Google Tag, Google Tag Manager, consent handling, and conversion-event emission remain outside the provider
Developer-token + single-user OAuth refresh-token credentials only