From acf74bafb405c895a9d833a445269f60b3481659 Mon Sep 17 00:00:00 2001 From: laurentdav <45101601+laurentdav@users.noreply.github.com> Date: Tue, 17 Nov 2026 23:09:54 +0100 Subject: [PATCH 1/2] feat(ga4): new server destination for the GA4 Measurement Protocol Closes #764 Co-Authored-By: Claude Opus 5.5 --- .changeset/ga4-server-destination.md | 9 + package-lock.json | 22 +++ packages/server/destinations/ga4/README.md | 65 +++++++ .../server/destinations/ga4/jest.config.mjs | 5 + packages/server/destinations/ga4/package.json | 76 +++++++++ .../ga4/src/__tests__/conformance.test.ts | 21 +++ .../ga4/src/__tests__/index.test.ts | 161 ++++++++++++++++++ .../ga4/src/__tests__/stepExamples.test.ts | 68 ++++++++ .../server/destinations/ga4/src/config.ts | 28 +++ packages/server/destinations/ga4/src/dev.ts | 2 + .../destinations/ga4/src/examples/env.ts | 36 ++++ .../destinations/ga4/src/examples/index.ts | 3 + .../destinations/ga4/src/examples/minimal.ts | 10 ++ .../destinations/ga4/src/examples/step.ts | 160 +++++++++++++++++ packages/server/destinations/ga4/src/index.ts | 22 +++ packages/server/destinations/ga4/src/push.ts | 106 ++++++++++++ .../destinations/ga4/src/schemas/index.ts | 12 ++ .../destinations/ga4/src/schemas/mapping.ts | 9 + .../ga4/src/schemas/primitives.ts | 4 + .../destinations/ga4/src/schemas/settings.ts | 25 +++ .../destinations/ga4/src/types/index.ts | 66 +++++++ .../server/destinations/ga4/tsconfig.json | 8 + .../server/destinations/ga4/tsup.config.ts | 14 ++ website/docs/destinations/index.mdx | 2 +- website/docs/destinations/server/ga4.mdx | 101 +++++++++++ website/package.json | 1 + website/sidebars.ts | 5 + 27 files changed, 1040 insertions(+), 1 deletion(-) create mode 100644 .changeset/ga4-server-destination.md create mode 100644 packages/server/destinations/ga4/README.md create mode 100644 packages/server/destinations/ga4/jest.config.mjs create mode 100644 packages/server/destinations/ga4/package.json create mode 100644 packages/server/destinations/ga4/src/__tests__/conformance.test.ts create mode 100644 packages/server/destinations/ga4/src/__tests__/index.test.ts create mode 100644 packages/server/destinations/ga4/src/__tests__/stepExamples.test.ts create mode 100644 packages/server/destinations/ga4/src/config.ts create mode 100644 packages/server/destinations/ga4/src/dev.ts create mode 100644 packages/server/destinations/ga4/src/examples/env.ts create mode 100644 packages/server/destinations/ga4/src/examples/index.ts create mode 100644 packages/server/destinations/ga4/src/examples/minimal.ts create mode 100644 packages/server/destinations/ga4/src/examples/step.ts create mode 100644 packages/server/destinations/ga4/src/index.ts create mode 100644 packages/server/destinations/ga4/src/push.ts create mode 100644 packages/server/destinations/ga4/src/schemas/index.ts create mode 100644 packages/server/destinations/ga4/src/schemas/mapping.ts create mode 100644 packages/server/destinations/ga4/src/schemas/primitives.ts create mode 100644 packages/server/destinations/ga4/src/schemas/settings.ts create mode 100644 packages/server/destinations/ga4/src/types/index.ts create mode 100644 packages/server/destinations/ga4/tsconfig.json create mode 100644 packages/server/destinations/ga4/tsup.config.ts create mode 100644 website/docs/destinations/server/ga4.mdx diff --git a/.changeset/ga4-server-destination.md b/.changeset/ga4-server-destination.md new file mode 100644 index 000000000..4685ad956 --- /dev/null +++ b/.changeset/ga4-server-destination.md @@ -0,0 +1,9 @@ +--- +'@walkeros/server-destination-ga4': minor +--- + +New GA4 Measurement Protocol server destination. Server events join the +visitor's GA4 session when the `_ga` client id and session id are mapped; an +event without a client id gets a stable one derived from its event id. Ad +signals follow the event's marketing consent, `timestamp_micros` is sent for +events under 72 hours, and invalid event names fail before any request. diff --git a/package-lock.json b/package-lock.json index 97459145a..29c13eb30 100644 --- a/package-lock.json +++ b/package-lock.json @@ -19837,6 +19837,10 @@ "resolved": "packages/server/destinations/file", "link": true }, + "node_modules/@walkeros/server-destination-ga4": { + "resolved": "packages/server/destinations/ga4", + "link": true + }, "node_modules/@walkeros/server-destination-gcp": { "resolved": "packages/server/destinations/gcp", "link": true @@ -49425,6 +49429,24 @@ "@walkeros/collector": "4.9.0" } }, + "packages/server/destinations/ga4": { + "name": "@walkeros/server-destination-ga4", + "version": "4.9.0", + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/elbwalker" + } + ], + "license": "MIT", + "dependencies": { + "@walkeros/core": "4.9.0", + "@walkeros/server-core": "4.9.0" + }, + "devDependencies": { + "@walkeros/collector": "4.9.0" + } + }, "packages/server/destinations/gcp": { "name": "@walkeros/server-destination-gcp", "version": "4.9.0", diff --git a/packages/server/destinations/ga4/README.md b/packages/server/destinations/ga4/README.md new file mode 100644 index 000000000..8ead08356 --- /dev/null +++ b/packages/server/destinations/ga4/README.md @@ -0,0 +1,65 @@ +

+ + walkerOS + +

+ +# @walkeros/server-destination-ga4 + +Server-side events to Google Analytics 4 through the Measurement Protocol: +conversions and other server events join the visitor's GA4 session when the +`_ga` client id and session id are mapped. + +[Documentation](https://www.walkeros.io/docs/destinations/server/ga4) • +[NPM Package](https://www.npmjs.com/package/@walkeros/server-destination-ga4) +• +[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/server/destinations/ga4) + +## Installation + +```bash +npm install @walkeros/server-destination-ga4 +``` + +## Quick start + +```json +{ + "version": 4, + "flows": { + "default": { + "config": { "platform": "server" }, + "destinations": { + "ga4": { + "package": "@walkeros/server-destination-ga4", + "config": { + "settings": { + "measurementId": "G-XXXXXXXXXX", + "apiSecret": "$secret.GA4_API_SECRET" + } + } + } + } + } + } +} +``` + +This quick start sets no consent: add `consent: { analytics: true }` to `config` +before you go live, see the docs. + +## Documentation + +Full configuration, mapping, and examples live in the docs: +**https://www.walkeros.io/docs/destinations/server/ga4** + +## Contribute + +Feel free to contribute by submitting an +[issue](https://github.com/elbwalker/walkerOS/issues), starting a +[discussion](https://github.com/elbwalker/walkerOS/discussions), or getting in +[contact](https://calendly.com/elb-alexander/30min). + +## License + +MIT diff --git a/packages/server/destinations/ga4/jest.config.mjs b/packages/server/destinations/ga4/jest.config.mjs new file mode 100644 index 000000000..d1e06ddf6 --- /dev/null +++ b/packages/server/destinations/ga4/jest.config.mjs @@ -0,0 +1,5 @@ +import baseConfig from '@walkeros/config/jest'; + +const config = {}; + +export default { ...baseConfig, ...config }; diff --git a/packages/server/destinations/ga4/package.json b/packages/server/destinations/ga4/package.json new file mode 100644 index 000000000..1697ff412 --- /dev/null +++ b/packages/server/destinations/ga4/package.json @@ -0,0 +1,76 @@ +{ + "name": "@walkeros/server-destination-ga4", + "description": "Google Analytics 4 Measurement Protocol server destination for walkerOS", + "version": "4.9.0", + "license": "MIT", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.mjs", + "require": "./dist/index.js" + }, + "./dev": { + "types": "./dist/dev.d.ts", + "import": "./dist/dev.mjs", + "require": "./dist/dev.js" + }, + "./walkerOS.json": "./dist/walkerOS.json", + "./examples": { + "types": "./dist/examples/index.d.ts", + "import": "./dist/examples/index.mjs", + "require": "./dist/examples/index.js" + } + }, + "files": [ + "dist/**", + "CHANGELOG.md" + ], + "scripts": { + "build": "tsup --silent", + "clean": "rm -rf .turbo && rm -rf dist", + "dev": "jest --watchAll --colors", + "typecheck": "tsc --noEmit", + "lint": "eslint \"**/*.ts*\"", + "test": "jest", + "update": "npx npm-check-updates -u && npm update" + }, + "dependencies": { + "@walkeros/core": "4.9.0", + "@walkeros/server-core": "4.9.0" + }, + "devDependencies": { + "@walkeros/collector": "4.9.0" + }, + "repository": { + "url": "git+https://github.com/elbwalker/walkerOS.git", + "directory": "packages/server/destinations/ga4" + }, + "author": "elbwalker ", + "homepage": "https://github.com/elbwalker/walkerOS#readme", + "bugs": { + "url": "https://github.com/elbwalker/walkerOS/issues" + }, + "walkerOS": { + "type": "destination", + "platform": [ + "server" + ], + "docs": "https://www.walkeros.io/docs/destinations/server/ga4" + }, + "keywords": [ + "walkerOS", + "walkerOS-destination", + "destination", + "server", + "ga4", + "google-analytics", + "measurement-protocol", + "analytics" + ], + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/elbwalker" + } + ] +} diff --git a/packages/server/destinations/ga4/src/__tests__/conformance.test.ts b/packages/server/destinations/ga4/src/__tests__/conformance.test.ts new file mode 100644 index 000000000..fb6cde146 --- /dev/null +++ b/packages/server/destinations/ga4/src/__tests__/conformance.test.ts @@ -0,0 +1,21 @@ +import path from 'path'; +import { conformance } from '@walkeros/collector/dev'; +import { destinationGA4 } from '..'; +import { examples, schemas } from '../dev'; + +describe('ga4 conformance', () => { + beforeEach(() => { + jest.useRealTimers(); + }); + + it('conforms', async () => { + await conformance('destination', destinationGA4, { + profile: 'http', + examples: examples.step, + schema: schemas.settings, + settings: examples.minimal.settings, + minimal: examples.minimal, + root: path.join(__dirname, '..', '..'), + }); + }); +}); diff --git a/packages/server/destinations/ga4/src/__tests__/index.test.ts b/packages/server/destinations/ga4/src/__tests__/index.test.ts new file mode 100644 index 000000000..b3fa8831d --- /dev/null +++ b/packages/server/destinations/ga4/src/__tests__/index.test.ts @@ -0,0 +1,161 @@ +import type { Collector, WalkerOS } from '@walkeros/core'; +import type { Settings } from '../types'; +import { + clone, + createMockContext, + createMockLogger, + getEvent, +} from '@walkeros/core'; +import { destinationGA4 as destination } from '..'; +import { fallbackClientId } from '../push'; +import { examples } from '../dev'; + +describe('Server Destination GA4 Measurement Protocol', () => { + const settings: Settings = { measurementId: 'G-TEST123', apiSecret: 'a&b' }; + const mockSendServer = jest.fn(); + const testEnv = clone(examples.env.push); + testEnv.sendServer = mockSendServer; + + const body = () => JSON.parse(mockSendServer.mock.calls[0][1]); + + function event(props: Partial = {}): WalkerOS.Event { + return getEvent('order complete', { + id: 'ev-1', + timestamp: 1700000900000, + consent: {}, + ...props, + }); + } + + async function push( + walkerEvent: WalkerOS.Event, + data: Record = {}, + extra: Partial = {}, + rule?: Record, + ) { + return destination.push( + walkerEvent, + createMockContext({ + config: { settings: { ...settings, ...extra } }, + data, + env: testEnv, + ...(rule ? { rule } : {}), + }), + ); + } + + async function init(config: Record) { + return destination.init({ + config: { settings: config as unknown as Settings }, + collector: {} as Collector.Instance, + env: testEnv, + logger: createMockLogger(), + id: 'test-ga4', + }); + } + + beforeEach(() => { + jest.clearAllMocks(); + mockSendServer.mockResolvedValue({ data: {} }); + }); + + test('init checks measurementId and apiSecret', async () => { + await expect(init({})).rejects.toThrow( + 'Config settings measurementId, apiSecret missing', + ); + await expect( + init({ measurementId: 'UA-1', apiSecret: 'x' }), + ).rejects.toThrow('must look like G-XXXX'); + }); + + test('endpoint carries encoded measurement id and secret', async () => { + await push(event()); + expect(mockSendServer.mock.calls[0][0]).toBe( + 'https://www.google-analytics.com/mp/collect?measurement_id=G-TEST123&api_secret=a%26b', + ); + }); + + test('custom url (EU collection)', async () => { + await push( + event(), + {}, + { + url: 'https://region1.google-analytics.com/mp/collect', + }, + ); + expect(mockSendServer.mock.calls[0][0]).toMatch( + /^https:\/\/region1\.google-analytics\.com\/mp\/collect\?/, + ); + }); + + test('event name: spaces become _, invalid names fail', async () => { + await push({ ...event(), name: 'order complete' }); + expect(body().events[0].name).toBe('order_complete'); + mockSendServer.mockClear(); + await expect( + push({ ...event(), name: '1 bad-name' }), + ).rejects.toMatchObject({ code: 'mapping', retryable: false }); + expect(mockSendServer).not.toHaveBeenCalled(); + }); + + test('valid client id and session id are kept', async () => { + await push(event(), { client_id: '123.456', session_id: 1699999000 }); + expect(body().client_id).toBe('123.456'); + expect(body().events[0].params.session_id).toBe('1699999000'); + }); + + test('malformed client id and session id are replaced or dropped', async () => { + await push(event(), { client_id: 'GA1.1.123.456', session_id: 'abc' }); + expect(body().client_id).toBe(await fallbackClientId(event())); + expect(body().events[0].params).not.toHaveProperty('session_id'); + }); + + test('fallback client id is stable per event id', async () => { + const a = await fallbackClientId(event()); + const b = await fallbackClientId(event()); + expect(a).toBe(b); + expect(a).toMatch(/^\d+\.1700000900$/); + expect(await fallbackClientId(event({ id: 'ev-2' }))).not.toBe(a); + }); + + test('value is a number, an invalid one is dropped', async () => { + await push(event(), { params: { value: '19.9', currency: 'EUR' } }); + expect(body().events[0].params.value).toBe(19.9); + mockSendServer.mockClear(); + await push(event(), { params: { value: 'n/a' } }); + expect(body().events[0].params).not.toHaveProperty('value'); + }); + + test('ad signals follow the marketing consent', async () => { + await push(event({ consent: { marketing: true } })); + expect(body().consent).toEqual({ + ad_user_data: 'GRANTED', + ad_personalization: 'GRANTED', + }); + mockSendServer.mockClear(); + await push(event({ consent: { analytics: true } })); + expect(body().consent.ad_user_data).toBe('DENIED'); + }); + + test('timestamp_micros only for events under 72 hours', async () => { + const recent = Date.now() - 1000; + await push(event({ timestamp: recent })); + expect(body().timestamp_micros).toBe(recent * 1000); + mockSendServer.mockClear(); + await push(event()); + expect(body()).not.toHaveProperty('timestamp_micros'); + }); + + test('user_id only when a non-empty string', async () => { + await push(event(), { user_id: 'u1' }); + expect(body().user_id).toBe('u1'); + mockSendServer.mockClear(); + await push(event(), { user_id: '' }); + expect(body()).not.toHaveProperty('user_id'); + }); + + test('silent rule sends nothing', async () => { + await push(event(), {}, {}, { silent: true }); + expect(mockSendServer).not.toHaveBeenCalled(); + }); +}); diff --git a/packages/server/destinations/ga4/src/__tests__/stepExamples.test.ts b/packages/server/destinations/ga4/src/__tests__/stepExamples.test.ts new file mode 100644 index 000000000..bb0d9d459 --- /dev/null +++ b/packages/server/destinations/ga4/src/__tests__/stepExamples.test.ts @@ -0,0 +1,68 @@ +import type { WalkerOS } from '@walkeros/core'; +import { startFlow } from '@walkeros/collector'; +import { clone, isObject } from '@walkeros/core'; +import { examples } from '../dev'; +import { expectSimulationResolves } from '@walkeros/core/dev'; + +type Captured = [callable: string, ...args: unknown[]]; + +/** + * GA4 Measurement Protocol destination invokes `env.sendServer(url, body, options)` + * exactly once per push. Stateless: no init-time calls to filter. + */ +describe('Step Examples', () => { + const mockSendServer = jest.fn(); + + beforeEach(() => { + jest.clearAllMocks(); + mockSendServer.mockResolvedValue({ + data: { success: true }, + }); + }); + + // Non-public examples (silent, failures) run in the conformance test. + const published = Object.entries(examples.step).filter( + ([, example]) => example.public !== false, + ); + + it.each(published)('%s', async (_name, example) => { + const event = example.in as WalkerOS.Event; + const mapping = example.mapping; + + const testEnv = clone(examples.env.push); + testEnv.sendServer = mockSendServer; + + const dest = jest.requireActual('../').default; + const { elb } = await startFlow(); + + const mappingConfig = mapping + ? { [event.entity]: { [event.action]: mapping } } + : undefined; + + await elb('walker destination', { + code: { ...dest, env: testEnv }, + config: { + settings: { measurementId: 'G-TEST123', apiSecret: 's3cr3t' }, + mapping: mappingConfig, + }, + }); + + await elb(event); + + const captured: Captured[] = mockSendServer.mock.calls.map( + (args) => ['sendServer', ...args] as Captured, + ); + + expect(captured).toEqual(example.out); + }); +}); + +it('declares simulation paths that resolve', () => + expectSimulationResolves(examples.env)); + +it('gives every example event a timestamp in milliseconds', () => { + for (const example of Object.values(examples.step)) { + const timestamp = isObject(example.in) ? example.in.timestamp : undefined; + expect(timestamp).toBeGreaterThan(1e12); + } +}); diff --git a/packages/server/destinations/ga4/src/config.ts b/packages/server/destinations/ga4/src/config.ts new file mode 100644 index 000000000..ded9ed9c8 --- /dev/null +++ b/packages/server/destinations/ga4/src/config.ts @@ -0,0 +1,28 @@ +import type { Config, Settings, PartialConfig } from './types'; +import { StepError } from '@walkeros/core'; + +const MEASUREMENT_ID = /^G-[A-Z0-9]+$/; + +export function getConfig(partialConfig: PartialConfig = {}): Config { + const settings: Partial = partialConfig.settings || {}; + const { measurementId, apiSecret } = settings; + + if (!measurementId || !apiSecret) { + const missing = [ + ...(measurementId ? [] : ['measurementId']), + ...(apiSecret ? [] : ['apiSecret']), + ]; + throw new StepError(`Config settings ${missing.join(', ')} missing`, { + code: 'config', + }); + } + if (!MEASUREMENT_ID.test(measurementId)) + throw new StepError('Config settings measurementId must look like G-XXXX', { + code: 'config', + }); + + return { + ...partialConfig, + settings: { ...settings, measurementId, apiSecret }, + }; +} diff --git a/packages/server/destinations/ga4/src/dev.ts b/packages/server/destinations/ga4/src/dev.ts new file mode 100644 index 000000000..706f4127d --- /dev/null +++ b/packages/server/destinations/ga4/src/dev.ts @@ -0,0 +1,2 @@ +export * as schemas from './schemas'; +export * as examples from './examples'; diff --git a/packages/server/destinations/ga4/src/examples/env.ts b/packages/server/destinations/ga4/src/examples/env.ts new file mode 100644 index 000000000..ff1e83fb1 --- /dev/null +++ b/packages/server/destinations/ga4/src/examples/env.ts @@ -0,0 +1,36 @@ +import type { SendDataValue, SendResponse } from '@walkeros/core'; +import type { SendServerOptions } from '@walkeros/server-core'; +import type { Env } from '../types'; + +/** + * Example environment configurations for GA4 Measurement Protocol destination + * + * These environments provide standardized mock structures for testing + * and development without requiring actual HTTP requests. + */ + +type MockSendServer = ( + url: string, + data?: SendDataValue, + options?: SendServerOptions, +) => Promise; + +/** + * Mock sendServer function that simulates successful HTTP responses + */ +const mockSendServer: MockSendServer = async () => { + // GA4 answers 2xx with no body, even for an invalid payload + return { data: {} }; +}; + +/** + * Standard mock environment for push operations + * + * Use this for testing GA4 events without making + * actual HTTP requests to Google. + */ +export const push: Env = { + sendServer: mockSendServer, +}; + +export const simulation = ['sendServer']; diff --git a/packages/server/destinations/ga4/src/examples/index.ts b/packages/server/destinations/ga4/src/examples/index.ts new file mode 100644 index 000000000..181dfc860 --- /dev/null +++ b/packages/server/destinations/ga4/src/examples/index.ts @@ -0,0 +1,3 @@ +export * as env from './env'; +export * as step from './step'; +export { minimal } from './minimal'; diff --git a/packages/server/destinations/ga4/src/examples/minimal.ts b/packages/server/destinations/ga4/src/examples/minimal.ts new file mode 100644 index 000000000..f4c489eca --- /dev/null +++ b/packages/server/destinations/ga4/src/examples/minimal.ts @@ -0,0 +1,10 @@ +import type { Flow } from '@walkeros/core'; + +/** + * The settings GA4 needs to deliver: the measurement id and the Measurement + * Protocol API secret, read from the environment. + */ +export const minimal: Flow.MinimalExample = { + settings: { measurementId: 'G-TEST123', apiSecret: 's3cr3t' }, + secrets: { apiSecret: 'GA4_API_SECRET' }, +}; diff --git a/packages/server/destinations/ga4/src/examples/step.ts b/packages/server/destinations/ga4/src/examples/step.ts new file mode 100644 index 000000000..ad2198228 --- /dev/null +++ b/packages/server/destinations/ga4/src/examples/step.ts @@ -0,0 +1,160 @@ +import type { Flow } from '@walkeros/core'; +import { createEvent, getEvent } from '@walkeros/core'; + +/** + * GA4 Measurement Protocol step examples. + * + * At push time, the destination calls + * `env.sendServer(endpoint, JSON.stringify(body), options)` where + * `endpoint = ${settings.url}?measurement_id=...&api_secret=...` and + * `body = { client_id, user_id?, timestamp_micros?, consent, events: [{ name, params }] }`. + * + * The test fixture pins `measurementId = 'G-TEST123'` and + * `apiSecret = 's3cr3t'`. Example events are older than 72 hours, so + * `timestamp_micros` is left out (GA4 would refuse it) and GA4 uses the + * reception time. + */ +const ENDPOINT = + 'https://www.google-analytics.com/mp/collect?measurement_id=G-TEST123&api_secret=s3cr3t'; +const OPTIONS = { headers: { 'Content-Type': 'application/json' } }; +const DENIED = { ad_user_data: 'DENIED', ad_personalization: 'DENIED' }; +const GRANTED = { ad_user_data: 'GRANTED', ad_personalization: 'GRANTED' }; + +export const purchase: Flow.StepExample = { + title: 'Purchase', + description: + 'A completed order joins the visitor GA4 session as a purchase with value, currency and transaction id; marketing consent grants the ad signals.', + in: getEvent('order complete', { + id: 'ev-1700000900', + timestamp: 1700000900000, + data: { id: 'ORD-300', total: 249.99, currency: 'EUR' }, + globals: { + ga_client_id: '1234567890.1699990000', + ga_session_id: '1699999000', + }, + consent: { marketing: true }, + }), + mapping: { + name: 'purchase', + data: { + map: { + client_id: 'globals.ga_client_id', + session_id: 'globals.ga_session_id', + params: { + map: { + value: 'data.total', + currency: 'data.currency', + transaction_id: 'data.id', + }, + }, + }, + }, + }, + out: [ + [ + 'sendServer', + ENDPOINT, + JSON.stringify({ + client_id: '1234567890.1699990000', + consent: GRANTED, + events: [ + { + name: 'purchase', + params: { + value: 249.99, + currency: 'EUR', + transaction_id: 'ORD-300', + session_id: '1699999000', + engagement_time_msec: 1, + }, + }, + ], + }), + OPTIONS, + ], + ], +}; + +export const generateLead: Flow.StepExample = { + title: 'Lead with user id', + description: + 'A demo request is sent as generate_lead with the visitor GA4 client id and the signed-in user id.', + in: createEvent({ + name: 'demo request', + id: 'ev-1700000901', + timestamp: 1700000901000, + data: { location: 'hero' }, + user: { id: 'user-42' }, + globals: { ga_client_id: '1234567890.1699990000' }, + }), + mapping: { + name: 'generate_lead', + data: { + map: { + client_id: 'globals.ga_client_id', + user_id: 'user.id', + params: { map: { location: 'data.location' } }, + }, + }, + }, + out: [ + [ + 'sendServer', + ENDPOINT, + JSON.stringify({ + client_id: '1234567890.1699990000', + user_id: 'user-42', + consent: DENIED, + events: [ + { + name: 'generate_lead', + params: { location: 'hero', engagement_time_msec: 1 }, + }, + ], + }), + OPTIONS, + ], + ], +}; + +export const withoutClientId: Flow.StepExample = { + title: 'Event without GA4 client id', + description: + 'Without a _ga client id, a stable one is derived from the event id so the event still counts (as a new user) and a retry keeps the same id.', + in: createEvent({ + name: 'user register', + id: 'ev-1700000902', + timestamp: 1700000902000, + data: { method: 'email' }, + }), + mapping: { + name: 'sign_up', + data: { map: { params: { map: { method: 'data.method' } } } }, + }, + out: [ + [ + 'sendServer', + ENDPOINT, + JSON.stringify({ + client_id: '735042307.1700000902', + consent: DENIED, + events: [ + { + name: 'sign_up', + params: { method: 'email', engagement_time_msec: 1 }, + }, + ], + }), + OPTIONS, + ], + ], +}; + +/** A silent rule sends nothing to GA4. */ +export const silentRule: Flow.StepExample = { + public: false, + description: 'A rule with silent: true sends no request to GA4.', + in: getEvent('page view', { timestamp: 1700000990000 }), + mapping: { silent: true }, + out: [], +}; diff --git a/packages/server/destinations/ga4/src/index.ts b/packages/server/destinations/ga4/src/index.ts new file mode 100644 index 000000000..4ea19dd77 --- /dev/null +++ b/packages/server/destinations/ga4/src/index.ts @@ -0,0 +1,22 @@ +import type { Destination } from './types'; +import { getConfig } from './config'; +import { push } from './push'; + +// Types +export * as DestinationGA4 from './types'; + +export const destinationGA4: Destination = { + type: 'ga4', + + config: {}, + + async init({ config: partialConfig }) { + return getConfig(partialConfig); + }, + + async push(event, context) { + return await push(event, context); + }, +}; + +export default destinationGA4; diff --git a/packages/server/destinations/ga4/src/push.ts b/packages/server/destinations/ga4/src/push.ts new file mode 100644 index 000000000..ecbb3fde2 --- /dev/null +++ b/packages/server/destinations/ga4/src/push.ts @@ -0,0 +1,106 @@ +import type { ConsentValue, PushFn, RequestBody } from './types'; +import type { WalkerOS } from '@walkeros/core'; +import { isObject, StepError } from '@walkeros/core'; +import { getHashServer, sendServer } from '@walkeros/server-core'; + +const DEFAULT_URL = 'https://www.google-analytics.com/mp/collect'; + +// ".", as in the _ga cookie GA1.1.. +const CLIENT_ID = /^\d{1,20}\.\d{1,20}$/; +const SESSION_ID = /^\d{1,20}$/; +const EVENT_NAME = /^[A-Za-z][A-Za-z0-9_]{0,39}$/; +// GA4 accepts events up to 72 hours old; older ones get the reception time. +const MAX_AGE_MS = 71 * 3600 * 1000; + +function withoutUndefined(value: T): T { + return Object.fromEntries( + Object.entries(value).filter(([, item]) => item !== undefined), + ) as T; +} + +/** + * A stable client id for an event without one (no _ga cookie): derived from + * the event id, so a retried event keeps the same id. + */ +export async function fallbackClientId(event: WalkerOS.Event): Promise { + const digest = await getHashServer(String(event.id ?? '')); + const random = parseInt(digest.slice(0, 8), 16); + const seconds = Math.floor(Number(event.timestamp || Date.now()) / 1000); + return `${random}.${seconds}`; +} + +/** Event name: the mapped name with `_` for spaces. */ +function eventName(name: string): string { + const normalized = name.trim().replace(/ /g, '_'); + if (!EVENT_NAME.test(normalized)) + throw new StepError(`GA4 event name "${name}" is invalid`, { + code: 'mapping', + retryable: false, + }); + return normalized; +} + +export async function buildBody( + event: WalkerOS.Event, + data: Record, +): Promise { + const params: Record = withoutUndefined({ + ...(isObject(data.params) ? data.params : {}), + session_id: SESSION_ID.test(String(data.session_id ?? '')) + ? String(data.session_id) + : undefined, + engagement_time_msec: 1, + }); + if (params.value !== undefined) { + const value = Number(params.value); + if (Number.isFinite(value)) params.value = value; + else delete params.value; + } + + const ads: ConsentValue = + event.consent?.marketing === true ? 'GRANTED' : 'DENIED'; + const timestamp = Number(event.timestamp); + const clientId = String(data.client_id ?? ''); + + return withoutUndefined({ + client_id: CLIENT_ID.test(clientId) + ? clientId + : await fallbackClientId(event), + user_id: + typeof data.user_id === 'string' && data.user_id !== '' + ? data.user_id + : undefined, + timestamp_micros: + Number.isFinite(timestamp) && timestamp > Date.now() - MAX_AGE_MS + ? Math.round(timestamp) * 1000 + : undefined, + consent: { ad_user_data: ads, ad_personalization: ads }, + events: [{ name: eventName(event.name), params }], + }); +} + +// A silent rule has no GA4 call of its own: nothing to send. +export const push: PushFn = async function (event, context) { + if (!context.rule?.silent) await send(event, context); +}; + +const send: PushFn = async function (event, { config, data, env, logger }) { + const { measurementId, apiSecret, url = DEFAULT_URL } = config.settings ?? {}; + if (!measurementId || !apiSecret) + throw new StepError('GA4 settings missing, init() not run', { + code: 'not-ready', + }); + + const body = await buildBody(event, isObject(data) ? data : {}); + const endpoint = `${url}?measurement_id=${encodeURIComponent(measurementId)}&api_secret=${encodeURIComponent(apiSecret)}`; + + logger.debug('Calling GA4 Measurement Protocol', { + name: body.events[0].name, + eventId: event.id, + }); + + const sendServerFn = env?.sendServer || sendServer; + await sendServerFn(endpoint, JSON.stringify(body), { + headers: { 'Content-Type': 'application/json' }, + }); +}; diff --git a/packages/server/destinations/ga4/src/schemas/index.ts b/packages/server/destinations/ga4/src/schemas/index.ts new file mode 100644 index 000000000..9dcaf388d --- /dev/null +++ b/packages/server/destinations/ga4/src/schemas/index.ts @@ -0,0 +1,12 @@ +import { zodToSchema } from '@walkeros/core/dev'; +import { SettingsSchema } from './settings'; +import { MappingSchema } from './mapping'; + +export * from './primitives'; + +export { SettingsSchema, type Settings } from './settings'; +export { MappingSchema, type Mapping } from './mapping'; + +// JSON Schema +export const settings = zodToSchema(SettingsSchema); +export const mapping = zodToSchema(MappingSchema); diff --git a/packages/server/destinations/ga4/src/schemas/mapping.ts b/packages/server/destinations/ga4/src/schemas/mapping.ts new file mode 100644 index 000000000..3d4ba2aa4 --- /dev/null +++ b/packages/server/destinations/ga4/src/schemas/mapping.ts @@ -0,0 +1,9 @@ +import { z } from '@walkeros/core/dev'; + +/** + * GA4 Measurement Protocol Mapping Schema + * The rule `name` is the GA4 event name; no other rule settings. + */ +export const MappingSchema = z.object({}); + +export type Mapping = z.infer; diff --git a/packages/server/destinations/ga4/src/schemas/primitives.ts b/packages/server/destinations/ga4/src/schemas/primitives.ts new file mode 100644 index 000000000..29bf961a0 --- /dev/null +++ b/packages/server/destinations/ga4/src/schemas/primitives.ts @@ -0,0 +1,4 @@ +import { z } from '@walkeros/core/dev'; + +/** GA4 measurement id of a web data stream. */ +export const MeasurementIdSchema = z.string().regex(/^G-[A-Z0-9]+$/); diff --git a/packages/server/destinations/ga4/src/schemas/settings.ts b/packages/server/destinations/ga4/src/schemas/settings.ts new file mode 100644 index 000000000..94f1dc52b --- /dev/null +++ b/packages/server/destinations/ga4/src/schemas/settings.ts @@ -0,0 +1,25 @@ +import { z } from '@walkeros/core/dev'; +import { MeasurementIdSchema } from './primitives'; + +export const SettingsSchema = z + .object({ + measurementId: MeasurementIdSchema.describe( + 'GA4 measurement id of the web data stream (like G-ABC123XYZ)', + ), + apiSecret: z + .string() + .min(1) + .describe( + 'Measurement Protocol API secret: GA4 Admin > Data streams > the stream > Measurement Protocol API secrets (like Ab12Cd34...)', + ), + url: z + .string() + .url() + .describe( + 'Endpoint without query string. EU collection: https://region1.google-analytics.com/mp/collect; testing: https://www.google-analytics.com/debug/mp/collect (like https://www.google-analytics.com/mp/collect)', + ) + .optional(), + }) + .strict(); + +export type Settings = z.infer; diff --git a/packages/server/destinations/ga4/src/types/index.ts b/packages/server/destinations/ga4/src/types/index.ts new file mode 100644 index 000000000..42981d21c --- /dev/null +++ b/packages/server/destinations/ga4/src/types/index.ts @@ -0,0 +1,66 @@ +import type { + Mapping as WalkerOSMapping, + Destination as CoreDestination, +} from '@walkeros/core'; +import type { DestinationServer, sendServer } from '@walkeros/server-core'; + +export interface Settings { + /** GA4 measurement id of the web data stream (G-...) */ + measurementId: string; + /** Measurement Protocol API secret of that stream */ + apiSecret: string; + /** + * Endpoint without query string. + * @default 'https://www.google-analytics.com/mp/collect' + */ + url?: string; +} + +export type InitSettings = Partial; + +export interface Mapping {} + +export interface Env extends DestinationServer.Env { + sendServer?: typeof sendServer; +} + +export type Types = CoreDestination.Types; + +export interface Destination extends DestinationServer.Destination { + init: DestinationServer.InitFn; +} + +export type Config = { + settings: Settings; +} & DestinationServer.Config; + +export type InitFn = DestinationServer.InitFn; +export type PushFn = DestinationServer.PushFn; + +export type PartialConfig = DestinationServer.PartialConfig; + +export type PushEvents = DestinationServer.PushEvents; + +export type Rule = WalkerOSMapping.Rule; +export type Rules = WalkerOSMapping.Rules; + +// GA4 Measurement Protocol types +// https://developers.google.com/analytics/devguides/collection/protocol/ga4 + +export type ConsentValue = 'GRANTED' | 'DENIED'; + +export interface MeasurementEvent { + name: string; + params: Record; +} + +export interface RequestBody { + client_id: string; + user_id?: string; + timestamp_micros?: number; + consent: { + ad_user_data: ConsentValue; + ad_personalization: ConsentValue; + }; + events: MeasurementEvent[]; +} diff --git a/packages/server/destinations/ga4/tsconfig.json b/packages/server/destinations/ga4/tsconfig.json new file mode 100644 index 000000000..b1c75c589 --- /dev/null +++ b/packages/server/destinations/ga4/tsconfig.json @@ -0,0 +1,8 @@ +{ + "extends": "@walkeros/config/tsconfig/node.json", + "compilerOptions": { + "rootDir": "src" + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist"] +} diff --git a/packages/server/destinations/ga4/tsup.config.ts b/packages/server/destinations/ga4/tsup.config.ts new file mode 100644 index 000000000..0f100c52d --- /dev/null +++ b/packages/server/destinations/ga4/tsup.config.ts @@ -0,0 +1,14 @@ +import { + defineConfig, + buildModules, + buildExamples, + buildDev, +} from '@walkeros/config/tsup'; + +export default defineConfig([ + buildModules({ + terserOptions: { mangle: false }, + }), + buildExamples(), + buildDev(), +]); diff --git a/website/docs/destinations/index.mdx b/website/docs/destinations/index.mdx index 4351459f1..597095a93 100644 --- a/website/docs/destinations/index.mdx +++ b/website/docs/destinations/index.mdx @@ -76,7 +76,7 @@ destination batches answer `queued` until the flush. | **Clarity** | Yes | - | | **d8a** | Yes | - | | **FullStory** | Yes | - | -| **GA4** | Yes | - | +| **GA4** | Yes | Yes | | **GTM** | Yes | - | | **Heap** | Yes | - | | **Hotjar** | Yes | - | diff --git a/website/docs/destinations/server/ga4.mdx b/website/docs/destinations/server/ga4.mdx new file mode 100644 index 000000000..529340fb5 --- /dev/null +++ b/website/docs/destinations/server/ga4.mdx @@ -0,0 +1,101 @@ +--- +title: GA4 Measurement Protocol +description: "Server-side events to Google Analytics 4 through the Measurement Protocol" +path: /docs/destinations/server/ga4 +sidebar_position: 7 +package: '@walkeros/server-destination-ga4' +--- +import data from '@walkeros/server-destination-ga4/walkerOS.json'; +import Configuration from '@site/src/components/snippets/_configuration.mdx'; +import Quickstart from '@site/src/components/snippets/_quickstart.mdx'; + +import WhereThisFits from '@site/src/components/snippets/_where-this-fits.mdx'; + +# GA4 Measurement Protocol + + + +Server-side events to Google Analytics 4 through the [Measurement Protocol](https://developers.google.com/analytics/devguides/collection/protocol/ga4). Use it for events that happen on a server (a sign-up confirmed by your app, a payment webhook) or that should not depend on the browser; the [gtag web destination](/docs/destinations/web/gtag/ga4) stays the way to send page views and browser events. + +GA4 Measurement Protocol is a server destination in the walkerOS flow:} + flowMap={{ + destinations: { default: { label: 'Destination', text: 'GA4 MP', highlight: true } }, + }} + post={<>Sends one event per request to `/mp/collect` with the measurement id and API secret in the query string, using raw HTTP (no SDK). Nothing personal is sent unless you map it: no email, IP or user agent.} +/> + +## Installation + + + + + +## Joining the visitor's session + +The Measurement Protocol attributes an event to a visitor and a session only through ids you send. Read them in the browser and carry them to the server event (for example as `globals`): + +| Mapped `data` | Sent as | Where it comes from | +|---|---|---| +| `client_id` | `client_id` | The `_ga` cookie `GA1.1..`: send `.` | +| `session_id` | `events[0].params.session_id` | The `_ga_` cookie (digits) | +| `user_id` | `user_id` | Your own user id (optional) | +| `params` | `events[0].params` | Event parameters, such as `value` (sent as a number), `currency`, `transaction_id` | + +With a valid `client_id` and `session_id` the event joins the visitor's session and its traffic source. Without a valid `client_id`, the destination derives a stable one from the walkerOS event id: the event still counts, as a new user, and a retry keeps the same id. `engagement_time_msec: 1` is added so the event counts as engaged. + + + +## Event name + +The mapped name, with `_` for spaces (`order complete` becomes `order_complete`). GA4 accepts letters, digits and `_`, starting with a letter, up to 40 characters: an invalid name fails with the code `mapping` and nothing is sent. Use GA4's recommended names (`purchase`, `sign_up`, `generate_lead`) for reports and key events to pick them up. + +## Consent + +`consent.ad_user_data` and `consent.ad_personalization` are `GRANTED` only when the event carries `marketing` consent, else `DENIED`. Gate the destination itself on measurement consent: add `consent: { analytics: true }` to `config`, next to `settings` (see [Gate a destination with consent](/docs/guides/consent#gate-a-destination-with-consent)). + +## Timestamps + +`timestamp_micros` is the event time when the event is less than 71 hours old; GA4 refuses older ones, so an older event (a late retry) is sent without it and GA4 uses the reception time. + +## Testing + +GA4 answers 2xx even to an invalid payload. While setting up, point `url` to the validation server, which answers with the problems it finds and records nothing: + + + +For collection in the EU, use `https://region1.google-analytics.com/mp/collect`. + +## Failures + +- A response outside the 2xx range, a network error or no answer within 5 seconds fails with `transport` (with the HTTP status) or `timeout`; 429 and 5xx are retried. +- Without `measurementId` or `apiSecret`, or with a measurement id that is not `G-...`, the destination does not start: every push answers `failed` with the code `config`. +- A rule with `silent: true` sends nothing. + +## Links + +- [GA4 Measurement Protocol](https://developers.google.com/analytics/devguides/collection/protocol/ga4) +- [Validating events](https://developers.google.com/analytics/devguides/collection/protocol/ga4/validating-events) diff --git a/website/package.json b/website/package.json index 9999364b6..a696651b8 100644 --- a/website/package.json +++ b/website/package.json @@ -35,6 +35,7 @@ "@walkeros/server-destination-customerio": "^4.9.0", "@walkeros/server-destination-datamanager": "^4.9.0", "@walkeros/server-destination-file": "^4.9.0", + "@walkeros/server-destination-ga4": "^4.9.0", "@walkeros/server-destination-gcp": "^4.9.0", "@walkeros/server-destination-hubspot": "^4.9.0", "@walkeros/server-destination-kafka": "^4.9.0", diff --git a/website/sidebars.ts b/website/sidebars.ts index 5696f2b85..b372dc261 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -546,6 +546,11 @@ const sidebars: SidebarsConfig = { id: 'destinations/server/file', className: 'sidebar-badge-server', }, + { + type: 'doc', + id: 'destinations/server/ga4', + className: 'sidebar-badge-server', + }, { type: 'doc', id: 'destinations/server/gcp', From d17a07750d581e794c283f2bbc723dd401d0d5ce Mon Sep 17 00:00:00 2001 From: laurentdav <45101601+laurentdav@users.noreply.github.com> Date: Tue, 17 Nov 2026 23:23:01 +0100 Subject: [PATCH 2/2] docs(ga4): no promise of automatic retries Same finding as on the sibling OpenAI Ads PR: a failed request goes to the dead-letter queue; 429 and 5xx are only marked retryable. Co-Authored-By: Claude Opus 5.5 --- website/docs/destinations/server/ga4.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/destinations/server/ga4.mdx b/website/docs/destinations/server/ga4.mdx index 529340fb5..bb8ef8bac 100644 --- a/website/docs/destinations/server/ga4.mdx +++ b/website/docs/destinations/server/ga4.mdx @@ -91,7 +91,7 @@ For collection in the EU, use `https://region1.google-analytics.com/mp/collect`. ## Failures -- A response outside the 2xx range, a network error or no answer within 5 seconds fails with `transport` (with the HTTP status) or `timeout`; 429 and 5xx are retried. +- A response outside the 2xx range, a network error or no answer within 5 seconds fails with `transport` (with the HTTP status) or `timeout`, and the event goes to the dead-letter queue. 429 and 5xx are marked retryable, other 4xx not; nothing resends the event by itself. - Without `measurementId` or `apiSecret`, or with a measurement id that is not `G-...`, the destination does not start: every push answers `failed` with the code `config`. - A rule with `silent: true` sends nothing.