Skip to main content

Google Analytics 4 (GA4)

packages/destinations/web/google-ga4 @elbwalker/destination-web-google-ga4

Google Analytics 4 is the current version of Google's marketing measurement software. It's the most common analytics tool for tracking conversions and user behavior on websites.

Configuration

Set up the GA4 destination configuration to start tracking events. This destination works both in a Node environment and directly in the browser.

const config = {
custom: {
measurementId: 'G-XXXXXXXXXX', // Required
debug: false,
include: ['globals'],
items: {},
pageview: false,
params: {
currency: {
default: 'EUR',
key: 'data.currency',
},
user_id: 'user.id',
},
snakeCase: true,
transport_url: 'https://www.google-analytics.com/j/collect',
},
mapping: {
'*': { '*': {} }, // Process all events
// entity: { action: { name: 'custom_name' } },
page: { view: { ignore: true } }, // Ignore page view events, same as pageview: false
product: {
add: {
name: 'add_to_cart', // Rename the product add event to add_to_cart
custom: {
// Set parameters for items array
include: ['all'], // Add all properties to parameters
items: {
params: {
item_id: 'data.id',
item_category: 'context.category.0', // Value is an array
quantity: { default: 1, key: 'data.quantity' },
},
},
// Set event parameters
params: { value: 'data.price' },
},
},
// Add view and other product-related actions
},
order: {
complete: {
name: 'purchase',
custom: {
items: {
params: {
// Nested entities are looped and can be used with a wildcard
// This will add multiple items to the event
item_id: 'nested.*.data.id',
},
},
params: { transaction_id: 'data.id', value: 'data.revenue' },
},
},
},
},
};

CustomConfig

PropertyTypeDescription
measurementId*stringThe GA4 measurement ID
debugbooleanEnables debug mode for additional logging
includearrayDefines groups of properties to be included in all events
itemsobjectSets parameters for item-level data in events
pageviewbooleanEnables or disables automatic pageview tracking
paramsobjectCustom parameters for event-level data
snakeCasebooleanConverts parameter names to snake_case for GA4 compatibility
transport_urlstringThe URL used for sending events to GA4

Properties with a * are required.

CustomEventConfig

PropertyTypeDescription
paramsobjectCustom parameters for the event. Includes data properties like value, item_id, etc.
includearraySpecifies which groups of properties to include, e.g., ['all'], ['data'], ['context'], etc.
itemsobjectDefines parameters for item-level data in events, like 'quantity', 'item_id'
items.paramsobjectParameters for items array, specifying data property keys and defaults for quantities, etc.

params, items, and include are available at both, the config and event level. Settings on the event level will override the general ones.

Use the string-dot notation (data.id, user.id, group, context.position.0) to access all values of an event. They can either be a string or an object. A string is used as a key to access an event value directly. An object can be used to set a default value and a key to access the event value.

{
params: {
name: 'data.name', // Key to value
quantity: { default: 1, key: 'data.quantity' }, // default value and key to value
},
};

Nested entities will be looped if available. Use items and the wildcard (*) to access and add them dynamically (for order complete events with multiple nested product entities for example).

Use the include option to bulk-add event properties without explicitly mapping custom event parameters. This adds all available properties of the specified group. Available groups are event (for basic event properties like trigger, timing, etc.), data, context, globals, nested, source, user, version, or just all. All data properties are added automatically by default. If you don't want this add include: [].

Note: consent and nested are not available via include, but you can add them explicitly using params or items.

The properties get prefixed with the group's name and underscore (like globals_lang for { globals: { lang: 'de' } }). Custom parameters will override include values with the same key.

How to use

Choose one of the installation options below to start using the GA4 destination:

const config = {
custom: {
measurementId: 'G-XXXXXXXXXX',
},
};

Install the destination via npm

npm i --save @elbwalker/destination-web-google-ga4
import { elb } from '@elbwalker/walker.js';
import destinationGoogleGA4 from '@elbwalker/destination-web-google-ga4';

elb('walker destination', destinationGoogleGA4, config);