Skip to main content
Ask your AI

Google Ads

Web Source code Package

Google Ads conversion tracking records the conversions of your Google Ads campaigns. The unified gtag destination sends them.

Installation​

npm install @walkeros/web-destination-gtag
import { startFlow } from '@walkeros/collector';
import { destinationGtag } from '@walkeros/web-destination-gtag';

const { elb } = await startFlow({
  destinations: {
    gtag: {
      code: destinationGtag,
      config: {
        loadScript: true,
        settings: {
          ads: {
            conversionId: 'AW-123456789',
            currency: 'EUR',
          },
        },
        mapping: {
          order: {
            complete: {
              name: 'purchase',
              settings: {
                ads: {
                  label: 'purchase_conversion',
                },
              },
            },
          },
        },
      },
    },
  },
});

loadScript: true makes walkerOS add gtag.js to the page; without it, events reach Google only if your page loads gtag.js itself.

The snippet sets no consent, so conversions, and with enhanced conversions the customer's email, phone and address, go to Google without marketing consent. Add consent: { marketing: true } to config, next to settings, before you go live: the destination then sends nothing until marketing is granted (see Google Consent Mode).

Configuration​

This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.

Settings​

PropertyTypeDescriptionMore
comoboolean | objectConsent mode configuration: false (disabled), true (use defaults), or custom mapping
como_advancedboolean | numberAdvanced consent mode (non-EU): emit denied default at page load with wait_for_update (true=500ms, or a number of ms)
ga4ga4GA4-specific configuration settings
measurementId*stringGA4 Measurement ID from Google Analytics
debugbooleanEnable debug mode for GA4
initbooleanSet to false when an external tag manager already configures this measurement ID: walkerOS then skips the gtag bootstrap (js, config and the script load) and only sends events, routed via send_to (default: true)
pageviewbooleanSet to false to stop gtag's own page_view on config (sends send_page_view: false), so a pushed page view is not counted twice. Page views from the web stream's enhanced measurement of history changes still fire (default: true)
scriptSrcstringFull URL to load gtag.js first-party from a tagging server, used verbatim without the measurement ID (like https://example.com/metrics/tag_serving_path/). Needs a tag serving path configured in the server container; falls back to googletagmanager.com if it fails to load
server_container_urlstringServer-side GTM container URL
snakeCasebooleanLowercase the event name and replace its spaces with underscores (like true). Applies to the event name only, never to parameter names
transport_urlstringCustom transport URL for GA4
dataanyCustom data mapping configuration
adsadsGoogle Ads specific configuration settings
conversionId*stringGoogle Ads Conversion ID (required)
currencystringISO 4217 currency of every conversion
dataanyCustom data mapping (WalkerOS.Mapping.Value | Values)
enhancedConversionsenhancedConversionsEnhanced conversions: maps event fields to Google user_data for improved measurement accuracy
emailanyMapping value for user email
phone_numberanyMapping value for user phone number
addressaddressAddress mapping for enhanced conversions
first_nameanyMapping value for first name
last_nameanyMapping value for last name
streetanyMapping value for street address
cityanyMapping value for city
regionanyMapping value for region/state
postal_codeanyMapping value for postal/zip code
countryanyMapping value for country
gtmgtmGoogle Tag Manager specific configuration settings
containerId*stringGTM Container ID (required)
dataLayerstringCustom dataLayer variable name (default: dataLayer)
domainstringURL the container ID is appended to, up to and including ?id=
dataanyCustom data mapping (WalkerOS.Mapping.Value | Values)
* Required fields

Mapping​

Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

PropertyTypeDescriptionMore
ga4ga4GA4-specific event mapping
adsadsGoogle Ads-specific event mapping
labelstringConversion label for this event, sent as send_to <conversionId>/<label>. A conversion is sent only when the rule also has a name; without a label, the rule's name is the label
gtmgtmGTM-specific event mapping

Examples

Add to cart

A product add becomes the GA4 add_to_cart event with currency, value and the added product as its item.

Event
{
  "name": "product add",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420,
    "quantity": 1,
    "currency": "EUR"
  },
  "context": {
    "shopping": [
      "intent",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "83e860384d50953f",
  "trigger": "click",
  "entity": "product",
  "action": "add",
  "timestamp": 1700000000000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Mapping
{
  "name": "add_to_cart",
  "data": {
    "map": {
      "currency": {
        "key": "data.currency",
        "value": "EUR"
      },
      "value": "data.price",
      "items": {
        "loop": [
          "this",
          {
            "map": {
              "item_id": "data.id",
              "item_name": "data.name",
              "item_variant": "data.color",
              "price": "data.price",
              "quantity": {
                "key": "data.quantity",
                "value": 1
              }
            }
          }
        ]
      }
    }
  }
}
Out
window.gtag("event", "add_to_cart", {
  "currency": "EUR",
  "value": 420,
  "items": [
    {
      "item_id": "ers",
      "item_name": "Everyday Ruck Snack",
      "item_variant": "black",
      "price": 420,
      "quantity": 1
    }
  ],
  "send_to": "G-XXXXXXXXXX"
})

Google Ads init

Configures a Google Ads account via its conversionId. gtag already exists here, so no `js` is sent.

Event
{
  "settings": {
    "ads": {
      "conversionId": "AW-123456789",
      "currency": "EUR"
    }
  }
}
Out
window.gtag("config", "AW-123456789")

Consent Mode v2

A walker consent command with marketing and analytics granted updates gtag Consent Mode v2 parameters. Without config.consent, as here, the first consent command sends the denied default before the update; with config.consent, the denied default goes out before config, as the destination starts.

Event
{
  "marketing": true,
  "analytics": true
}
Out
window.gtag("consent", "default", {
  "ad_storage": "denied",
  "ad_user_data": "denied",
  "ad_personalization": "denied",
  "analytics_storage": "denied"
});

window.gtag("consent", "update", {
  "ad_storage": "granted",
  "ad_user_data": "granted",
  "ad_personalization": "granted",
  "analytics_storage": "granted"
})

GA4 init

Configures a GA4 property with pageview false, so gtag sends no page_view of its own next to the walkerOS page view.

Event
{
  "settings": {
    "ga4": {
      "measurementId": "G-XXXXXXXXXX",
      "pageview": false
    }
  }
}
Out
window.gtag("config", "G-XXXXXXXXXX", {
  "send_page_view": false
})

GTM init

With script loading enabled the destination initializes the dataLayer, pushes the gtm.js start event, and loads the GTM container.

Event
{
  "loadScript": true,
  "settings": {
    "gtm": {
      "containerId": "GTM-XXXXXXX"
    }
  }
}
Out
window.dataLayer.push({
  "gtm.start": 1700000000000,
  "event": "gtm.js"
})

Page view

A page view becomes the GA4 page_view event; gtag adds the page location and title itself, and pageview false keeps it from counting twice.

Event
{
  "name": "page view",
  "data": {
    "domain": "www.example.com",
    "title": "walkerOS documentation",
    "referrer": "https://www.walkeros.io/",
    "search": "?foo=bar",
    "hash": "#hash",
    "id": "/docs/"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "docs"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "f0cc5f6fec3d8eeb",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000000000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Out
window.gtag("event", "page_view", {
  "send_to": "G-XXXXXXXXXX"
})

View item

A product view becomes the GA4 view_item event with currency, value and the product as its one item.

Event
{
  "name": "product view",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420,
    "currency": "EUR"
  },
  "context": {
    "shopping": [
      "detail",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "db22fb16c70f663d",
  "trigger": "load",
  "entity": "product",
  "action": "view",
  "timestamp": 1700000000000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Mapping
{
  "name": "view_item",
  "data": {
    "map": {
      "currency": {
        "key": "data.currency",
        "value": "EUR"
      },
      "value": "data.price",
      "items": {
        "loop": [
          "this",
          {
            "map": {
              "item_id": "data.id",
              "item_name": "data.name",
              "item_variant": "data.color",
              "price": "data.price",
              "quantity": {
                "key": "data.quantity",
                "value": 1
              }
            }
          }
        ]
      }
    }
  }
}
Out
window.gtag("event", "view_item", {
  "currency": "EUR",
  "value": 420,
  "items": [
    {
      "item_id": "ers",
      "item_name": "Everyday Ruck Snack",
      "item_variant": "black",
      "price": 420,
      "quantity": 1
    }
  ],
  "send_to": "G-XXXXXXXXXX"
})

Purchase

An order complete becomes the GA4 purchase event with transaction id, value, tax, shipping, currency and one item per product.

Event
{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "value": 462,
    "tax": 73.76,
    "shipping": 5.22,
    "total": 467.22
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "235d0d7bd7a213f2",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000000000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Mapping
{
  "name": "purchase",
  "data": {
    "map": {
      "transaction_id": "data.id",
      "value": "data.value",
      "tax": "data.tax",
      "shipping": "data.shipping",
      "currency": {
        "key": "data.currency",
        "value": "EUR"
      },
      "items": {
        "loop": [
          "nested",
          {
            "condition": {
              "$code": "e=>\"object\"==typeof e&&null!==e&&\"entity\"in e&&\"product\"===e.entity"
            },
            "map": {
              "item_id": "data.id",
              "item_name": "data.name",
              "item_variant": "data.color",
              "price": "data.price",
              "quantity": {
                "key": "data.quantity",
                "value": 1
              }
            }
          }
        ]
      }
    }
  }
}
Out
window.gtag("event", "purchase", {
  "transaction_id": "0rd3r1d",
  "value": 462,
  "tax": 73.76,
  "shipping": 5.22,
  "currency": "EUR",
  "items": [
    {
      "item_id": "ers",
      "item_name": "Everyday Ruck Snack",
      "item_variant": "black",
      "price": 420,
      "quantity": 1
    },
    {
      "item_id": "cc",
      "item_name": "Cool Cap",
      "price": 42,
      "quantity": 1
    }
  ],
  "send_to": "G-XXXXXXXXXX"
})

Conversion example​

An order complete event whose rule has a name and a label is sent as a Google Ads conversion. The destination builds send_to from the conversion ID and the label (the rule's name when it has no label) and sets currency from the ads settings, EUR when unset; a currency in the mapped data replaces it. A rule with a label and no name sends no conversion, and its push still answers done.

An order complete event is sent as a Google Ads conversion with a configured label and transaction value.

Event
{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "value": 462,
    "tax": 73.76,
    "shipping": 5.22,
    "total": 467.22
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "235d0d7bd7a213f2",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000000000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Mapping
{
  "name": "PURCHASE_CONV",
  "settings": {
    "ads": {
      "label": "PURCHASE_CONV"
    }
  },
  "data": {
    "map": {
      "value": "data.value"
    }
  }
}
Out
window.gtag("event", "conversion", {
  "send_to": "AW-123456789/PURCHASE_CONV",
  "currency": "EUR",
  "value": 462
})

Enhanced conversions​

Enhanced conversions improve measurement accuracy by sending first-party customer data (email, phone, address) alongside a conversion. The destination calls gtag('set', 'user_data', {...}) immediately before the conversion event, and passes allow_enhanced_conversions: true at init. Google hashes the data, the destination sends it in plain form.

Set enhancedConversions on the ads settings. It maps event fields to Google's user_data. Each value is a standard mapping value, so you can pull from event.user, event.data, or anywhere a mapping reaches.

{
  settings: {
    ads: {
      conversionId: 'AW-123456789',
      currency: 'EUR',
      enhancedConversions: {
        email: 'data.customerEmail',
        phone_number: 'data.customerPhone',
        address: {
          city: 'data.city',
          country: 'data.country',
        },
      },
    },
  },
}

The address object accepts first_name, last_name, street, city, region, postal_code, and country. When no user data resolves, the set user_data call is skipped and the conversion is sent normally.

enhancedConversions maps event fields into a gtag set user_data call sent immediately before the conversion event.

Event
{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "value": 462,
    "tax": 73.76,
    "shipping": 5.22,
    "total": 467.22,
    "customerEmail": "buyer@example.com",
    "customerPhone": "+1234567890"
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "235d0d7bd7a213f2",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000000000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Mapping
{
  "name": "PURCHASE_EC2",
  "settings": {
    "ads": {
      "label": "PURCHASE_EC2"
    }
  },
  "data": {
    "map": {
      "value": "data.value"
    }
  }
}
Out
window.gtag("set", "user_data", {
  "email": "buyer@example.com",
  "phone_number": "+1234567890"
});

window.gtag("event", "conversion", {
  "send_to": "AW-123456789/PURCHASE_EC2",
  "currency": "EUR",
  "value": 462
})
💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)