@endora-commerce/mod-google-tag-manager 0.100.0

package/dist/backend/services/ss-relay.service.js

@@ -0,0 +1,77 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { GOOGLE_TAG_MANAGER_SETTING_CODES } from '@endora-commerce/contracts';
+/**
+ * Server-side relay orchestration (feature 066, US3).
+ *
+ * - `makeEnqueuer` returns the producer used by the `/collect` route: it
+ *   assigns one uuid `eventId` per event (the idempotency key and the BullMQ
+ *   `jobId`) and enqueues one relay job each. Pure producer — no outbound call
+ *   happens in the shopper's request (Principle X / FR-029).
+ * - `makeProcessor` returns the BullMQ processor: it resolves the channel's
+ *   server container address from Settings, drops the visitor's IP and user
+ *   agent unless consent was granted (FR-030), and forwards through the sGTM
+ *   client, letting a failure throw so BullMQ retries.
+ */
+export function makeEnqueuer(queue) {
+    return async (salesChannelId, request, context) => {
+        // One timestamp for the whole batch: it is when the visitor acted, not when
+        // a retry happened to reach the destination.
+        const occurredAt = new Date().toISOString();
+        let accepted = 0;
+        for (const event of request.events) {
+            const eventId = randomUUID();
+            await queue.add('relay', {
+                eventId,
+                salesChannelId,
+                clientId: request.clientId,
+                // `gtm_event_id` travels in the params so the operator's container
+                // can deduplicate a retried delivery.
+                event: { name: event.name, params: { ...event.params, gtm_event_id: eventId } },
+                consent: request.consent,
+                page: request.page,
+                ...(context.ip ? { ip: context.ip } : {}),
+                ...(context.userAgent ? { userAgent: context.userAgent } : {}),
+                occurredAt,
+            }, { jobId: eventId });
+            accepted += 1;
+        }
+        return accepted;
+    };
+}
+export function makeProcessor(deps) {
+    return async (job) => {
+        const { salesChannelId } = job.data;
+        const baseUrl = await read(deps.settings, GOOGLE_TAG_MANAGER_SETTING_CODES.SERVER_CONTAINER_URL, salesChannelId);
+        if (!baseUrl.trim()) {
+            // The operator cleared the address between enqueue and delivery. That is
+            // a permanent no-op, not a transient failure — returning rather than
+            // throwing keeps it from burning eight retries.
+            return;
+        }
+        const ingestPath = await read(deps.settings, GOOGLE_TAG_MANAGER_SETTING_CODES.SERVER_INGEST_PATH, salesChannelId);
+        const granted = job.data.consent.analyticsStorage === 'granted';
+        const event = {
+            eventId: job.data.eventId,
+            clientId: job.data.clientId,
+            name: job.data.event.name,
+            params: job.data.event.params,
+            consent: job.data.consent,
+            page: job.data.page,
+            // FR-030 — the visitor's IP and user agent travel only with consent.
+            ...(granted && job.data.ip ? { ip: job.data.ip } : {}),
+            ...(granted && job.data.userAgent ? { userAgent: job.data.userAgent } : {}),
+        };
+        await deps.client.send({ baseUrl, ingestPath }, event);
+    };
+}
+/** A destination read must never fail the job on an unregistered setting. */
+async function read(settings, code, salesChannelId) {
+    try {
+        return await settings.get(code, salesChannelId, z.string());
+    }
+    catch {
+        return '';
+    }
+}
+//# sourceMappingURL=ss-relay.service.js.map

package/dist/backend/services/ss-relay.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ss-relay.service.js","sourceRoot":"","sources":["../../../src/backend/services/ss-relay.service.ts"],"names":[],"mappings":"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"}

package/dist/manifest.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Google Tag Manager module (feature 066). Puts the operator's GTM container on
+ * the storefront per sales channel, publishes a documented commerce `dataLayer`
+ * vocabulary for their tags to trigger on, and optionally relays the
+ * relay-eligible subset of those events to their server-side container.
+ *
+ * The module owns no table and no admin page: every tag, trigger and variable
+ * lives in the GTM console, and the six values below are managed on the generic
+ * Settings screen (research §§R2-R3). Consequently it declares no permission
+ * codes — the one palette action references the core `settings:read` code.
+ */
+export declare const googleTagManagerSettingsManifest: {
+    moduleCode: string;
+    groups: {
+        code: string;
+        name: string;
+        salesChannelCodes?: string[] | undefined;
+        isSystemProtected?: boolean | undefined;
+    }[];
+    settings: {
+        code: string;
+        name: string;
+        valueType: "string" | "number" | "boolean" | "json" | "string_list" | "secret" | "credential_ref";
+        defaultValue: unknown;
+        description?: string | undefined;
+        groupCode?: string | undefined;
+        previousDefaultValues?: unknown[] | undefined;
+        salesChannelCodes?: string[] | undefined;
+        enumOptions?: string[] | undefined;
+        configurationType?: string | undefined;
+        hidden?: boolean | undefined;
+    }[];
+};
+export declare const manifest: {
+    id: string;
+    name: string;
+    version: string;
+    dependencies: string[];
+    description?: string | undefined;
+    acknowledgedDependencies?: {
+        moduleId: string;
+        port: string;
+        reason: string;
+    }[] | undefined;
+    nonBindingDependencies?: {
+        moduleId: string;
+        name: string;
+        kind: "contributes-to" | "degrades-without" | "refuses-without";
+        reason: string;
+        whenAbsent?: string | undefined;
+    }[] | undefined;
+    activation?: {
+        settingCode: string;
+        default: boolean;
+    } | {
+        nonDeactivatable: true;
+        reason: string;
+    } | undefined;
+    settings?: {
+        moduleCode: string;
+        groups: {
+            code: string;
+            name: string;
+            salesChannelCodes?: string[] | undefined;
+            isSystemProtected?: boolean | undefined;
+        }[];
+        settings: {
+            code: string;
+            name: string;
+            valueType: "string" | "number" | "boolean" | "json" | "string_list" | "secret" | "credential_ref";
+            defaultValue: unknown;
+            description?: string | undefined;
+            groupCode?: string | undefined;
+            previousDefaultValues?: unknown[] | undefined;
+            salesChannelCodes?: string[] | undefined;
+            enumOptions?: string[] | undefined;
+            configurationType?: string | undefined;
+            hidden?: boolean | undefined;
+        }[];
+    } | undefined;
+    i18n?: {
+        bundlesDir: string;
+    } | undefined;
+    docs?: false | {
+        dir: string;
+    } | undefined;
+    demo?: false | {
+        summary: string;
+        seed: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoSeedResult>;
+        reset: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoResetResult>;
+        after?: readonly string[] | undefined;
+        package?: string | undefined;
+    } | undefined;
+    actions?: {
+        id: string;
+        labelKey: string;
+        icon: "Plus" | "Sparkles" | "Settings" | "Search" | "Boxes" | "Layers" | "Menu" | "PlusCircle" | "PlusSquare" | "FilePlus" | "FolderPlus" | "Upload" | "FileUp" | "CloudUpload" | "Download" | "FileDown" | "FileText" | "BookOpen" | "Rss" | "Package" | "Tag" | "ShoppingCart" | "Receipt" | "CreditCard" | "Users" | "UserPlus" | "Inbox" | "ListChecks" | "ClipboardList" | "Image" | "Video" | "LayoutDashboard" | "PanelLeft" | "KeyRound" | "ShieldCheck" | "Edit" | "Archive" | "Box" | "Truck" | "CircleDollarSign" | "Activity" | "LineChart" | "Smartphone" | "Webhook" | "Scale" | "PlugZap" | "PercentDiamond" | "Newspaper" | "Languages" | "Eraser" | "Warehouse" | "TrendingDown" | "Bell" | "PackageOpen" | "Building2" | "Store" | "ClipboardCheck";
+        targetRoute: string;
+        keywords: string[];
+        weight: number;
+        descriptionKey?: string | undefined;
+        requiredPermission?: string | undefined;
+    }[] | undefined;
+    permissions?: {
+        code: string;
+        label: string;
+        module?: string | undefined;
+        description?: string | undefined;
+        requires?: string[] | undefined;
+    }[] | undefined;
+    transactionalEmails?: {
+        code: string;
+        name: string;
+        variables: {
+            key: string;
+            label: string;
+            sampleValue?: string | undefined;
+            description?: string | undefined;
+        }[];
+        description?: string | undefined;
+        group?: string | undefined;
+    }[] | undefined;
+    capabilities?: string[] | undefined;
+    exclusiveCapabilities?: {
+        key: string;
+        errorCode: string;
+    }[] | undefined;
+    errorCodes?: {
+        code: string;
+        tokens?: string[] | undefined;
+    }[] | undefined;
+    blocks?: {
+        name: string;
+        labelKey: string;
+        category: string;
+        contexts: ("invoice" | "email" | "cms" | "newsletter")[];
+        fields: Record<string, {
+            type: "number" | "object" | "array" | "text" | "textarea" | "select" | "radio" | "external" | "uuid" | "richtext";
+            label?: string | undefined;
+            required?: boolean | undefined;
+            options?: {
+                label: string;
+                value: string | number;
+            }[] | undefined;
+            refKind?: string | undefined;
+        }>;
+        descriptionKey?: string | undefined;
+        defaultProps?: Record<string, unknown> | undefined;
+        responsiveFields?: string[] | undefined;
+        previewIcon?: string | undefined;
+        weight?: number | undefined;
+    }[] | undefined;
+    blockCategories?: {
+        key: string;
+        titleKey: string;
+        contexts: ("invoice" | "email" | "cms" | "newsletter")[];
+        weight?: number | undefined;
+        visible?: boolean | undefined;
+    }[] | undefined;
+    env?: {
+        name: string;
+        describes: {
+            en: string;
+            pl: string;
+        };
+        requirement: {
+            kind: "required";
+        } | {
+            kind: "requiredWhen";
+            input: string;
+            equals: string;
+        } | {
+            kind: "optional";
+            without: {
+                en: string;
+                pl: string;
+            };
+        };
+        secret: boolean;
+        generable: boolean;
+        owner: {
+            kind: "platform";
+        } | {
+            kind: "application";
+            application: "admin" | "backend" | "storefront";
+        } | {
+            kind: "module";
+            moduleId: string;
+        };
+        consumers: ("admin" | "backend" | "storefront")[];
+        addressOf: "admin" | "backend" | "storefront" | null;
+    }[] | undefined;
+};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;CAwE3C,CAAC;AAEH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCnB,CAAC"}

package/dist/manifest.js

@@ -0,0 +1,117 @@
+import { defineModuleManifest, defineModuleSettingsManifest } from '@endora-commerce/contracts';
+import { GOOGLE_TAG_MANAGER_SETTING_CODES } from '@endora-commerce/contracts';
+/**
+ * Google Tag Manager module (feature 066). Puts the operator's GTM container on
+ * the storefront per sales channel, publishes a documented commerce `dataLayer`
+ * vocabulary for their tags to trigger on, and optionally relays the
+ * relay-eligible subset of those events to their server-side container.
+ *
+ * The module owns no table and no admin page: every tag, trigger and variable
+ * lives in the GTM console, and the six values below are managed on the generic
+ * Settings screen (research §§R2-R3). Consequently it declares no permission
+ * codes — the one palette action references the core `settings:read` code.
+ */
+export const googleTagManagerSettingsManifest = defineModuleSettingsManifest({
+    moduleCode: 'google_tag_manager',
+    groups: [{ code: 'google_tag_manager', name: 'Google Tag Manager' }],
+    settings: [
+        {
+            // Feature 073 — the operator's activation control. Platform-wide, and
+            // deliberately not `google_tag_manager.enabled`: that code already exists
+            // and is per-sales-channel, answering "does the container load on this
+            // storefront". This one answers "does this client have GTM at all".
+            code: 'google_tag_manager.module_enabled',
+            name: 'Google Tag Manager module enabled',
+            description: 'Switches the Google Tag Manager container injection and the server-side relay on or off for the whole platform. Separate from the per-channel switch, which decides where the container actually loads. Nothing is dropped: every setting keeps its value.',
+            groupCode: 'google_tag_manager',
+            valueType: 'boolean',
+            defaultValue: true,
+        },
+        {
+            code: GOOGLE_TAG_MANAGER_SETTING_CODES.ENABLED,
+            name: 'Enable Google Tag Manager',
+            description: 'Master switch for the module. Per-channel overridable. If your container also contains a GA4 tag, do not enable the platform\'s Google Analytics module for the same channel: both would report the same actions and every metric would be doubled.',
+            groupCode: 'google_tag_manager',
+            valueType: 'boolean',
+            defaultValue: false,
+        },
+        {
+            code: GOOGLE_TAG_MANAGER_SETTING_CODES.CONTAINER_ID,
+            name: 'Container ID',
+            description: 'GTM container ID (GTM-XXXXXXX) from the Google Tag Manager console. Blank means the channel is untracked.',
+            groupCode: 'google_tag_manager',
+            valueType: 'string',
+            defaultValue: '',
+        },
+        {
+            code: GOOGLE_TAG_MANAGER_SETTING_CODES.REQUIRE_CONSENT,
+            name: 'Require analytics consent',
+            description: 'When enabled, the container starts with Consent Mode v2 set to denied and the platform sends no events until the visitor accepts the cookie banner. Consent Mode governs Google tags automatically; a non-Google tag in your container fires unless you add an additional consent check to it.',
+            groupCode: 'google_tag_manager',
+            valueType: 'boolean',
+            defaultValue: true,
+        },
+        {
+            code: GOOGLE_TAG_MANAGER_SETTING_CODES.SERVER_SIDE_ENABLED,
+            name: 'Server-side tagging',
+            description: 'Deliver the platform\'s commerce events to your server-side GTM container from the backend instead of the browser. This moves those events out of the web container: tags that trigger on them must exist in the server container. Triggers configured inside the web container (scroll, clicks, visibility, forms) are unaffected.',
+            groupCode: 'google_tag_manager',
+            valueType: 'boolean',
+            defaultValue: false,
+        },
+        {
+            code: GOOGLE_TAG_MANAGER_SETTING_CODES.SERVER_CONTAINER_URL,
+            name: 'Server container URL',
+            description: 'Base URL of your server-side GTM container, e.g. https://sgtm.example.com. Blank keeps the channel on the browser path even when server-side tagging is on.',
+            groupCode: 'google_tag_manager',
+            valueType: 'string',
+            defaultValue: '',
+        },
+        {
+            code: GOOGLE_TAG_MANAGER_SETTING_CODES.SERVER_INGEST_PATH,
+            name: 'Server container ingest path',
+            description: "Request path your server container's client listens on. Default /data matches Google's Data Client; change it only if your container uses a custom client.",
+            groupCode: 'google_tag_manager',
+            valueType: 'string',
+            defaultValue: '/data',
+        },
+    ],
+});
+export const manifest = defineModuleManifest({
+    id: 'google_tag_manager',
+    name: 'Google Tag Manager',
+    description: 'Google Tag Manager integration: per-sales-channel container injection behind the storefront consent decision, a documented commerce dataLayer vocabulary, and an optional server-side tagging relay.',
+    version: '1.0.0',
+    dependencies: ['sales_channels', 'settings'],
+    settings: googleTagManagerSettingsManifest,
+    i18n: { bundlesDir: 'i18n' },
+    docs: { dir: 'docs' },
+    actions: [
+        {
+            id: 'open-google-tag-manager',
+            labelKey: 'actions.openGoogleTagManager.label',
+            descriptionKey: 'actions.openGoogleTagManager.description',
+            icon: 'Settings',
+            // The module has no page of its own — its settings group lives on the
+            // generic Settings screen, which has a search box (research §R3).
+            targetRoute: '/settings',
+            // Core catalogue code, referenced rather than re-declared: this module
+            // owns no permission of its own.
+            requiredPermission: 'settings:read',
+            keywords: [
+                'gtm',
+                'google',
+                'tag',
+                'manager',
+                'container',
+                'datalayer',
+                'sgtm',
+                'tagi',
+                'kontener',
+            ],
+            weight: 246,
+        },
+    ],
+    activation: { settingCode: 'google_tag_manager.module_enabled', default: true },
+});
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"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"}

package/docs/google-tag-manager.md

@@ -0,0 +1,228 @@
+---
+title: Google Tag Manager
+description: Google Tag Manager containers per sales channel, with a documented commerce dataLayer and an optional server-side relay
+---
+
+# Google Tag Manager
+
+The `google_tag_manager` module puts your **GTM container** on the storefront, one per
+sales channel, and publishes a documented commerce `dataLayer` vocabulary for your tags to trigger
+on. It can also relay those events from the platform's backend to your **server-side GTM container**.
+
+## What this module does, and what it does not
+
+Google Tag Manager is a *tag container*, not a measurement product. Every tag, trigger and variable
+lives in the Google Tag Manager console, outside this platform. So the module's job is narrow on
+purpose:
+
+**It does:**
+
+- load the right container on the right channel's storefront, behind the storefront's single consent
+  decision;
+- publish a stable, documented set of commerce events onto `window.dataLayer`;
+- optionally deliver the relay-eligible subset of those events to your server container, durably and
+  exactly once.
+
+**It does not:**
+
+- model, mirror or manage your tags, triggers or variables — those stay in the GTM console;
+- own a database table or an admin page of its own. Its whole configuration is six settings on the
+  generic Settings screen;
+- decide anything about which vendors your container talks to.
+
+## Configuration (Settings module)
+
+All values live in the **Google Tag Manager** settings group and are overridable per sales channel.
+
+| Setting | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `google_tag_manager.enabled` | boolean | `false` | Master switch for the channel. |
+| `google_tag_manager.container_id` | string | `''` | Container ID, `GTM-XXXXXXX`. Blank ⇒ the channel is untracked. |
+| `google_tag_manager.require_consent` | boolean | `true` | Start the container under Consent Mode v2 denied and send no platform events until the visitor accepts. |
+| `google_tag_manager.server_side_enabled` | boolean | `false` | Relay commerce events from the backend to your server container. |
+| `google_tag_manager.server_container_url` | string | `''` | Base URL of your server container, e.g. `https://sgtm.example.com`. |
+| `google_tag_manager.server_ingest_path` | string | `/data` | Request path your container's ingest client claims. |
+
+A channel is tracked only when the master switch is on **and** the container ID has the `GTM-…`
+shape. A blank or malformed ID means "not configured", never a broken script tag, so clearing it is
+a safe way to pause a channel. Configuration changes reach the storefront immediately — no redeploy,
+no cache wait.
+
+There is no admin page: six settings and no rows of its own means the generic Settings screen already
+does everything a bespoke page could. Under the command palette, "Google Tag Manager" lands there.
+
+## Double counting with the native Google Analytics module
+
+> **Do not run a GA4 tag inside your container *and* the platform's Google Analytics module on the
+> same channel.** Both report the same shopping actions, so every metric doubles.
+
+The platform cannot detect this: the GA4 tag lives in your container, where the platform has no
+visibility. It also does not enforce mutual exclusion — the two integrations stay independent
+switches and the choice is yours. Pick one measurement path per channel:
+
+- **GTM as the single path** — turn the platform's Google Analytics module off for the channel and
+  build your GA4 tag in the container. GTM tracking is unaffected by that switch.
+- **The native module as the single path** — keep GTM for everything that is not GA4.
+
+## Storefront behaviour
+
+The container loads with `next/script` on `afterInteractive`, so it never blocks the critical
+rendering path. The standard `<noscript>` iframe fallback is rendered too, so the container is
+reachable without JavaScript.
+
+### Consent
+
+Consent is the storefront's single decision, shared with Google Analytics, LinkedIn Ads and Meta
+Ads: one banner, one stored answer. The banner is shown whenever **any** enabled integration on the
+channel requires consent — including when Google Tag Manager is the only one enabled.
+
+With `Require analytics consent` on:
+
+1. before the container loads, the page publishes Consent Mode v2 defaults of `denied` for
+   `analytics_storage`, `ad_storage`, `ad_user_data` and `ad_personalization`;
+2. the container itself **is** loaded. A container is not a tag: withholding it would silently
+   disable every tag you built, including ones that never needed consent;
+3. the platform pushes **no events of its own** — no page views, no commerce events, no relay —
+   until the visitor accepts;
+4. accepting mid-session delivers a Consent Mode `update` to the container and starts the platform's
+   events flowing, with no page reload.
+
+> **Consent Mode governs Google tags, not everyone else's.** Google's own tags read the consent state
+> and withhold storage and identifiers automatically. A Meta, LinkedIn or custom HTML tag in your
+> container **fires regardless** unless you add an **additional consent check** to it in the GTM
+> console. The platform cannot see or enforce that — it is your obligation.
+
+## The event vocabulary
+
+Trigger your tags on these custom events. The `items` parameter is a **JSON string** using the GA4
+recommended item shape (`item_id`, `item_name`, `price`, `quantity`), because virtually every
+container maps it to a GA4 tag.
+
+| Event | Parameters | Relay-eligible |
+| --- | --- | --- |
+| `page_view` | `page_path`, `page_location`, `page_title` | yes |
+| `view_search_results` | `search_term` | yes |
+| `view_item` | `currency`, `value`, `items` | yes |
+| `add_to_cart` | `currency`, `value`, `items` | yes |
+| `add_to_quote_request` | `currency`, `value`, `items` | yes |
+| `add_to_shopping_list` | `items` | yes |
+| `begin_checkout` | `currency`, `value`, `items` | yes |
+| `place_order_clicked` | the checkout submission fields | yes |
+| `purchase` | `transaction_id`, `value`, `currency`, `items` | yes |
+| `contact_form_submitted` | the contact-form field values | yes |
+
+Event payloads carry scalar values only, so an uploaded file or attachment can never appear in one.
+
+> **Trigger `page_view`, not History Change.** The storefront pushes exactly one `page_view` per
+> destination, including navigations that do not reload the document. If your container also uses
+> GTM's built-in History Change trigger you will count every navigation twice.
+
+### Client-only events
+
+These are **not** published by the platform and have no server-side path, by design:
+
+| Trigger | Why the platform cannot reconstruct it |
+| --- | --- |
+| Scroll depth | Depends on viewport size and live scroll position. |
+| Outbound link clicks | Needs the clicked element and the live DOM. |
+| File downloads | Needs the clicked link's href and text. |
+| `form_start` / `form_submit` | DOM interaction timing; `form_start` has no server-observable moment at all. |
+| Element visibility | `IntersectionObserver` state, internal to the container. |
+| Timers | Wall-clock dwell time in the browser session. |
+| `gtm.js`, `gtm.dom`, `gtm.load`, history change | Generated by the container itself. |
+
+There is nothing to configure here, and nothing is lost: the container stays loaded in the browser
+even when server-side tagging is on, so its own triggers keep handling all of them. The backend
+ingest rejects any event name outside the relay-eligible list, so a crafted request cannot give a
+client-only event a server path either.
+
+## Server-side tagging
+
+With `Server-side tagging` on and a server container URL configured, the ten events above stop being
+pushed to the browser `dataLayer` and are delivered from the platform's backend instead. Each
+logical event is reported exactly once — never both ways.
+
+> **This *moves* those events out of the web container.** Tags that triggered on them in the web
+> container must be rebuilt in the **server** container. Everything configured inside the web
+> container that observes the browser — scroll depth, link clicks, file downloads, form interaction,
+> element visibility, timers — is unaffected and keeps firing.
+
+A blank `Server container URL` keeps the channel on the browser path even with the switch on, so
+turning the switch on first is harmless.
+
+### How delivery works
+
+The storefront posts to `POST /api/v1/storefront/google-tag-manager/collect`, which is a **pure
+producer**: it validates the batch and enqueues one job per event onto the durable BullMQ queue
+`google_tag_manager.ss.relay`, then answers `202`. No outbound call happens inside the shopper's
+request, so a slow or failing container can never affect the shop.
+
+A separable worker (co-located in the API process unless `BACKEND_ROLE=api`, in which case only the
+`worker` process runs it) posts each event to your container and retries on failure: eight attempts
+with exponential backoff from one second. Exhausted deliveries are retained as failed jobs so they
+are observable rather than silently dropped.
+
+### The request your container receives
+
+```
+POST {server_container_url}{server_ingest_path}
+Content-Type: application/json
+```
+
+```json
+{
+  "event_name": "purchase",
+  "client_id": "1234567890.1754006400",
+  "event_id": "6b1f0ec4-0000-4000-8000-000000000001",
+  "page_location": "https://shop.example.com/checkout/thank-you",
+  "page_referrer": "https://shop.example.com/checkout",
+  "page_title": "Thank you",
+  "language": "pl",
+  "consent": { "analytics_storage": "granted" },
+  "ip_override": "203.0.113.7",
+  "user_agent": "Mozilla/5.0 ...",
+  "transaction_id": "ORD-2026-000123",
+  "value": 1249.0,
+  "currency": "PLN",
+  "items": "[{\"item_id\":\"SKU-9\",\"item_name\":\"Widget 9\",\"price\":249,\"quantity\":5}]",
+  "gtm_event_id": "6b1f0ec4-0000-4000-8000-000000000001"
+}
+```
+
+The event's own parameters are flattened at the top level. `client_id`, `ip_override` and
+`user_agent` deliberately reuse the GA4 Measurement Protocol field names, which server-side GTM's
+clients already recognise, so you write no translation layer. No credentials are sent: an sGTM
+ingest endpoint is a public collection endpoint by design.
+
+### What you have to do on your side
+
+1. **Claim the configured request path.** Google's **Data Client** claims `/data` by default; a
+   custom client can claim any path, in which case set `Server container ingest path` to match.
+2. **Rebuild the tags** that triggered on the platform's commerce events, in the server container.
+   Those events no longer reach the web container.
+3. **Parse `items` as JSON** — it arrives as a string, not an array.
+4. **Deduplicate on `event_id`** (also present as `gtm_event_id`). It is stable across retries, so a
+   redelivery carries the same value.
+5. **Handle a missing IP and user agent.** When the visitor denied consent, `ip_override` and
+   `user_agent` are omitted entirely, so geo and device enrichment is not always possible.
+
+### What the relay never carries
+
+Only the documented commerce parameters, page context, client id, consent state and event id. No
+`user_id`, no e-mail address, no organization id, no postal address, no hashed identifiers, and
+never a file attachment. Enhanced conversions and user-id stitching are deliberately out of scope —
+add whatever your container needs, in your container.
+
+## Permissions
+
+The module declares **no permission codes of its own**. Its configuration is reached through the
+generic Settings screen and is therefore gated by the core `settings:read` / `settings:write`
+permissions, and audited by the Settings module.
+
+## Not yet implemented
+
+- **Serving `gtm.js` first-party from the server container.** Attractive for cookie lifetime and
+  ad-blocker resilience, but a mis-provisioned server container would turn a delivery setting into a
+  total tracking outage. It needs its own setting and its own acceptance test.
+- **`user_id` and enhanced conversions in the relay** — each needs its own consent and hashing
+  analysis.

package/i18n/en.json

@@ -0,0 +1,4 @@
+{
+  "actions.openGoogleTagManager.label": "Google Tag Manager",
+  "actions.openGoogleTagManager.description": "Configure the GTM container and server-side tagging per sales channel"
+}

package/i18n/pl.json

@@ -0,0 +1,4 @@
+{
+  "actions.openGoogleTagManager.label": "Google Tag Manager",
+  "actions.openGoogleTagManager.description": "Skonfiguruj kontener GTM i tagowanie server-side dla kanału sprzedaży"
+}