@buildinams/core 0.3.0 → 0.4.0

package/docs/analytics.md

@@ -0,0 +1,883 @@
+# Analytics
+
+One typed `track()` for every provider, gated by the visitor's consent.
+
+- **Three declarations:** the project declares its events in a catalog, each destination declares the events it accepts, and a mapping connects the two. A missing field or an unknown event is a compile error.
+- **Your events, your data:** [tracking](tracking.md) reports what happened (page views, clicks, product views, cart changes), with your own product data in it, e.g. `{ product, variant }`, and analytics tracks it under the same name. Mappings turn them into each provider's events, e.g. GA4's recommended ones for GTM.
+- **A readable catalog:** every event describes what it means, and `analytics.routes()` lists which destinations receive it.
+- **Consent first:** events are queued until consent is answered, then only reach the destinations the visitor allowed.
+- **Browser only:** `track()` on the server does nothing. A prerendered page delivers nothing until the visitor navigates to it.
+
+## Quick start
+
+### 1. Add tracking
+
+The markup watcher and cart changes report page views, product views, selections and cart changes, so most call sites need no `analytics.track()`. Your product, list, promotion and cart item types are declared here, on their plugins. Create them in a module without side effects, so server components can import `track()` without loading analytics:
+
+```ts
+// src/analytics/tracking.ts
+import { createCartChanges } from "@buildinams/core/tracking/cart";
+import {
+	createDomWatcher,
+	ecommerce,
+	pageViews,
+} from "@buildinams/core/tracking/dom";
+
+export type Item = { product: ProductFragment; variant?: VariantFragment };
+export type List = { id: string; name: string };
+export type Promotion = { id: string; name: string; slot?: string };
+
+export const domWatcher = createDomWatcher([
+	pageViews(),
+	ecommerce<{ item: Item; list: List; promotion: Promotion }>({
+		id: ({ product }) => product.id,
+	}),
+]);
+
+export const { track } = domWatcher;
+
+export const cartChanges = createCartChanges<Item>();
+```
+
+See [Tracking](tracking.md) for every plugin and how to mark elements.
+
+### 2. Declare your events
+
+One catalog with every event the project emits: what tracking reports, from the trackers' `events`, and your own. See [The catalog](#the-catalog).
+
+```ts
+// src/analytics/event-catalog.ts
+import { defineEvents, type EventsOf, shape } from "@buildinams/core/analytics";
+
+import { cartChanges, domWatcher } from "./tracking";
+
+export const events = defineEvents({
+	...domWatcher.events,
+	...cartChanges.events,
+	newsletterSignedUp: {
+		description: "The newsletter form was submitted successfully.",
+		payload: shape<{ source: "footer" | "popup" }>(),
+	},
+});
+
+export type Events = EventsOf<typeof events>;
+```
+
+### 3. Create the instance
+
+One module, imported wherever you track. Consent comes from your consent platform ([Consent](#consent)); each destination is mapped onto your events, then given the consent it requires ([Destinations and mappings](#destinations-and-mappings)). `sources` tracks what the trackers report, under the same name.
+
+```ts
+// src/analytics/index.ts
+import {
+	createAnalytics,
+	map,
+	mapEvery,
+	withConsent,
+} from "@buildinams/core/analytics";
+import {
+	toGa4CustomEvent,
+	ga4Mapping,
+	gtmDestination,
+} from "@buildinams/core/analytics/google";
+import { cookiebotConsent } from "@buildinams/core/consent/cookiebot";
+
+import { events, type Events } from "./event-catalog";
+import { cartChanges, domWatcher } from "./tracking";
+
+export const analytics = createAnalytics<Events>({
+	events,
+	consent: cookiebotConsent(),
+	sources: [domWatcher, cartChanges],
+	destinations: [
+		withConsent(
+			map(gtmDestination(), {
+				...mapEvery(events, toGa4CustomEvent),
+				...ga4Mapping<Events>({ item: toGa4Item }),
+			}),
+			"none",
+		),
+	],
+});
+```
+
+| Option           | Default      | What it does                                                                                                                                                                                                                                                             |
+| ---------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `events`         | —            | The catalog from `defineEvents()`.                                                                                                                                                                                                                                       |
+| `consent`        | —            | The consent source. Events are queued while it's unanswered.                                                                                                                                                                                                             |
+| `consentTargets` | `[]`         | Providers told every answer. See [Consent targets](#consent-targets).                                                                                                                                                                                                    |
+| `destinations`   | `[]`         | Where events go, each from `withConsent()`.                                                                                                                                                                                                                              |
+| `sources`        | `[]`         | Trackers whose events are tracked under the same name, e.g. `domWatcher`. See [Sources](#sources).                                                                                                                                                                       |
+| `context`        | `{}`         | Initial [context](#context) for every event.                                                                                                                                                                                                                             |
+| `delivery`       | `"deferred"` | `"deferred"` delivers after the next paint, so tracking in a click handler doesn't hurt INP; pending events go out straight away when the page is hidden or, with the Navigation API, before a client-side navigation. `"immediate"` delivers as tracked, e.g. in tests. |
+
+The instance has `track()`, `setContext()`, `routes()` ([Routes](#routes)) and `subscribe(listener)`, which receives every event as tracked, before consent and delivery, and returns an unsubscribe function.
+
+### 4. Track
+
+Mark elements, and track the rest from code:
+
+```tsx
+<main {...track({ pageView: { pageType: "product" } })}>
+
+analytics.track("newsletterSignedUp", { source: "footer" });
+```
+
+Names and payloads are typed by the catalog. Payloads whose fields are all optional can be left out. Payloads are copied with `structuredClone`, so keep them plain and lean: a fragment with what the mappings read, not the whole product. `track()` never throws: a payload it can't copy is logged and dropped.
+
+## Events
+
+### The catalog
+
+```ts
+export const events = defineEvents({
+	...domWatcher.events,
+	...cartChanges.events,
+	orderPlaced: {
+		description: "An order was placed, on the thank-you page. Once per order.",
+		payload: shape<{ order: OrderFragment }>(),
+	},
+	loggedOut: { description: "The visitor logged out from the account menu." },
+});
+```
+
+- **`defineEvents(catalog)`** returns the catalog as is, for `createAnalytics({ events })`. `EventsOf<typeof events>` is the `Events` type for `createAnalytics<Events>()`, `ga4Mapping<Events>()` and `shopifyMapping<Events>()`.
+- **`description`** is required: when the event is tracked and what it means, for developers, agents and analysts.
+- **`shape<T>()`** is the payload's type as a value, holding nothing at runtime. Leave `payload` out for events without fields.
+- **`domWatcher.events` and `cartChanges.events`** have an entry for exactly what the installed plugins and cart changes report, under the names they report it, typed with your data and fields as the plugins declare them.
+- **Names** are camelCase and past tense, like tracking's: `orderPlaced`, `loggedIn`, `newsletterSignedUp`. Mappings give each provider its own names.
+- **Only what's in it:** `track()` only takes catalog events, and mappings only have to cover them. In development, a name outside it, e.g. through a cast, logs a warning once.
+- **Extra fields** from markup are declared on the plugin, e.g. `clicks<{ cta: string }>()` adds `cta` to `clicked` and its catalog entry. For data from elsewhere, track the event yourself.
+
+### Sources
+
+`createAnalytics({ sources: [domWatcher, cartChanges] })` subscribes to each source in the browser, which starts it, and tracks what it reports under the same name.
+
+- **Type-checked:** every event a source reports must be in the catalog with a compatible payload, so spread its `events`.
+- **One instance per source:** a later `createAnalytics()` with the same source, e.g. when HMR re-runs the module, takes it over, so nothing is tracked twice.
+- **Your own names:** to track an occurrence under another name, [subscribe to the tracker yourself](tracking.md#subscribing) instead.
+- **Any `subscribe()`** works as a source: an `AnalyticsSource<Events>` reports `{ name, payload }` of catalog events.
+
+## Context
+
+Every event carries a `context`: `url`, `title` and `referrer`, plus session data you set. `setContext()` merges into it, and `undefined` clears a field. Each event copies the context when tracked, so queued events keep the values from when they happened.
+
+```ts
+createAnalytics<Events>({ /* … */ context: { locale: "nl-NL", market: "NL" } });
+
+// after login
+analytics.setContext({ user: { id: customer.id, type: "returning" } });
+
+// after logout
+analytics.setContext({ user: undefined });
+```
+
+| Field    | Type                             | What it is                                                                   |
+| -------- | -------------------------------- | ---------------------------------------------------------------------------- |
+| `user`   | `{ id?, email?, phone?, type? }` | The logged-in visitor. `phone` in E.164, `type` is `"new"` or `"returning"`. |
+| `locale` | `string`                         | BCP 47, e.g. `"nl-NL"`. Take it from the route, not `<html lang>`.           |
+| `market` | `string`                         | The storefront market (ISO 3166-1 alpha-2), not where the visitor is.        |
+
+Add fields, including user fields, with the second type argument. Don't redeclare a built-in one; an undeclared key is a compile error:
+
+```ts
+createAnalytics<
+	Events,
+	{ storefront?: "web" | "app"; user?: { loyaltyTier?: "silver" | "gold" } }
+>({ /* … */ context: { storefront: "web" } });
+```
+
+Destinations decide which fields they forward. Personal data (`email`, `phone`) should only leave the browser with marketing consent; the GTM destination checks this for you.
+
+**Page type** belongs to the page, not the session, so it's on `pageViewed`: `analytics.track("pageViewed", { pageType: "product" })`. Suggested values are `"home"`, `"collection"`, `"product"`, `"search"`, `"cart"`, `"checkout"`, `"account"` and `"content"`, but any string works. GTM remembers it for later events.
+
+## Destinations and mappings
+
+A destination accepts events in its provider's own vocabulary, each with a minimum shape. `map()` maps your events onto them, and returns a destination that accepts yours. `withConsent()` gives that the consent it requires, for `createAnalytics()`:
+
+```ts
+withConsent(
+	map(metaDestination(META_PIXEL_ID), {
+		pageViewed: () => ({ name: "PageView", payload: {} }),
+		addedToCart: ({ currency, value, items }) => ({
+			name: "AddToCart",
+			payload: {
+				content_ids: items.map(({ item }) => item.merchandise.id),
+				content_type: "product",
+				currency,
+				value,
+			},
+		}),
+		newsletterSignedUp: ({ source }) => ({
+			name: "Lead",
+			payload: { content_name: source },
+		}),
+	}),
+	["marketing"],
+);
+```
+
+- **Typed both ways:** each entry gets its event's payload and must return an event the destination accepts, with every required field.
+- **One, several or none:** return one event, an array, or `null`. The second argument has the event's `id`, `name` and `context`.
+- **`withConsent()`'s second argument** is mandatory: the consent categories that must all be granted, or `"none"` for providers that gate on consent themselves, like GTM with Consent Mode.
+- **Events without an entry** aren't sent; in development, creating analytics warns about catalog events no destination receives.
+- **`mapEvery(events, toEvent)`** has an entry for every catalog event, e.g. `mapEvery(events, toGa4CustomEvent)` for GTM. Spread it first, so the entries after it override it.
+- **Builders** map what tracking reports for a destination over adapters for your data: [`ga4Mapping()`](#ga4mapping) and [`shopifyMapping()`](#shopify). Spread one to extend or override it; an entry set to `undefined` sends nothing.
+- **Your own events, unmapped:** a destination typed by your `Events`, e.g. a log, skips `map()`: `withConsent(logDestination, "none")`.
+- **Outside `createAnalytics()`**, `map()` and `withConsent()` can't infer your events: annotate the result, `const meta: ConsentedDestination<Events> = withConsent(map(…), …)`.
+- **Mapped twice**, e.g. with two mappings and different consent, a destination is set up once and receives what both send.
+
+### Routes
+
+`analytics.routes()` lists, per catalog event, its description and the destinations that receive it, with the consent they wait for. Destinations are keyed by `name`, numbered when several share one (`gtm`, `gtm (2)`). It works on the server too, without consent.
+
+```ts
+analytics.routes();
+// {
+//   pageViewed: {
+//     description: "A page was shown: on load, after a client-side navigation, …",
+//     destinations: {
+//       gtm: { requires: "none" },
+//       shopify: { requires: ["analytics"] },
+//     },
+//   },
+//   newsletterSignedUp: {
+//     description: "The newsletter form was submitted successfully.",
+//     destinations: { gtm: { requires: "none" } },
+//   },
+// }
+```
+
+It's the project's tracking plan, read from the code. Snapshot it in a test, `expect(analytics.routes()).toMatchSnapshot()`, so changes to what reaches which provider show up in review, or print it as JSON for agents and analysts.
+
+## Consent
+
+Three categories, mapped onto what each provider expects. Strictly necessary storage is always allowed.
+
+| Category      | Google Consent Mode v2                             | Shopify Customer Privacy              | Meta Pixel       |
+| ------------- | -------------------------------------------------- | ------------------------------------- | ---------------- |
+| `preferences` | `functionality_storage`, `personalization_storage` | `preferences`                         | —                |
+| `analytics`   | `analytics_storage`                                | `analytics`                           | —                |
+| `marketing`   | `ad_storage`, `ad_user_data`, `ad_personalization` | `marketing`, read with `sale_of_data` | `grant`/`revoke` |
+
+1. **`requires: "none"`** destinations receive every event straight away; their callbacks get the current answer, `null` until there is one.
+2. **Destinations with categories** wait: their events are queued (the last 100) until the visitor answers.
+3. **On an answer**, every [consent target](#consent-targets) is told, then the queue flushes to the destinations now allowed. Repeated values are ignored.
+4. **After that**, events go straight to allowed destinations. One that loses consent receives nothing until it's granted again.
+
+### Consent platforms
+
+| Source                                        | Answered when                                                                    | Mapping                                                                      |
+| --------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `cookiebotConsent()` from `consent/cookiebot` | The visitor responds, or Cookiebot implies consent where it isn't required.      | `preferences`, `statistics` → `analytics`, `marketing`                       |
+| `oneTrustConsent()` from `consent/onetrust`   | The visitor closes the banner, or straight away where OneTrust doesn't show one. | Groups `C0003` → `preferences`, `C0002` → `analytics`, `C0004` → `marketing` |
+| `shopifyConsent()` from `consent/shopify`     | The visitor responds, or straight away where Shopify shows no banner.            | `preferences`, `analytics`, `marketing` only with `sale_of_data` too         |
+
+- **Load the platform's script yourself.** The source reads its global and listens to its events, so load order doesn't matter.
+- **OneTrust group ids** differ per setup; all listed groups must be active: `oneTrustConsent({ groups: { marketing: ["C0004", "C0005"] } })`.
+- **On the server**, sources report unanswered.
+- **Shopify's `marketing`** needs sale of data allowed too, as Shopify blocks pixels that count as a sale for visitors who opt out.
+
+### Consent targets
+
+A source decides consent; a target is told it ([ADR 009](decisions/009-analytics-consent-targets.md)), e.g. for Shopify's checkout, which reads it from the Customer Privacy API, or Google's tags, which read Consent Mode.
+
+```ts
+createAnalytics<Events>({
+	events,
+	consent: cookiebotConsent(),
+	consentTargets: [shopifyCustomerPrivacy()],
+	destinations: [
+		/* … */
+	],
+});
+```
+
+| Target                                            | Tells                                                                                       |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `shopifyCustomerPrivacy()` from `consent/shopify` | Shopify's Customer Privacy API, with `sale_of_data` from `saleOfData` (`false` by default). |
+| `googleConsentMode()` from `consent/google`       | Google Consent Mode v2. See [Consent Mode](#consent-mode).                                  |
+
+- **Every answer, first:** targets are told before destinations receive events under it. One that throws is logged; the others are still told.
+- **Never back to the source:** a target named like the source is skipped, so Shopify's separate sale of data opt-out isn't overwritten, and targets can stay listed when you switch platforms.
+
+A target is a `name` and `apply(consent)`, which may return a promise:
+
+```ts
+export const metaConsent: ConsentTarget = {
+	name: "meta",
+	apply: (consent) =>
+		window.fbq?.("consent", consent.marketing ? "grant" : "revoke"),
+};
+```
+
+### Writing a consent source
+
+A `ConsentSource` is `get()`, returning the answer or `null`, and `subscribe(listener)`:
+
+```ts
+export const myPlatformConsent: ConsentSource = {
+	get: () => {
+		const state = window.MyPlatform?.consent;
+		if (!state?.answered) return null;
+		return {
+			preferences: state.functional,
+			analytics: state.analytics,
+			marketing: state.ads,
+		};
+	},
+	subscribe: (listener) => {
+		const onChange = () => {
+			const consent = myPlatformConsent.get();
+			if (consent) listener(consent);
+		};
+		window.addEventListener("myplatform:consent", onChange);
+		return () => window.removeEventListener("myplatform:consent", onChange);
+	},
+};
+```
+
+Only call `listener` with answered consent; repeats are fine. Give it a `name` when a target exists for the same platform.
+
+## Google Tag Manager
+
+`gtmDestination({ dataLayerName })` from `@buildinams/core/analytics/google` pushes events to `window.dataLayer`, as in [Quick start](#3-create-the-instance). Load GTM itself in the root layout, e.g. with `<GoogleTagManager />` from `@next/third-parties/google`, after the consent platform's script. In the container, fire the GA4 tag on the custom `page_view` event and turn off GA4's own page views, outbound clicks and scrolls (`send_page_view: false`, Enhanced Measurement), or they're counted twice.
+
+It accepts (`GtmEvents`) every GA4 event in GA4's own params, and `custom` for any other name. Ecommerce events are pushed with their params under `ecommerce`, after a `{ ecommerce: null }` reset; others at the top level, and `custom` as `{ event, ...params }`. Each push has `event_id` and the context as variables: `user_id`, `user_type`, `language`, `market`, your own fields in snake_case, and `user_data` with email and phone only with marketing consent.
+
+### `ga4Mapping()`
+
+`ga4Mapping<Events>(adapters)` maps what tracking reports to [GA4's recommended events](https://developers.google.com/analytics/devguides/collection/ga4/reference/events), with snake_case params:
+
+| Occurrence                                          | GA4 event                                         |
+| --------------------------------------------------- | ------------------------------------------------- |
+| `pageViewed`, `clicked`, `scrolled`                 | `page_view`, `click`, `scroll`                    |
+| `videoStarted`, `videoProgressed`, `videoCompleted` | `video_start`, `video_progress`, `video_complete` |
+| `formStarted`, `formSubmitted`                      | `form_start`, `form_submit`                       |
+| `itemViewed`, `itemSelected`, `itemsViewed`         | `view_item`, `select_item`, `view_item_list`      |
+| `promotionViewed`, `promotionSelected`              | `view_promotion`, `select_promotion`              |
+| `addedToCart`, `removedFromCart`                    | `add_to_cart`, `remove_from_cart`                 |
+
+`page_view` has `page_location`, `page_path`, `page_title`, `page_referrer` and `page_type`. The ecommerce and cart events carry your data, so they need adapters:
+
+| Adapter     | Type                                     | Maps                                                                                                                   |
+| ----------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `item`      | `(item) => Ga4Item`                      | The ecommerce events. Placed items get `index`, and the list's and promotion's params.                                 |
+| `list`      | `(list) => Ga4List`                      | `item_list_id` and `item_list_name`.                                                                                   |
+| `promotion` | `(promotion) => Ga4Promotion`            | `promotion_id`, `promotion_name`, `creative_name` and `creative_slot`.                                                 |
+| `currency`  | `(item, context) => string \| undefined` | `currency` on `itemViewed` → `view_item`, with `value` as `price` × `quantity` (default 1).                            |
+| `cartItem`  | `(item) => Ga4Item`                      | `addedToCart` → `add_to_cart` and `removedFromCart` → `remove_from_cart`, with `price` and `quantity` from the change. |
+
+`cartItem` defaults to `item` when the cart item type is assignable to the item type; otherwise it's required alongside `item`.
+
+```ts
+const toGa4Item = ({ product, variant }: Item): Ga4Item => ({
+	item_id: product.id,
+	item_name: product.title,
+	item_brand: product.vendor,
+	item_variant: variant?.title,
+	price: Number((variant?.price ?? product.priceRange.minVariantPrice).amount),
+});
+
+ga4Mapping<Events>({
+	item: toGa4Item,
+	cartItem: ({ merchandise }: ShopifyStorefrontCartLine) => ({
+		item_id: merchandise.product.id,
+		item_name: merchandise.product.title,
+		item_variant: merchandise.title,
+	}),
+	currency: ({ product, variant }) =>
+		(variant?.price ?? product.priceRange.minVariantPrice).currencyCode,
+	list: ({ id, name }) => ({ item_list_id: id, item_list_name: name }),
+	promotion: ({ id, name, slot }) => ({
+		promotion_id: id,
+		promotion_name: name,
+		creative_slot: slot,
+	}),
+});
+```
+
+- **Same `item_id` everywhere:** `item` and `cartItem` should give a product the same id, so reports can join views, adds and purchases.
+- **Without an adapter**, its events aren't mapped.
+- **`toGa4CustomEvent`**, through `mapEvery()`, sends every other event under its own name and params in snake_case, e.g. `newsletterSignedUp` as `newsletter_signed_up`. It drops ecommerce events with a development warning, as GA4 would read them with an earlier event's `ecommerce`.
+
+### Consent Mode
+
+Cookiebot and OneTrust set up [Google Consent Mode](https://developers.google.com/tag-platform/security/guides/consent) through their own integration; the destination doesn't send consent itself. `requires` picks Google's setup:
+
+| `requires`      | Setup    | GTM receives events                                                                           |
+| --------------- | -------- | --------------------------------------------------------------------------------------------- |
+| `"none"`        | Advanced | Straight away. Consent Mode gates tags in the container, and Google models visitors who deny. |
+| `["analytics"]` | Basic    | Only with analytics consent. Use it when the container has tags that ignore Consent Mode.     |
+
+For platforms without that integration, like Shopify's, add the `googleConsentMode({ dataLayerName, waitForUpdate })` target. Created before GTM loads, it sends every category denied (with `wait_for_update: 500`), then an update for every answer.
+
+### Adjusting what GTM receives
+
+Spread `ga4Mapping()` to map your own events, or override and drop its entries. Return GA4's params as GA4 names them:
+
+```ts
+withConsent(
+	map(gtmDestination(), {
+		...mapEvery(events, toGa4CustomEvent),
+		...ga4Mapping<Events>({ item: toGa4Item }),
+		orderPlaced: ({ order }) => ({
+			name: "purchase",
+			payload: {
+				transaction_id: order.name,
+				currency: order.totalPrice.currencyCode,
+				value: Number(order.totalPrice.amount),
+				items: order.lineItems.map(toGa4OrderItem),
+			},
+		}),
+		productListViewed: ({ list, products }) => ({
+			name: "view_item_list",
+			payload: {
+				item_list_id: list?.id,
+				item_list_name: list?.name,
+				items: products.map(toGa4Item),
+			},
+		}),
+		// The container's trigger listens for another name.
+		newsletterSignedUp: ({ source }) => ({
+			name: "custom",
+			payload: { event: "newsletter", params: { form_location: source } },
+		}),
+		formStarted: () => null,
+	}),
+	"none",
+);
+```
+
+## Shopify
+
+`shopifyDestination()` from `@buildinams/core/analytics/shopify` publishes to Hydrogen's analytics bus (`window.Shopify.analytics`), which `<ShopifyScripts>` from `@shopify/hydrogen/react` sets up and sends to Shopify Analytics, as in [vercel/shop](https://github.com/vercel/shop). Your project installs Hydrogen. For Liquid themes, see [Shopify Liquid themes](#shopify-liquid-themes).
+
+```ts
+// src/analytics/index.ts
+export const customerPrivacy = shopifyCustomerPrivacy();
+
+const toShopifyProduct = ({ product, variant }: Item): ShopifyProduct | null =>
+	variant
+		? {
+				id: product.id,
+				title: product.title,
+				vendor: product.vendor,
+				productType: product.productType,
+				variantId: variant.id,
+				variantTitle: variant.title,
+				price: variant.price,
+				quantity: 1,
+			}
+		: null;
+
+export const analytics = createAnalytics<Events>({
+	events,
+	consent: cookiebotConsent(),
+	consentTargets: [customerPrivacy],
+	destinations: [
+		/* GTM, … */
+		withConsent(
+			map(
+				shopifyDestination(),
+				shopifyMapping<Events>({
+					product: toShopifyProduct,
+					cartProduct: toStorefrontCartProduct,
+					getCartId: () => cartStore.get()?.id,
+				}),
+			),
+			["analytics"],
+		),
+	],
+});
+```
+
+```tsx
+// src/components/shopify-analytics.tsx, rendered in the root layout
+"use client";
+
+import { ShopifyScripts } from "@shopify/hydrogen/react";
+
+import { customerPrivacy } from "@/analytics";
+
+export const ShopifyAnalytics = () => (
+	<ShopifyScripts
+		analytics={{ channel: "headless" }}
+		consent={{ mode: "custom-banner", setup: customerPrivacy.syncConsent }}
+		shop={{
+			myshopifyDomain: process.env.NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN!,
+			// The numeric shop id, not the storefront id.
+			shopId: process.env.NEXT_PUBLIC_SHOPIFY_SHOP_ID!,
+		}}
+		i18n={{ country: "NL", language: "NL" }}
+		shopifyAnalytics
+	/>
+);
+```
+
+The Customer Privacy API also needs Hydrogen's same-origin Storefront API proxy (`handleShopifyRoutes` in `proxy.ts`).
+
+| `shopifyMapping()` option | What it does                                                                                                                               |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `product`                 | Your item as a `ShopifyProduct`, or `null` to leave it out. `itemViewed` only reaches Shopify with it.                                     |
+| `cartProduct`             | Your cart item as a `ShopifyProduct` without `price` and `quantity`. `toStorefrontCartProduct` does this for `toStorefrontCartSnapshot()`. |
+| `getCartId`               | The current cart's GID, read on delivery. `addedToCart` only reaches Shopify with it and `cartProduct`.                                    |
+
+### Consent
+
+Give it `withConsent(…, ["analytics"])`: Hydrogen's bus only delivers with analytics consent anyway. Consent comes from one of two places:
+
+- **Your consent platform** (Cookiebot, OneTrust), as above, through the `shopifyCustomerPrivacy()` target, also for checkout. `saleOfData` is a boolean or a function, e.g. `(consent) => consent.marketing`. Its `syncConsent` is the `setup` for Hydrogen's `"custom-banner"` mode, and releases Hydrogen's bus once Shopify has an answer.
+- **Shopify's own banner**: `consent: shopifyConsent()`, `consentTargets: [shopifyCustomerPrivacy(), googleConsentMode()]`, and `<ShopifyScripts consent={{ mode: "default-banner" }} />`. The Shopify target is then skipped, so it can stay listed, and `syncConsent` isn't needed: as a setup it would wait forever (in development it warns after 10 seconds). Shopify's banner has no Consent Mode integration on a headless storefront, hence `googleConsentMode()`. It decides per region whether to show, is styled in the Shopify admin, and has no IAB TCF support.
+
+### Events
+
+| Event         | Published as            | Notes                                                                                                                                           |
+| ------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pageViewed`  | `page_viewed`           | Shopify skips it on product, collection and search pages, which send their own.                                                                 |
+| `itemViewed`  | `product_viewed`        | With `product`.                                                                                                                                 |
+| `addedToCart` | `product_added_to_cart` | One per changed line, with the quantity added. Leave `getCartId` out when Hydrogen's `useCartAnalytics()` tracks the cart, or adds count twice. |
+
+Shopify's script drops products without `id`, `title`, `vendor`, `variantId` or `price.amount`, so incomplete products are left out with a development warning; numeric ids become GIDs. Events delivered before `<ShopifyScripts>` sets up the bus are held (at most 100, for 30 seconds after each).
+
+`ShopifyEvents` also has `search_viewed`, `collection_viewed` and Hydrogen's cart events. Spread the mapping to add them:
+
+```ts
+withConsent(
+	map(shopifyDestination(), {
+		...shopifyMapping<Events>({ product, cartProduct, getCartId }),
+		searched: ({ term }, { context }) => ({
+			name: "search_viewed",
+			payload: { url: context.url, searchTerm: term },
+		}),
+		collectionViewed: (collection, { context }) => ({
+			name: "collection_viewed",
+			payload: { url: context.url, collection },
+		}),
+	}),
+	["analytics"],
+);
+```
+
+## URLs and personal data
+
+URLs can carry tokens, order keys or emails, and every event has the page URL in `context.url`. Analytics doesn't clean them, as the parameters differ per project and tags read the page URL themselves anyway. Instead:
+
+1. **Don't track links with tokens:** leave them out of auto-tracked areas, or wrap them in `track({ auto: false })`.
+2. **Turn on GA4's data redaction** (Admin → Data streams → Redact data) for emails and parameters like `token`, `key` and `email`. Keep `utm_*` and `gclid` off the list.
+3. **Clean what GTM receives**, when other tags need it too, by wrapping the destination's subscriptions:
+
+```ts
+const SENSITIVE_PARAMS = ["token", "key", "email"];
+const URL_KEYS = [
+	"page_location",
+	"page_referrer",
+	"url",
+	"video_url",
+	"form_destination",
+];
+
+const redact = (params: Record<string, unknown>) => {
+	for (const key of URL_KEYS) {
+		const value = params[key];
+		if (typeof value !== "string" || !value) continue;
+		const url = new URL(value, window.location.href);
+		SENSITIVE_PARAMS.forEach((param) => url.searchParams.delete(param));
+		params[key] = url.href;
+	}
+	// `custom` events hold theirs under `params`.
+	if (params.params) redact(params.params as Record<string, unknown>);
+};
+
+const gtm = gtmDestination();
+
+withConsent(
+	map(
+		{
+			...gtm,
+			setup: ({ subscribe }) =>
+				gtm.setup({
+					subscribe: (event, callback) =>
+						subscribe(event, (payload, context) => {
+							redact(payload as Record<string, unknown>);
+							callback(payload, context);
+						}),
+				}),
+		},
+		{
+			...mapEvery(events, toGa4CustomEvent),
+			...ga4Mapping<Events>({ item: toGa4Item }),
+		},
+	),
+	"none",
+);
+```
+
+This only changes the dataLayer: tags that read the page URL themselves still see the original.
+
+## Writing a destination
+
+A destination is typed by the events it accepts, shaped like Hydrogen's `StorefrontAnalyticsDestination`:
+
+```ts
+type ConsoleEvents = {
+	view: { path: string };
+	order: { id: string; total: number };
+};
+
+export const consoleDestination: AnalyticsDestination<ConsoleEvents> = {
+	name: "console",
+	setup: ({ subscribe }) => {
+		subscribe("view", ({ path }) => console.log("view", path));
+		subscribe("order", (order, { id, context, consent }) => {
+			console.log("order", order.total, id, context, consent);
+		});
+	},
+};
+```
+
+- **`name`** prefixes its errors and warnings.
+- **`setup`** runs once in the browser, before consent. Subscribe to every event it accepts, and list them in `events` if it takes your own events without `map()`, so `routes()` knows them; in development, a mapping that sends an unsubscribed event warns. Don't load the provider's script here, but with the first event, which only arrives once allowed. It can be async; events wait for it.
+- **Callbacks** get the payload and `{ id, context, consent }`. `id` is unique per event, so providers with server-side events (Meta CAPI, GA4 Measurement Protocol) can dedupe.
+- **What it accepts is a minimum:** required fields are what the provider needs. Keep open shapes, like GTM's `Record<string, unknown>`, for providers that take anything.
+- **Consent is set with `withConsent()`**, so name the categories it needs in its docs. Telling the provider consent is a [consent target](#consent-targets)'s job.
+- **Ship a builder**, like `ga4Mapping()`, generic over `Events` with adapters typed from it, e.g. `Events["itemViewed"]["item"]`, returning `AnalyticsMapping<Events, YourEvents>`. A one-project destination can type its mapping by `Events` directly.
+- **Errors are isolated:** a failing `setup` is logged and the destination receives nothing; a failing callback is logged and the others still run.
+
+## Recipes
+
+### Next.js App Router
+
+```
+src/
+  analytics/event-catalog.ts  events = defineEvents({ … }), Events = EventsOf<typeof events>
+  analytics/tracking.ts       domWatcher = createDomWatcher([…]), { track } = domWatcher,
+                              cartChanges = createCartChanges<CartItem>()
+  analytics/index.ts          analytics = createAnalytics<Events>({ …, sources: [domWatcher, cartChanges] })
+  app/layout.tsx              the consent platform's script, <GoogleTagManager />
+  app/**/page.tsx             <main {...track({ pageView: { pageType: "…" } })}>
+```
+
+Server and client components import `track()` and `cartChanges` from `analytics/tracking.ts`; only client components import `analytics/index.ts`. As `createAnalytics()` starts the trackers, a client component every page renders, e.g. in the layout, must import it.
+
+### Multi-page sites
+
+Analytics needs no framework, so it also runs on sites whose server renders every page and links load them in full, e.g. a CMS's templates. Bundle the same modules into one script, e.g. with Vite or esbuild:
+
+```
+src/analytics/
+  event-catalog.ts   as in Next.js
+  tracking.ts        as in Next.js
+  index.ts           analytics, <track-data>, the cart, bundled to analytics.js
+templates/
+  layout             the consent platform's script, GTM, the starting cart, <script src="/analytics.js" defer>
+  pages, partials    page views and clicks as attributes; products, lists and promotions in <track-data>
+```
+
+**Attribute types** are written as attributes, e.g. on each page's root, the header and the footer:
+
+```html
+<header data-track="auto-links location" data-track-name="header">…</header>
+<main data-track="page-view auto-links" data-track-page-type="product">…</main>
+```
+
+**Data types** need a `ref`, so the server renders the data as JSON and a custom element sets it. Markup replaced later, e.g. by a partial reload or infinite scroll, sets its own when connected:
+
+```html
+<track-data type="list">
+	<script type="application/json">
+		{ "id": "summer", "name": "Summer" }
+	</script>
+	<ul>
+		<li>
+			<track-data type="item">
+				<script type="application/json">
+					{
+						"id": "tee",
+						"title": "Tee",
+						"variant": "M",
+						"price": 29.95,
+						"currency": "EUR"
+					}
+				</script>
+				<!-- the product card -->
+			</track-data>
+		</li>
+	</ul>
+</track-data>
+```
+
+```ts
+// src/analytics/index.ts
+const refs = {
+	"view-item": (data: Item) => track({ viewItem: data }).ref,
+	item: (data: Item) => track({ item: data }).ref,
+	list: (data: List) => track({ list: data }).ref,
+	promotion: (data: Promotion) => track({ promotion: data }).ref,
+};
+
+customElements.define(
+	"track-data",
+	class extends HTMLElement {
+		connectedCallback() {
+			const type = this.getAttribute("type") as keyof typeof refs;
+			const json = this.querySelector(
+				":scope > script[type='application/json']",
+			);
+			if (refs[type] && json?.textContent) {
+				refs[type](JSON.parse(json.textContent))(this);
+			}
+		}
+	},
+);
+```
+
+- **Give it a box:** `track-data { display: block; }`, as custom elements are inline and product views need a box.
+- **Escape the JSON** as your template language does for `<script>` content, so a `</script>` in a product name can't end it.
+- **Keep the JSON lean:** what the mappings read, not the whole product.
+- **Variant pickers** that swap the variant without re-rendering the `view-item` element leave its JSON on the first variant: re-render it, or set the new data with `refs["view-item"](data)(element)`.
+- **Placement across pages:** a product page loaded from a list card gets the card's list and index from the tab's `sessionStorage` ([Placement](tracking.md#behaviour)), as long as `ecommerce()`'s `id` gives both the same id.
+
+**The cart:** render the cart the page starts with, then pass `cartChanges` every cart the server confirms after a change, as a [`CartSnapshot`](tracking.md#cart):
+
+```html
+<script type="application/json" id="analytics-cart">
+	{ "id": "…", "currency": "EUR", "lines": [ … ] }
+</script>
+```
+
+```ts
+const starting = document.getElementById("analytics-cart")?.textContent;
+if (starting) cartChanges.setCart(JSON.parse(starting));
+
+// Wherever the site's cart code receives the updated cart, with your own `toCartSnapshot()`.
+cartChanges.setCart(toCartSnapshot(await response.json()));
+```
+
+A form that adds to the cart and redirects needs nothing more: the next page's starting cart differs from the one stored.
+
+**Keep in mind:**
+
+- **Events waiting for consent** are kept in memory, so those of a page the visitor leaves before answering the banner are lost.
+- **Load GTM after the consent platform**, as in Next.js. With the `googleConsentMode()` target, load GTM from the bundle after `createAnalytics()`, so the denied defaults come first.
+
+#### Shopify Liquid themes
+
+On a Liquid theme, Shopify's defaults are usually enough, without this library: Shopify sends its standard events (page, product, cart and checkout) to Shopify Analytics and to web pixels itself, and the [Google & YouTube sales channel](https://apps.shopify.com/google) sends them to GA4 as ecommerce events, purchases included, respecting the visitor's consent. Turn on its GA4 connection rather than tracking the same events from GTM, or GA4 counts them twice.
+
+### Ecommerce flow
+
+`track()` on lists, items and the product page covers views and selections, and `createCartChanges()` adds and removes. The rest is your own events:
+
+```ts
+export const events = defineEvents({
+	...domWatcher.events,
+	...cartChanges.events,
+	checkoutStarted: {
+		description: "The checkout page was opened with the cart's lines.",
+		payload: shape<{ cart: CartFragment }>(),
+	},
+	orderPlaced: {
+		description: "An order was placed, on the thank-you page. Once per order.",
+		payload: shape<{ order: OrderFragment }>(),
+	},
+});
+```
+
+- **Purchases count once:** a reload of the thank-you page tracks again, so remember the order id, e.g. in `sessionStorage`.
+
+### A Meta Pixel destination
+
+```ts
+// src/analytics/meta-destination.ts
+type Fbq = ((...args: unknown[]) => void) & { queue?: unknown[] };
+declare global {
+	interface Window {
+		fbq?: Fbq;
+	}
+}
+
+const loadPixel = () => {
+	const queue: unknown[] = [];
+	const fbq: Fbq = (...args) => queue.push(args);
+	fbq.queue = queue;
+	window.fbq = fbq;
+	const script = document.createElement("script");
+	script.async = true;
+	script.src = "https://connect.facebook.net/en_US/fbevents.js";
+	document.head.append(script);
+};
+
+type Content = {
+	content_ids: string[];
+	content_type: "product";
+	currency: string;
+	value: number;
+};
+
+export type MetaEvents = {
+	PageView: Record<never, never>;
+	ViewContent: Content;
+	AddToCart: Content;
+	Purchase: Content;
+	Lead: { content_name?: string };
+};
+
+export const metaDestination = (
+	pixelId: string,
+): AnalyticsDestination<MetaEvents> => {
+	const fbq = () => {
+		if (!window.fbq) {
+			loadPixel();
+			window.fbq!("init", pixelId);
+		}
+		return window.fbq!;
+	};
+
+	return {
+		name: "meta",
+		setup: ({ subscribe }) => {
+			for (const name of [
+				"PageView",
+				"ViewContent",
+				"AddToCart",
+				"Purchase",
+				"Lead",
+			] as const) {
+				// `eventID` lets Meta dedupe against the Conversions API.
+				subscribe(name, (payload, { id }) =>
+					fbq()("track", name, payload, { eventID: id }),
+				);
+			}
+		},
+	};
+};
+```
+
+Map it as in [Destinations and mappings](#destinations-and-mappings), with `withConsent(…, ["marketing"])`, so the script only loads with marketing consent, and add [`metaConsent`](#consent-targets) as a target, as the script can't be unloaded when consent is revoked. For advanced matching, pass `user.email` and `user.phone` as `{ em, ph }` to `fbq("init", …)`.
+
+### Logged-in users
+
+Set the user before tracking `loggedIn`, so the event carries it, and restore it before the first `pageViewed` when a session exists. Use the platform's customer id, never the email.
+
+```ts
+analytics.setContext({
+	user: {
+		id: customer.id,
+		email: customer.email,
+		type: customer.ordersCount > 0 ? "returning" : "new",
+	},
+});
+analytics.track("loggedIn", { method: "email" });
+```
+
+Map it to GA4's `login` in GTM's mapping: `loggedIn: (payload) => ({ name: "login", payload })`. Without it, `mapEvery(events, toGa4CustomEvent)` sends it as `logged_in`.
+
+### Debugging
+
+- **Log every event** in development, also those queued for consent: `analytics.subscribe((event) => console.debug("[analytics]", event))`.
+- **See what GTM receives:** `dataLayer` in the console, or GTM's Preview mode, which also shows the consent state.
+- **A destination gets nothing?** Its `requires` isn't granted (check `Cookiebot.consent` or `OnetrustActiveGroups`), its mapping has no entry, or it threw: errors are logged as `[analytics] <name>.<event>`. `analytics.routes()` shows what reaches it.
+- **`"…" reach no destination`:** no mapping covers these catalog events. Map them, or remove them.
+- **`"…" isn't in the events passed to createAnalytics()`:** `track()` got a name outside the catalog. Add it with `defineEvents()`.
+- **A tracker's event missing?** Check its tracker is in `sources`, then [tracking's debugging](tracking.md#debugging).