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/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..bb8ef8bac
--- /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`, 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.
+
+## 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',