Google Gtag
The Google Gtag destination provides a unified interface for sending events to
Google Analytics 4 (GA4), Google Ads, and Google Tag Manager (GTM) through a
single destination configuration. It initializes the gtag function with your
config, loads gtag.js when loadScript is true, handles Consent Mode v2
commands automatically, and pushes mapped events to Google services.
Consent Mode is on by default via como (set como: false to disable it). By default analytics consent sets analytics_storage and marketing consent sets ad_storage, ad_user_data and ad_personalization (see Google Consent Mode). When the destination declares a consent signal (config.consent or como_advanced), the denied consent default is emitted before config, as Consent Mode v2 requires. Set como_advanced: true (or a number of milliseconds) to opt into advanced mode, emitting the denied default at page load with wait_for_update, for non-EU setups. The consent update for the recorded consent state is sent before the first event, also when the destination is gated with require or added while the flow is running.
Gtag is a destination in the walkerOS flow:
Installation
npm install @walkeros/web-destination-gtag- Integrated
- Bundled
import { startFlow } from '@walkeros/collector';
import { destinationGtag } from '@walkeros/web-destination-gtag';
const { collector, elb } = await startFlow({
destinations: {
gtag: {
code: destinationGtag,
config: {
loadScript: true,
settings: {
ga4: {
measurementId: 'G-XXXXXXXXXX',
},
},
},
},
},
});Add to your flow.json destinations:
"destinations": {
"gtag": {
"package": "@walkeros/web-destination-gtag",
"config": {
"loadScript": true,
"settings": {
"ga4": {
"measurementId": "G-XXXXXXXXXX"
}
}
}
}
}loadScript: true makes walkerOS add gtag.js to the page. Without it walkerOS
injects no gtag.js and only queues its calls in dataLayer, so events reach
Google only if your page loads gtag.js itself.
The snippets above set no consent. As the flow starts, gtag.js loads and sends
its config, and with it Google's own page_view, before any Consent Mode
default; the denied default follows only with the first consent command. Add
consent: { analytics: true } to config, next to settings, before you go
live. The destination then waits for that consent: once it is granted, the
denied default goes out before config, gtag.js loads and the waiting events
follow (see Google Consent Mode).
For Google Ads, use a destination of its own with
consent: { marketing: true }. One granted key is enough for the gate (see
gate a destination), so
a destination that runs GA4 and Ads with both keys sends conversions, and with
enhanced conversions the customer's data, to gtag.js once analytics alone is
granted.
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
| Property | Type | Description | More |
|---|---|---|---|
como | boolean | object | Consent mode configuration: false (disabled), true (use defaults), or custom mapping | |
como_advanced | boolean | number | Advanced consent mode (non-EU): emit denied default at page load with wait_for_update (true=500ms, or a number of ms) | |
ga4 | ga4 | GA4-specific configuration settings | |
measurementId | string | GA4 Measurement ID from Google Analytics | |
debug | boolean | Enable debug mode for GA4 | |
init | boolean | Set 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) | |
pageview | boolean | Set 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) | |
scriptSrc | string | Full 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_url | string | Server-side GTM container URL | |
snakeCase | boolean | Lowercase the event name and replace its spaces with underscores (like true). Applies to the event name only, never to parameter names | |
transport_url | string | Custom transport URL for GA4 | |
data | any | Custom data mapping configuration | |
ads | ads | Google Ads specific configuration settings | |
conversionId | string | Google Ads Conversion ID (required) | |
currency | string | ISO 4217 currency of every conversion | |
data | any | Custom data mapping (WalkerOS.Mapping.Value | Values) | |
enhancedConversions | enhancedConversions | Enhanced conversions: maps event fields to Google user_data for improved measurement accuracy | |
email | any | Mapping value for user email | |
phone_number | any | Mapping value for user phone number | |
address | address | Address mapping for enhanced conversions | |
first_name | any | Mapping value for first name | |
last_name | any | Mapping value for last name | |
street | any | Mapping value for street address | |
city | any | Mapping value for city | |
region | any | Mapping value for region/state | |
postal_code | any | Mapping value for postal/zip code | |
country | any | Mapping value for country | |
gtm | gtm | Google Tag Manager specific configuration settings | |
containerId | string | GTM Container ID (required) | |
dataLayer | string | Custom dataLayer variable name (default: dataLayer) | |
domain | string | URL the container ID is appended to, up to and including ?id= | |
data | any | Custom data mapping (WalkerOS.Mapping.Value | Values) |
Mapping
Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
| Property | Type | Description | More |
|---|---|---|---|
ga4 | ga4 | GA4-specific event mapping | |
ads | ads | Google Ads-specific event mapping | |
label | string | Conversion 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 | |
gtm | gtm | GTM-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.
{
"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"
}
}{
"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
}
}
}
]
}
}
}
}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.
{
"settings": {
"ads": {
"conversionId": "AW-123456789",
"currency": "EUR"
}
}
}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.
{
"marketing": true,
"analytics": true
}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.
{
"settings": {
"ga4": {
"measurementId": "G-XXXXXXXXXX",
"pageview": false
}
}
}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.
{
"loadScript": true,
"settings": {
"gtm": {
"containerId": "GTM-XXXXXXX"
}
}
}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.
{
"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"
}
}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.
{
"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"
}
}{
"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
}
}
}
]
}
}
}
}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.
{
"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"
}
}{
"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
}
}
}
]
}
}
}
}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"
})gtag.js and a GTM container load through walkerOS, so a blocked script fails later events visibly. An empty GA4 parameter name, or two names that normalize to one, drops that parameter and still sends the event. The first such drop writes an ERROR line naming the mapping key; further drops on this destination within a minute write none. A rule with silent: true sends nothing. Settings with a key gtag does not read fail walkeros validate.
Next steps
- Mapping: transform events for Google's expected format
- GA4 configuration: detailed GA4 setup
- Google Ads: conversion tracking
- Google Tag Manager: push events into a GTM container
- Consent management: control when events are sent