Google Analytics 4 (GA4)

Web Source code Package

Google Analytics 4 (GA4) is a web analytics and marketing platform that helps businesses measure traffic across websites and apps. The destination automatically sends events to GA4 via gtag function. All you need to do is install the destination, and optionally map events to GA4's format. walkerOS takes care of loading the script and the function calls.

Installation

npm install @walkeros/web-destination-gtag

Setup

import { startFlow } from '@walkeros/collector';
import { destinationGtag } from '@walkeros/web-destination-gtag';

const { elb } = await startFlow();

elb('walker destination', destinationGtag, {
  settings: {
    ga4: {
      measurementId: 'G-XXXXXXXXXX',
    },
  },
});

Configuration reference

Property	Type	Description	More
measurementId*	string	GA4 Measurement ID from Google Analytics
debug	boolean	Enable debug mode for GA4
include	Include[]	Array of properties to include in events
pageview	boolean	Enable automatic pageview tracking
server_container_url	string	Server-side GTM container URL
snakeCase	boolean	Convert parameter names to snake_case
transport_url	string	Custom transport URL for GA4

* Required fields

Example

Settings

{
  measurementId: 'G-XXXXXXXXXX', // Required
  debug: false,
  include: ['globals'],
  pageview: false,
  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, 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.

Event Mapping

For custom event mapping (mapping.entity.action.settings.ga4):

Property	Type	Description	More
include	Include[]	Array of properties to include in this specific event

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

Mapping examples

tip

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

Find all of GA4's recommended events in this overview.

add_to_cart

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

Event

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

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

Mapping

{
  name: "add_to_cart",
  settings: {
    ga4: {
      include: [
        "data"
      ]
    }
  },
  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", settings: { ga4: { include: [ "data" ] } }, 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 walkerOS event to get a purchase gtag.js event.

Event

{
  name: "order complete",
  data: {
    id: "0rd3r1d",
    currency: "EUR",
    shipping: 5.22,
    taxes: 73.76,
    total: 555
  },
  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: "1760487217000-gr0up-1",
  trigger: "load",
  entity: "order",
  action: "complete",
  timestamp: 1760487217000,
  timing: 3.14,
  group: "gr0up",
  count: 1,
  version: {
    source: "0.2.0",
    tagging: 1
  },
  source: {
    type: "web",
    id: "https://localhost:80",
    previous_id: "http://remotehost:9001"
  }
}

{ name: "order complete", data: { id: "0rd3r1d", currency: "EUR", shipping: 5.22, taxes: 73.76, total: 555 }, 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: "1760487217000-gr0up-1", trigger: "load", entity: "order", action: "complete", timestamp: 1760487217000, timing: 3.14, group: "gr0up", count: 1, version: { source: "0.2.0", tagging: 1 }, source: { type: "web", id: "https://localhost:80", previous_id: "http://remotehost:9001" } }

Mapping

{
  name: "purchase",
  settings: {
    ga4: {
      include: [
        "data",
        "context"
      ]
    }
  },
  data: {
    map: {
      transaction_id: "data.id",
      value: "data.total",
      tax: "data.taxes",
      shipping: "data.shipping",
      currency: {
        key: "data.currency",
        value: "EUR"
      },
      items: {
        loop: [
          "nested",
          {
            map: {
              item_id: "data.id",
              item_name: "data.name",
              quantity: {
                key: "data.quantity",
                value: 1
              }
            }
          }
        ]
      }
    }
  }
}

{ name: "purchase", settings: { ga4: { include: [ "data", "context" ] } }, data: { map: { transaction_id: "data.id", value: "data.total", tax: "data.taxes", shipping: "data.shipping", currency: { key: "data.currency", value: "EUR" }, items: { loop: [ "nested", { map: { item_id: "data.id", item_name: "data.name", quantity: { key: "data.quantity", value: 1 } } } ] } } } }

Result

No event yet.

No event yet.