Google Analytics 4 (GA4)

Source code Package Browser ES5

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

Installation

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

Load 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);
})();

Configuration

Configure the GA4 destination with your Measurement ID.

Example

Custom Config

{
    measurementId: 'G-XXXXXXXXXX', // Required
    debug: false,
    include: ['globals'],
    pageview: false,
    data: {
      map: {
        currency: {
          value: 'EUR',
          key: 'data.currency',
        },
      },
    },
    server_container_url: 'https://server.example.com',
    snakeCase: true,
    transport_url: 'https://www.google-analytics.com/g/collect',
  }

{ measurementId: 'G-XXXXXXXXXX', // Required debug: false, include: ['globals'], pageview: false, data: { map: { currency: { value: 'EUR', key: 'data.currency', }, }, }, server_container_url: 'https://server.example.com', snakeCase: true, transport_url: 'https://www.google-analytics.com/g/collect', }

Result

No event yet.

No event yet.

Custom

Property	Type	Description
measurementId*	string	GA4 Measurement ID
debug	boolean	Enables debug mode for additional logging
include	array	Defines groups of properties to be included in all events, data by default. Use an empty array for none.
pageview	boolean	Enables or disables automatic pageview tracking
server_container_url	string	URL for a server-side tag manager
snakeCase	boolean	Converts parameter names to snake_case for GA4 compatibility
transport_url	string	URL used for sending events to GA4

Properties with a * are required.

CustomEvent

Property	Type	Description
include	array	Specifies which groups of properties to include, e.g., ['all'], ['data'], ['context'], etc.

note

include is 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. A key to access the event value.

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 data.

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.

Mapping

You are able to map your walkerOS events to match the respective requirements of each vendor. The mapping examples are using a live configuration.

tip

The code examples are interactive. You can edit the code to generate your individual event mapping.

add_to_cart

Map your custom walkerOS event to get an add_to_cart gtag.js event.

Event

{
  event: "product add",
  data: {
    id: "ers",
    name: "Everyday Ruck Snack",
    color: "black",
    size: "l",
    price: 420
  },
  context: {
    shopping: [
      "intent",
      0
    ]
  },
  globals: {
    pagegroup: "shop"
  },
  custom: {},
  user: {
    id: "us3r",
    device: "c00k13",
    session: "s3ss10n"
  },
  nested: [],
  consent: {
    functional: true
  },
  id: "1734480817000-gr0up-1",
  trigger: "click",
  entity: "product",
  action: "add",
  timestamp: 1734480817000,
  timing: 3.14,
  group: "gr0up",
  count: 1,
  version: {
    source: "0.0.7",
    tagging: 1
  },
  source: {
    type: "web",
    id: "https://localhost:80",
    previous_id: "http://remotehost:9001"
  }
}

{ event: "product add", data: { id: "ers", name: "Everyday Ruck Snack", color: "black", size: "l", price: 420 }, context: { shopping: [ "intent", 0 ] }, globals: { pagegroup: "shop" }, custom: {}, user: { id: "us3r", device: "c00k13", session: "s3ss10n" }, nested: [], consent: { functional: true }, id: "1734480817000-gr0up-1", trigger: "click", entity: "product", action: "add", timestamp: 1734480817000, timing: 3.14, group: "gr0up", count: 1, version: { source: "0.0.7", tagging: 1 }, source: { type: "web", id: "https://localhost:80", previous_id: "http://remotehost:9001" } }

Custom Config

{
  name: "add_to_cart",
  data: {
    map: {
      currency: {
        value: "EUR",
        key: "data.currency"
      },
      value: "data.price",
      items: {
        loop: [
          "this",
          {
            map: {
              item_id: "data.id",
              item_variant: "data.color",
              quantity: {
                value: 1,
                key: "data.quantity"
              }
            }
          }
        ]
      }
    }
  }
}

{ name: "add_to_cart", data: { map: { currency: { value: "EUR", key: "data.currency" }, value: "data.price", items: { loop: [ "this", { map: { item_id: "data.id", item_variant: "data.color", quantity: { value: 1, key: "data.quantity" } } } ] } } } }

Result

No event yet.

No event yet.

purchase

Map your custom walkerOS event to get a purchase gtag.js event.

Event

{
  event: "order complete",
  data: {
    id: "0rd3r1d",
    currency: "EUR",
    shipping: 5.22,
    taxes: 73.76,
    total: 555
  },
  context: {
    shopping: [
      "complete",
      0
    ]
  },
  globals: {
    pagegroup: "shop"
  },
  custom: {},
  user: {
    id: "us3r",
    device: "c00k13",
    session: "s3ss10n"
  },
  nested: [
    {
      type: "product",
      data: {
        id: "ers",
        name: "Everyday Ruck Snack",
        color: "black",
        size: "l",
        price: 420
      },
      context: {
        shopping: [
          "complete",
          0
        ]
      },
      nested: []
    },
    {
      type: "product",
      data: {
        id: "cc",
        name: "Cool Cap",
        size: "one size",
        price: 42
      },
      context: {
        shopping: [
          "complete",
          0
        ]
      },
      nested: []
    },
    {
      type: "gift",
      data: {
        name: "Surprise"
      },
      context: {
        shopping: [
          "complete",
          0
        ]
      },
      nested: []
    }
  ],
  consent: {
    functional: true
  },
  id: "1734480817000-gr0up-1",
  trigger: "load",
  entity: "order",
  action: "complete",
  timestamp: 1734480817000,
  timing: 3.14,
  group: "gr0up",
  count: 1,
  version: {
    source: "0.0.7",
    tagging: 1
  },
  source: {
    type: "web",
    id: "https://localhost:80",
    previous_id: "http://remotehost:9001"
  }
}

{ event: "order complete", data: { id: "0rd3r1d", currency: "EUR", shipping: 5.22, taxes: 73.76, total: 555 }, context: { shopping: [ "complete", 0 ] }, globals: { pagegroup: "shop" }, custom: {}, user: { id: "us3r", device: "c00k13", session: "s3ss10n" }, nested: [ { type: "product", data: { id: "ers", name: "Everyday Ruck Snack", color: "black", size: "l", price: 420 }, context: { shopping: [ "complete", 0 ] }, nested: [] }, { type: "product", data: { id: "cc", name: "Cool Cap", size: "one size", price: 42 }, context: { shopping: [ "complete", 0 ] }, nested: [] }, { type: "gift", data: { name: "Surprise" }, context: { shopping: [ "complete", 0 ] }, nested: [] } ], consent: { functional: true }, id: "1734480817000-gr0up-1", trigger: "load", entity: "order", action: "complete", timestamp: 1734480817000, timing: 3.14, group: "gr0up", count: 1, version: { source: "0.0.7", tagging: 1 }, source: { type: "web", id: "https://localhost:80", previous_id: "http://remotehost:9001" } }

Custom Config

{
    name: 'purchase',
    data: {
      map: {
        transaction_id: 'data.id',
        value: 'data.total',
        tax: 'data.taxes',
        shipping: 'data.shipping',
        currency: { key: 'data.currency', value: 'EUR' },
        items: {
          loop: [
            'nested',
            {
              condition: (entity) => entity.type === 'product',
              map: {
                item_id: 'data.id',
                item_name: 'data.name',
                quantity: { key: 'data.quantity', value: 1 },
              },
            },
          ],
        },
      },
    },
  }

{ name: 'purchase', data: { map: { transaction_id: 'data.id', value: 'data.total', tax: 'data.taxes', shipping: 'data.shipping', currency: { key: 'data.currency', value: 'EUR' }, items: { loop: [ 'nested', { condition: (entity) => entity.type === 'product', map: { item_id: 'data.id', item_name: 'data.name', quantity: { key: 'data.quantity', value: 1 }, }, }, ], }, }, }, }

Result

No event yet.

No event yet.

info

If you need professional support with your walkerOS implementation, check out our services.