Google Analytics 4 (GA4)
Google Analytics 4 (GA4)
is configured within the unified gtag destination. With loadScript: true
walkerOS loads gtag.js and forwards mapped events to GA4.
Installation
npm install @walkeros/web-destination-gtagimport { startFlow } from '@walkeros/collector';
import { destinationGtag } from '@walkeros/web-destination-gtag';
await startFlow({
destinations: {
ga4: {
code: destinationGtag,
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
GA4 only if your page loads gtag.js itself.
This snippet sets no consent, so config, and with it Google's own
page_view, goes out before any Consent Mode default. Add
consent: { analytics: true } to config, next to settings, before you go
live (see Google Consent Mode).
Let a tag manager own the configuration
If a container (for example GTM) already configures your measurement ID, set
init: false. walkerOS then skips the gtag bootstrap entirely, no js, no
config, no script load, and only sends events, routed by send_to, plus its
Consent Mode commands while como is on.
settings: {
ga4: {
measurementId: 'G-XXXXXXXX',
init: false,
},
}The container's own config then stays the only one on the page. The settings
walkerOS would put into config or use to load the script
(server_container_url, transport_url, pageview, scriptSrc) have no
effect with init: false: set them on the container's tag. The Consent Mode
default has to come from the page as well, set by your CMP or inside the
container. With config.consent, walkerOS sends its denied default and its
updates only after the container's config.
Serve gtag.js first-party
By default gtag.js loads from googletagmanager.com. To serve it from your own
tagging server instead, set scriptSrc to the
tag serving path
configured in your server container. walkerOS loads that URL as it is, without
adding the measurement ID.
settings: {
ga4: {
measurementId: 'G-XXXXXXXXXX',
scriptSrc: 'https://example.com/metrics/tag_serving_path/',
server_container_url: 'https://example.com/metrics',
},
}server_container_url goes into gtag's config and does not change where the
script loads from: without scriptSrc, gtag.js still loads from
googletagmanager.com. If scriptSrc fails to load, walkerOS falls back to
googletagmanager.com, so measurement keeps working when the container is
misconfigured.
A page view needs no mapping
The gtag destination snake-cases an entity action event name into a GA4 event
name automatically, so page view arrives in GA4 as page_view with no mapping
at all. An unmapped product add would arrive as product_add carrying only
send_to, which is why the ecommerce event below needs an explicit mapping.
gtag also sends a page_view of its own when config runs. With the default
settings a pushed page view therefore reaches GA4 in addition to that
automatic one, and the page is counted twice. Set pageview: false on the
ga4 settings to keep only the walkerOS event; gtag still adds the page
location and title to it. On a single-page app, also turn off Page changes
based on browser history events in the web stream's enhanced measurement
settings: gtag.js still sends those page views with pageview: false.
settings: {
ga4: {
measurementId: 'G-XXXXXXXXXX',
pageview: false,
},
}Add the ecommerce mapping
Nest the mapping under the gtag destination to turn a product add event into
the GA4 add_to_cart event. The product price becomes the GA4 value, the
currency falls back to EUR, and the product is shaped into a GA4 items array
via a this loop.
mapping: {
product: {
add: {
name: 'add_to_cart',
data: {
map: {
value: 'data.price',
currency: { value: 'EUR', key: 'data.currency' },
items: {
loop: [
'this',
{
map: {
item_id: 'data.id',
item_name: 'data.name',
quantity: { value: 1, key: 'data.quantity' },
},
},
],
},
},
},
},
},
}Pushing a product add event:
elb({
name: 'product add',
data: { id: 'ers', name: 'Everyday Ruck Snack', price: 420 },
});produces the GA4 add_to_cart event:
gtag('event', 'add_to_cart', {
value: 420,
currency: 'EUR',
items: [{ item_id: 'ers', item_name: 'Everyday Ruck Snack', quantity: 1 }],
send_to: 'G-XXXXXXXXXX',
});Parameter names
Before sending, the destination replaces every run of characters other than
letters, digits and underscores in a parameter name with one underscore; a
hyphen is the most common case. Tagging creative-type under include: ['data'] produces the
parameter data_creative-type, which is sent as data_creative_type. Case is
left alone.
Event names are never rewritten this way. snakeCase lowercases the event name
and replaces its spaces with underscores; set it to false and the name is sent
exactly as configured.
Two parameters are dropped rather than renamed:
| Parameter | Produced by include from |
|---|---|
source_platform | event.source.platform |
user_id | event.user.id |
Required ecommerce parameters such as currency, value and transaction_id
are unaffected. To keep the platform value, map it to a name of your own:
data: { map: { platform: 'source.platform' } }Verify in GA4
In GA4, open Admin > Data collection and modification > Data streams, click your
web stream and copy its Measurement ID. Watch Reports > Realtime to confirm the
page_view event.
DebugView lists only events sent in debug mode, so while you test, add
debug: true to settings.ga4: the destination then adds debug_mode: true to
every event. Open Admin > Data display > DebugView to inspect the add_to_cart
event and its parameters as they arrive, and remove debug before going live.
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"
})