walkeros-using-transformer-ga4

Using @walkeros/transformer-ga4

Overview

@walkeros/transformer-ga4 decodes Google Analytics 4 Measurement Protocol v2 hits (/g/collect, /mp/collect) into walkerOS events. It sits in a server source's before chain, reads the raw HTTP request via ctx.ingest, and returns one walkerOS event per GA4 event in the hit (one hit can carry many events).

Boundaries: server-side decoding in front of a server source, GA4 v2 only, G- tids only by default. Per-field patching via extend/remove is supported.

When to use this skill

• You are wiring transformer-ga4 into a server flow for the first time
• You want to override one of the 33 default GA4 mappings
• You need to drop a GA4 event (auto-fired noise like user_engagement)
• You want to add a custom event key for a gtag('event', '<name>', ...) call
• You need to widen tidPattern to accept Ads (AW-) or DC (DC-) traffic
• Events are not arriving and you suspect the decoder is silently dropping them

Quickstart wiring

Pick the source by runtime before copying the example below. gtag.js can send several events in one POST body (one per line, as text/plain), so the source must keep a non-JSON body as ingest.body. These server sources do:

• @walkeros/server-source-express (shown below), the source runneros and the walkeros/flow image serve. A text/plain body that is valid JSON is parsed; any other text/plain body reaches the decoder as the raw string.

• @walkeros/server-source-fetch: a (Request) => Response handler with no port, for a runtime that calls it (Cloudflare Workers, Deno, Bun, Node.js 18+ with a fetch adapter), e.g. with collector from startFlow:

  import { Source } from '@walkeros/core';
  import type { SourceFetch } from '@walkeros/server-source-fetch';
  
  export default {
    fetch: Source.getSource<SourceFetch.Types>(collector, 'http').push,
  };
  

  runneros and the walkeros/flow image cannot serve it (they only mount a source's Node httpHandler).