Google Analytics 4 (GA4)

Source code Package Browser ES5

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

Property	Type	Description
measurementId*	string	The GA4 measurement ID
debug	boolean	Enables debug mode for additional logging
include	array	Defines groups of properties to be included in all events
items	object	Sets parameters for item-level data in events
pageview	boolean	Enables or disables automatic pageview tracking
params	object	Custom parameters for event-level data
snakeCase	boolean	Converts parameter names to snake_case for GA4 compatibility
transport_url	string	The URL used for sending events to GA4

Properties with a * are required.

CustomEventConfig

Property	Type	Description
params	object	Custom parameters for the event. Includes data properties like value, item_id, etc.
include	array	Specifies which groups of properties to include, e.g., ['all'], ['data'], ['context'], etc.
items	object	Defines parameters for item-level data in events, like 'quantity', 'item_id'
items.params	object	Parameters 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',
  },
};

TypeScript

Install the destination via npm

npm i @elbwalker/destination-web-google-ga4

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

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

Script

Loading the destination via dynamic import

<script>
  // Upload the dist/index.mjs on your own server
  const destination = (
    await import(
      'https://cdn.jsdelivr.net/npm/@elbwalker/destination-web-google-ga4/dist/index.mjs'
    )
  ).default;

  elb('walker destination', destination, config);
</script>

Code

Copy the code from the index.browser.js file

(function () {
  'use strict';
  var Destination = (() => {})(); // This is the copied code

  elb('walker destination', Destination.default, config);
})();