GA4 ecommerce
By the end of this tutorial you will send a page view and a product add event
to Google Analytics 4 and watch both arrive in DebugView. You start with a single
console destination to see output immediately, then swap in the GA4 destination
and add the ecommerce mapping that turns product add into add_to_cart.
Step 1: Install
Install the collector and the gtag destination:
npm install @walkeros/collector @walkeros/web-destination-gtagStep 2: Send a page view
Start with a single console destination so you can see your first event in the terminal before any vendor is involved. This snippet stays DOM-free, so it runs in Node:
import { startFlow } from '@walkeros/collector';
const { elb } = await startFlow({
destinations: {
console: {
code: {
type: 'console',
config: {},
push: (event) => console.log('Event:', event.name),
},
},
},
});
await elb({ name: 'page view', data: { title: 'Home' } });
// -> logs: Event: page viewOnce that prints, point the same page view at GA4 by swapping the console
destination for the gtag destination. The gtag destination snake-cases the
entity action name automatically, so page view arrives in GA4 as page_view
with no mapping:
import { startFlow } from '@walkeros/collector';
import { destinationGtag } from '@walkeros/web-destination-gtag';
const { elb } = await startFlow({
destinations: {
ga4: {
code: destinationGtag,
config: {
loadScript: true,
settings: {
ga4: { measurementId: 'G-XXXXXXXXXX', pageview: false },
},
},
},
},
});
await elb({ name: 'page view', data: { title: 'Home' } });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. pageview: false stops gtag from sending a page_view of
its own when it starts, so this page view is not counted twice. 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.
This snippet sets no consent, so gtag.js loads and sends its config as the
flow starts, and every event goes out before any consent decision. Before you go
live, add consent: { analytics: true } to config, next to settings: gtag.js
then loads and events go out only once analytics is granted. With several
keys in consent, one granted key is enough to open the gate (see
Google Consent Mode).
Step 3: Add the ecommerce mapping
A product add event needs an explicit mapping, otherwise it would arrive as
product_add carrying only send_to. Add this mapping to the gtag
destination's config, next to settings, to turn product add 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',
});Step 4: Verify in GA4
In GA4, open Admin > Data collection and modification > Data streams, click your
web stream and copy its Measurement ID into the measurementId above. 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.
Next steps
- GA4 destination reference: full configuration for the gtag destination, including consent and additional GA4 settings.