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 via source-express, 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

{
  "version": 4,
  "flows": {
    "default": {
      "config": { "platform": "server" },
      "sources": {
        "http": {
          "package": "@walkeros/server-source-express",
          "config": {
            "ingest": {
              "map": {
                "url": { "key": "url" },
                "path": { "key": "path" },
                "method": { "key": "method" },
                "body": { "key": "body" }
              }
            }
          },
          "before": "ga4"
        }
      },
      "transformers": {
        "ga4": { "package": "@walkeros/transformer-ga4" }
      },
      "destinations": {
        "log": { "package": "@walkeros/destination-demo" }
      }
    }
  }
}

Wiring rules:

• transformer-ga4 belongs in source.before, not destination.before. Decoding is a pre-collector concern: GA4 hits are not yet walkerOS events.
• The source must populate ctx.ingest.url (required, string) and ctx.ingest.body (optional, string). Raw text body only — pre-parsed JSON will not decode.
• One HTTP request can fan out to N walkerOS events. This requires the collector fan-out fix (shipped in this release).