Google Tag Manager (GTM)
Google Tag Manager (GTM) is a tool to manage and add third-party integrations to your website, configured within the unified gtag destination.
To get events into GTM without a flow, use walker.js: one script tag that pushes every tagged event to the dataLayer, with a complete GTM setup.
Installation
npm install @walkeros/web-destination-gtagimport { startFlow } from '@walkeros/collector';
import { destinationGtag } from '@walkeros/web-destination-gtag';
await startFlow({
destinations: {
gtag: {
code: destinationGtag,
config: {
loadScript: true, // walkerOS installs the container; omit it when GTM is already on the page
settings: {
gtm: {
containerId: 'GTM-XXXXXXX',
dataLayer: 'dataLayer',
},
},
},
},
},
});Set loadScript: true when walkerOS should install the container for you. It
loads gtm.js and pushes the gtm.js start event into the dataLayer, which is
what Google's own snippet does.
Leave loadScript unset when the container is already on the page, for example
when you are feeding an existing GTM setup while you migrate. walkerOS then
neither loads the container nor pushes the gtm.js bootstrap event: it adopts
the configured dataLayer (creating it if it does not exist yet) and pushes your
events into it, so your existing triggers keep firing exactly as often
as before.
Each push carries event with the event name. With a data mapping (data or
include on the rule or the destination config, or settings.gtm.data), it
carries the mapped values. Without one, it carries the whole walkerOS event as
it is.
loadScript is set once per destination and applies to every flavor configured
on it. On a destination that also configures ga4 or ads, the same flag
governs whether those scripts are loaded too.
walkerOS sends Consent Mode through a gtag function. When the page has none,
the destination adds one only if it declares a consent signal or configures
ga4 or ads. So on a destination that configures only gtm, on a page
without a gtag function, Consent Mode reaches the container only when the
destination declares a consent signal. With loadScript: true:
- With
consent: { marketing: true }inconfig, walkerOS pushes the deniedconsent defaultbeforegtm.js, loads the container once that consent is granted and pushes aconsent updateon every change. - With
como_advancedinstead, the denied default goes out beforegtm.jsas the flow starts, the container and the events go out without waiting, and aconsent updatefollows every change. - With neither, consent commands push nothing into the dataLayer and the container loads as the flow starts.
With neither signal, walkerOS still sends Consent Mode when a gtag function is
in place: because this destination configures ga4 or ads, because another
Google tag destination added one, or because the page defines one itself, for
example for its own Consent Mode default. The first consent command pushes the denied
consent default, followed by the consent update, through gtag, and every
later change pushes a consent update. With loadScript: true, these come
after gtm.js.
A container that is already on the page loads before walkerOS starts, so its Consent Mode default has to come from the page, set by your CMP or inside the container. walkerOS's own default, when it sends one, arrives after the container has started.
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"
})dataLayer example
A mapped event is pushed to the dataLayer with event set to the mapped name
and the mapped values beside it. When settings configures GA4 and GTM, both
receive every event the destination gets; a rule cannot leave one of them out.
A page view event is pushed to window.dataLayer for GTM with the mapped event name and parameters.
{
"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"
}
}{
"name": "page_view",
"settings": {
"gtm": {}
},
"data": {
"map": {
"page_title": "data.title",
"page_location": "data.domain"
}
}
}window.dataLayer.push({
"event": "page_view",
"page_title": "walkerOS documentation",
"page_location": "www.example.com"
})