Select spec version:

Google Ads Destination Config Reference Beta

Complete Rudder CLI reference for the Google Ads destination config keys, conversion tracking, dynamic remarketing, event filtering, and secrets.
Available Plans
  • free
  • growth
  • enterprise

  •   8 minute read  

Google Ads is a web device mode destination. RudderStack’s JavaScript SDK loads the Google tag (gtag.js) in the browser and sends page loads, clicks, and conversions to Google Ads from there.

In a Google Ads destination spec:

  • type: googleads
  • definition_version: 1

Sample configuration

yaml
version: rudder/v1
kind: destination
metadata:
  name: google-ads-prod
spec:
  id: google-ads-prod
  display_name: Google Ads Production
  type: googleads
  definition_version: 1
  enabled: true
  config:
    conversion_id: "{{ .GOOGLE_ADS_CONVERSION_ID }}"
    v2: true
    allow_identify: false
    event_mapping_from_config:
      - from: Signed Up
        to: Signup

    track_conversions: true
    enable_conversion_events_filtering: true
    events_to_track_conversions:
      - Order Completed
    track_dynamic_remarketing: false

    page_load_conversions:
      - label: AbC-D_efG-h12_34-567
        name: Pricing
    default_page_conversion: XyZ-a_BcD-e98_76-543
    click_event_conversions:
      - label: QrS-t_UvW-x45_67-890
        name: Order Completed

    send_page_view: true
    conversion_linker: true
    disable_ad_personalization: false
    enable_conversion_label: false
    allow_enhanced_conversions: false

    connection_mode:
      web: device
    consent_management:
      web:
        - provider: oneTrust
          consents:
            - marketing

The above example sends only Order Completed as a conversion event and leaves dynamic remarketing off, so it omits the remarketing event list — see Conversion and remarketing tracking.

Config keys

config accepts only the keys listed below. The shared config key rules cover unknown keys, defaults, and immutability.

Google Ads runs only in web device mode, and receives identify, track, and page calls from the SDK. Every key on this page configures what the Google tag does in the browser.

Connection

conversion_id

RequiredSecret

Type: string

Description: Your Google Ads conversion ID, which identifies the account the Google tag reports to.

Notes:

  • Must start with AW-, followed by at most 100 characters.
  • A {{ path || fallback }} template is accepted in place of a literal.
See How do I get the conversion ID in Google Ads?.

sdk_base_url

Type: string

Description: Full URL that loads the Google tag script. RudderStack appends ?id=<conversion_id> to it as-is, so it must resolve to gtag.js. When omitted, https://www.googletagmanager.com/gtag/js is used.

Notes:

  • Must be a domain URL, at most 500 characters. The scheme is optional.
  • A {{ path || fallback }} template is accepted in place of a literal.
To serve the tag from your own domain, set up Google tag gateway for advertisers and enter the gateway URL that serves gtag.js.

v2

Type: boolean

Default value: true

Description: Follow the Ecommerce Event Spec when sending track events. This is what the dashboard calls Ecommerce event spec support for track events.

allow_identify

Type: boolean

Default value: false

Description: Send identify calls to Google Ads, where they define the user data for enhanced conversions.

event_mapping_from_config

Type: array of objects

Description: Maps RudderStack event names to standard Google Ads events.

Notes:

  • from — RudderStack event name. At most 100 characters, or a {{ path || fallback }} template.
  • to — one of Lead, PageVisit, ViewCategory, Signup, WatchVideo, Checkout, Search, AddToCart, or purchase. Note the lowercase purchase. Templates aren’t accepted here.
yaml
event_mapping_from_config:
  - from: Signed Up
    to: Signup

Conversion and remarketing tracking

Each tracking switch gates a filtering toggle, which gates an event list. Rudder CLI accepts every key regardless of the switches above it, so a list whose toggle is off is stored and ignored.

track_conversions

Type: boolean

Default value: true

Description: Send conversion events to Google Ads.

enable_conversion_events_filtering

Type: boolean

Default value: false

Description: Treat only the events in events_to_track_conversions as conversions. When false, every event is a conversion event.

Notes:

  • Applies when track_conversions is true. Leave it unset otherwise.

events_to_track_conversions

Type: array of strings

Description: Event names to send as conversion events.

Notes:

  • Applies when track_conversions and enable_conversion_events_filtering are both true. Leave it unset otherwise.
  • Each name is at most 100 characters, or a {{ path || fallback }} template.

track_dynamic_remarketing

Type: boolean

Default value: false

Description: Send dynamic remarketing events.

enable_dynamic_remarketing_events_filtering

Type: boolean

Default value: false

Description: Treat only the events in events_to_track_dynamic_remarketing as remarketing events. When false, every event is a remarketing event.

Notes:

  • Applies when track_dynamic_remarketing is true. Leave it unset otherwise.

events_to_track_dynamic_remarketing

Type: array of strings

Description: Event names to send as dynamic remarketing events.

Notes:

  • Applies when track_dynamic_remarketing and enable_dynamic_remarketing_events_filtering are both true. Leave it unset otherwise.
  • Each name is at most 100 characters, or a {{ path || fallback }} template.

dynamic_remarketing

Internal

Type: object

Description: Per-source dynamic remarketing flag, keyed by web. Remarketing is controlled by track_dynamic_remarketing instead.

Notes:

  • web — boolean.
Leave it unset on a new destination. An imported spec may carry it from older configurations.

Page and click conversions

A conversion label identifies the conversion action in Google Ads — see How do I get the conversion label for Google Ads?.

page_load_conversions

Type: array of objects

Description: Conversions fired when a named page event loads.

Notes:

  • label — the conversion label from Google Ads.
  • name — name of the page event that fires the conversion.
  • Each is at most 100 characters, or a {{ path || fallback }} template.
yaml
page_load_conversions:
  - label: AbC-D_efG-h12_34-567
    name: Pricing

default_page_conversion

Type: string

Description: Conversion label used for page events that don’t match an entry in page_load_conversions.

Notes:

  • At most 100 characters, or a {{ path || fallback }} template.

click_event_conversions

Type: array of objects

Description: Conversions fired by named track events.

Notes:

  • label — the conversion label from Google Ads.
  • name — name of the track event that fires the conversion.
  • Each is at most 100 characters, or a {{ path || fallback }} template.

Tag behavior

send_page_view

Type: boolean

Default value: true

Description: Send page events to Google Ads automatically.

conversion_linker

Type: boolean

Default value: true

Description: Let the Google tag set first-party cookies on your domain for conversion measurement. Turning it off can make conversion measurement less accurate.

disable_ad_personalization

Type: boolean

Default value: false

Description: Disable ad personalization for the events this tag sends.

enable_conversion_label

Type: boolean

Default value: false

Description: Label every conversion event conversion. When false, each conversion keeps its event name as the label.

allow_enhanced_conversions

Type: boolean

Default value: false

Description: Send enhanced conversions programmatically. Pair it with allow_identify to supply the user data.

Event filtering

event_filtering

Type: object

Description: Restricts which events the SDK passes to Google Ads, by event name. See Client-side Events Filtering.

Notes:

  • whitelist — array of event names to allow; every other track event is dropped.
  • blacklist — array of event names to drop; every other track event is allowed.
  • The two are mutually exclusive, and Rudder CLI enforces it — setting both fails validation.
  • Each name is at most 100 characters, or a {{ path || fallback }} template.
This is separate from events_to_track_conversions: filtering decides whether an event reaches Google Ads at all, and the conversion list decides which of those count as conversions.

Per-source keys

Both keys are objects keyed by the local source type — the tokens listed under Source types. A key naming a source type this destination doesn’t support fails validation.

connection_mode

Type: object

Description: Maps each source type you connect to the mode its events reach Google Ads in. Google Ads accepts only web: device.

Notes:

yaml
connection_mode:
  web: device

Source types

Google Ads accepts events from these source types in the mentioned connection modes:

Source typeConnection mode
webdevice

Google Ads accepts only web sources, and only in device mode — the SDK loads the Google tag in the browser, and no events pass through RudderStack’s servers. See Google Ads device mode.

Connect a source

An event stream connection to this destination is checked against two rules at validate time.

The source’s type must be supported. A source’s type resolves to one of the tokens above before the check — a JavaScript source resolves to web, and webhook and server-side SDK sources resolve to cloud. Any source other than a JavaScript source reports:

destination 'google-ads-prod' (type 'googleads') does not support source 'my-source':
source type 'cloud' is not among supported source types: web

The destination config must carry a connection_mode entry for that source type. This lives on the destination spec, not on the connection spec. Without it:

destination 'google-ads-prod' config has no 'connection_mode' entry for source type 'web'

Google Ads needs no additional config keys to connect a web source.

Secrets

conversion_id is the only secret key. Write it as a {{ .VAR }} reference and supply the value at apply time:

yaml
config:
  conversion_id: "{{ .GOOGLE_ADS_CONVERSION_ID }}"
bash
export RUDDER_GOOGLE_ADS_CONVERSION_ID="AW-123456789"
rudder-cli apply

# or
rudder-cli apply --var-file secrets.vars.yaml

Note that:

  • In device mode the conversion ID is embedded in the page’s JavaScript, so treating it as a secret keeps it out of your YAML but doesn’t hide it from the browser.
  • The YAML that rudder-cli import writes may or may not include secret keys. Before you apply, make sure every secret key your configuration needs is present and populated through variable substitution.

See How to Use Variable Substitution in Rudder CLI.

See more

Questions? Let's figure it out together.

Join the RudderStack Slack community to connect with other users, customers, and the RudderStack team — or reach out for direct support.

Slack community Join now Email support Reach out