@buildinams/tracking 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/README.md +86 -208
  2. package/dist/{sources/cart → cart}/index.d.ts +4 -4
  3. package/dist/{sources/cart → cart}/index.js +13 -3
  4. package/dist/cart/index.js.map +1 -0
  5. package/dist/chunk-JZ6HFGVJ.js +163 -0
  6. package/dist/chunk-JZ6HFGVJ.js.map +1 -0
  7. package/dist/{compatibility-Dc1JmTeG.d.ts → compatibility-wHn2I_ws.d.ts} +2 -2
  8. package/dist/{consent/index.d.ts → consent-types-DgKtGapr.d.ts} +5 -1
  9. package/dist/{consent/cookiebot → cookiebot}/index.d.ts +1 -1
  10. package/dist/{consent/cookiebot → cookiebot}/index.js +1 -1
  11. package/dist/cookiebot/index.js.map +1 -0
  12. package/dist/destination-types-DNMBOW_e.d.ts +22 -0
  13. package/dist/devtools/index.d.ts +18 -0
  14. package/dist/devtools/index.js +299 -0
  15. package/dist/devtools/index.js.map +1 -0
  16. package/dist/{sources/dom → dom}/index.d.ts +34 -40
  17. package/dist/{sources/dom → dom}/index.js +149 -247
  18. package/dist/dom/index.js.map +1 -0
  19. package/dist/events/index.d.ts +3 -6
  20. package/dist/events/index.js +5 -4
  21. package/dist/events/index.js.map +1 -1
  22. package/dist/flow/index.d.ts +10 -8
  23. package/dist/flow/index.js +23 -9
  24. package/dist/flow/index.js.map +1 -1
  25. package/dist/google/index.d.ts +32 -0
  26. package/dist/google/index.js +66 -0
  27. package/dist/google/index.js.map +1 -0
  28. package/dist/{page → navigation}/index.d.ts +7 -12
  29. package/dist/{page → navigation}/index.js +4 -10
  30. package/dist/navigation/index.js.map +1 -0
  31. package/dist/{consent/onetrust → onetrust}/index.d.ts +1 -1
  32. package/dist/{consent/onetrust → onetrust}/index.js +1 -1
  33. package/dist/onetrust/index.js.map +1 -0
  34. package/dist/shopify/index.d.ts +45 -0
  35. package/dist/{consent/shopify → shopify}/index.js +48 -20
  36. package/dist/shopify/index.js.map +1 -0
  37. package/dist/{sources/index.d.ts → source-types-fJXZeF2Q.d.ts} +1 -1
  38. package/dist/{types-DfPz7mBl.d.ts → types-CZEg03xW.d.ts} +3 -7
  39. package/docs/annotations.md +104 -0
  40. package/docs/context.md +64 -0
  41. package/docs/decisions/001-vendor-neutral-event-pipeline.md +2 -2
  42. package/docs/decisions/002-data-per-annotation-word.md +34 -0
  43. package/docs/events.md +93 -84
  44. package/docs/setup.md +189 -0
  45. package/package.json +41 -69
  46. package/dist/consent/cookiebot/index.js.map +0 -1
  47. package/dist/consent/index.js +0 -3
  48. package/dist/consent/index.js.map +0 -1
  49. package/dist/consent/onetrust/index.js.map +0 -1
  50. package/dist/consent/shopify/index.d.ts +0 -13
  51. package/dist/consent/shopify/index.js.map +0 -1
  52. package/dist/destinations/ga4/index.d.ts +0 -16
  53. package/dist/destinations/ga4/index.js +0 -15
  54. package/dist/destinations/ga4/index.js.map +0 -1
  55. package/dist/destinations/index.d.ts +0 -9
  56. package/dist/destinations/index.js +0 -17
  57. package/dist/destinations/index.js.map +0 -1
  58. package/dist/destinations/shopify/index.d.ts +0 -12
  59. package/dist/destinations/shopify/index.js +0 -18
  60. package/dist/destinations/shopify/index.js.map +0 -1
  61. package/dist/page/index.js.map +0 -1
  62. package/dist/sources/cart/index.js.map +0 -1
  63. package/dist/sources/cart/shopify/index.d.ts +0 -28
  64. package/dist/sources/cart/shopify/index.js +0 -16
  65. package/dist/sources/cart/shopify/index.js.map +0 -1
  66. package/dist/sources/dom/index.js.map +0 -1
  67. package/dist/sources/index.js +0 -3
  68. package/dist/sources/index.js.map +0 -1
  69. package/dist/types-BfJsv8AV.d.ts +0 -30
@@ -1,6 +1,19 @@
1
- import { IS_DEVELOPMENT } from '../../chunk-KLN5K6PR.js';
1
+ import { IS_DEVELOPMENT } from '../chunk-KLN5K6PR.js';
2
2
 
3
- // src/consent/shopify/customer-privacy-api.ts
3
+ // src/shopify/shopify-cart.ts
4
+ var shopifyCart = () => ({
5
+ lines(cart) {
6
+ const lines = cart.lines;
7
+ if (!lines) return [];
8
+ if ("nodes" in lines) return lines.nodes;
9
+ if ("edges" in lines) return lines.edges.map(({ node }) => node);
10
+ return lines;
11
+ },
12
+ key: (line) => line.merchandise?.id ?? line.id,
13
+ quantity: (line) => line.quantity
14
+ });
15
+
16
+ // src/shopify/customer-privacy-api.ts
4
17
  var warn = (...args) => {
5
18
  if (IS_DEVELOPMENT) console.warn("[tracking]", ...args);
6
19
  };
@@ -37,7 +50,7 @@ var withCustomerPrivacy = (callback) => {
37
50
  );
38
51
  };
39
52
 
40
- // src/consent/shopify/shopify-consent.ts
53
+ // src/shopify/shopify-consent.ts
41
54
  var read = () => {
42
55
  const api = readCustomerPrivacy();
43
56
  if (!api) return null;
@@ -68,26 +81,41 @@ var shopifyConsent = () => ({
68
81
  }
69
82
  });
70
83
 
71
- // src/consent/shopify/shopify-customer-privacy.ts
84
+ // src/shopify/shopify-customer-privacy.ts
85
+ var toShopifyConsent = ({
86
+ analytics,
87
+ marketing,
88
+ preferences
89
+ }) => ({
90
+ analytics,
91
+ marketing,
92
+ preferences,
93
+ sale_of_data: marketing
94
+ });
72
95
  var shopifyCustomerPrivacy = ({
73
- saleOfData = "marketing"
74
- } = {}) => ({
75
- name: "shopify",
76
- apply(consent) {
77
- const { analytics, marketing, preferences } = consent;
78
- const sale_of_data = typeof saleOfData === "function" ? saleOfData(consent) : consent[saleOfData];
96
+ mapConsent = (_consent, defaults) => defaults
97
+ } = {}) => {
98
+ const apply = (consent) => {
99
+ const tracking = mapConsent(consent, toShopifyConsent(consent));
79
100
  withCustomerPrivacy(
80
- (api) => api.setTrackingConsent(
81
- { analytics, marketing, preferences, sale_of_data },
82
- (result) => {
83
- if (result?.error)
84
- warn("Shopify rejected the tracking consent", result.error);
85
- }
86
- )
101
+ (api) => api.setTrackingConsent(tracking, (result) => {
102
+ if (result?.error)
103
+ warn("Shopify rejected the tracking consent", result.error);
104
+ })
87
105
  );
88
- }
89
- });
106
+ };
107
+ return {
108
+ name: "shopify",
109
+ apply,
110
+ clear: () => apply({
111
+ necessary: true,
112
+ preferences: false,
113
+ analytics: false,
114
+ marketing: false
115
+ })
116
+ };
117
+ };
90
118
 
91
- export { shopifyConsent, shopifyCustomerPrivacy };
119
+ export { shopifyCart, shopifyConsent, shopifyCustomerPrivacy };
92
120
  //# sourceMappingURL=index.js.map
93
121
  //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../../src/shopify/shopify-cart.ts","../../src/shopify/customer-privacy-api.ts","../../src/shopify/shopify-consent.ts","../../src/shopify/shopify-customer-privacy.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { CartAdapter } from \"../cart\";\n\nexport type ShopifyCartLine = {\n\tid: string;\n\tquantity: number;\n\tmerchandise?: { id: string };\n};\n\n/** Storefront API connections and Hydrogen's flattened arrays both fit. */\ntype Lines<Line> =\n\t| readonly Line[]\n\t| { nodes: readonly Line[] }\n\t| { edges: readonly { node: Line }[] };\n\nexport type ShopifyCart = { lines?: Lines<ShopifyCartLine> | null };\n\nexport type ShopifyCartLineOf<Cart extends ShopifyCart> = (NonNullable<\n\tCart[\"lines\"]\n> extends Lines<infer Line>\n\t? Line\n\t: never) &\n\tShopifyCartLine;\n\n/** Reads Storefront API and Hydrogen carts, keying lines by variant. */\nexport const shopifyCart = <\n\tCart extends ShopifyCart = ShopifyCart,\n>(): CartAdapter<Cart, ShopifyCartLineOf<Cart>> => ({\n\tlines(cart) {\n\t\tconst lines = cart.lines as\n\t\t\t| Lines<ShopifyCartLineOf<Cart>>\n\t\t\t| null\n\t\t\t| undefined;\n\t\tif (!lines) return [];\n\t\tif (\"nodes\" in lines) return lines.nodes;\n\t\tif (\"edges\" in lines) return lines.edges.map(({ node }) => node);\n\t\treturn lines;\n\t},\n\tkey: (line) => line.merchandise?.id ?? line.id,\n\tquantity: (line) => line.quantity,\n});\n","import { IS_DEVELOPMENT } from \"../config\";\n\ntype ConsentValue = \"yes\" | \"no\" | \"\";\n\nexport type CustomerPrivacyApi = {\n\tsetTrackingConsent(\n\t\tconsent: {\n\t\t\tanalytics: boolean;\n\t\t\tmarketing: boolean;\n\t\t\tpreferences: boolean;\n\t\t\tsale_of_data: boolean;\n\t\t},\n\t\tcallback: (result?: { error?: unknown }) => void,\n\t): void;\n\tcurrentVisitorConsent(): {\n\t\tanalytics: ConsentValue;\n\t\tmarketing: ConsentValue;\n\t\tpreferences: ConsentValue;\n\t};\n\tshouldShowBanner(): boolean;\n\tanalyticsProcessingAllowed(): boolean;\n\tmarketingAllowed(): boolean;\n\tpreferencesProcessingAllowed(): boolean;\n\t/** Set on headless storefronts, by Shopify's scripts. */\n\tconsentStatus?: \"loading\" | \"loaded\";\n};\n\ntype ShopifyGlobal = {\n\tShopify?: {\n\t\tcustomerPrivacy?: Partial<CustomerPrivacyApi>;\n\t\tloadFeatures?(\n\t\t\tfeatures: { name: string; version: string }[],\n\t\t\tcallback: (error?: unknown) => void,\n\t\t): void;\n\t};\n};\n\nexport const warn = (...args: unknown[]) => {\n\tif (IS_DEVELOPMENT) console.warn(\"[tracking]\", ...args);\n};\n\n/** Fired on `document` by Shopify's scripts on headless storefronts once the API has loaded. */\nconst API_LOADED_EVENT = \"consentTrackingApiLoaded\";\n\n// Headless storefronts expose a placeholder first: without methods, then one that allows everything while loading.\nconst isLoaded = (\n\tapi: Partial<CustomerPrivacyApi> | undefined,\n): api is CustomerPrivacyApi =>\n\ttypeof api?.setTrackingConsent === \"function\" &&\n\tapi.consentStatus !== \"loading\";\n\n/** The API once it has loaded, else `undefined`. */\nexport const readCustomerPrivacy = () => {\n\tconst api = (window as ShopifyGlobal).Shopify?.customerPrivacy;\n\treturn isLoaded(api) ? api : undefined;\n};\n\n/** Calls back with the API once it has loaded: loading it on themes, waiting for Shopify's scripts on headless storefronts. */\nexport const withCustomerPrivacy = (\n\tcallback: (api: CustomerPrivacyApi) => void,\n) => {\n\tconst api = readCustomerPrivacy();\n\tif (api) return callback(api);\n\tconst shopify = (window as ShopifyGlobal).Shopify;\n\tif (!shopify?.loadFeatures) {\n\t\tdocument.addEventListener(\n\t\t\tAPI_LOADED_EVENT,\n\t\t\t() => {\n\t\t\t\tconst loaded = readCustomerPrivacy();\n\t\t\t\tif (loaded) callback(loaded);\n\t\t\t\telse warn(\"Shopify's Customer Privacy API didn't load\");\n\t\t\t},\n\t\t\t{ once: true },\n\t\t);\n\t\treturn;\n\t}\n\tshopify.loadFeatures(\n\t\t[{ name: \"consent-tracking-api\", version: \"0.1\" }],\n\t\t(error) => {\n\t\t\tconst loaded = readCustomerPrivacy();\n\t\t\tif (error || !loaded)\n\t\t\t\twarn(\"Shopify's Customer Privacy API didn't load\", error);\n\t\t\telse callback(loaded);\n\t\t},\n\t);\n};\n","import type { Consent, ConsentProvider } from \"../flow\";\nimport {\n\treadCustomerPrivacy,\n\twithCustomerPrivacy,\n} from \"./customer-privacy-api\";\n\nconst read = (): Consent | null => {\n\tconst api = readCustomerPrivacy();\n\tif (!api) return null;\n\tconst { analytics, marketing, preferences } = api.currentVisitorConsent();\n\t// Where no banner is required, Shopify's regional defaults are the answer.\n\tconst answered =\n\t\t!api.shouldShowBanner() ||\n\t\t[analytics, marketing, preferences].some(Boolean);\n\tif (!answered) return null;\n\treturn {\n\t\tnecessary: true,\n\t\tpreferences: api.preferencesProcessingAllowed(),\n\t\tanalytics: api.analyticsProcessingAllowed(),\n\t\tmarketing: api.marketingAllowed(),\n\t};\n};\n\n/** Reads consent from Shopify's Customer Privacy API, e.g. its privacy banner. */\nexport const shopifyConsent = (): ConsentProvider => ({\n\tname: \"shopify\",\n\tget: read,\n\tsubscribe(listener) {\n\t\tlet active = true;\n\t\tconst onChange = () => listener(read());\n\t\tdocument.addEventListener(\"visitorConsentCollected\", onChange);\n\t\twithCustomerPrivacy(() => {\n\t\t\tif (active) onChange();\n\t\t});\n\t\treturn () => {\n\t\t\tactive = false;\n\t\t\tdocument.removeEventListener(\"visitorConsentCollected\", onChange);\n\t\t};\n\t},\n});\n","import type { Consent, ConsentMapping, ConsentSink } from \"../flow\";\nimport { warn, withCustomerPrivacy } from \"./customer-privacy-api\";\n\nexport type ShopifyTrackingConsent = {\n\tanalytics: boolean;\n\tmarketing: boolean;\n\tpreferences: boolean;\n\tsale_of_data: boolean;\n};\n\nexport type ShopifyCustomerPrivacyOptions = {\n\t/** By default `sale_of_data` follows `marketing`. */\n\tmapConsent?: ConsentMapping<ShopifyTrackingConsent>;\n};\n\nconst toShopifyConsent = ({\n\tanalytics,\n\tmarketing,\n\tpreferences,\n}: Consent): ShopifyTrackingConsent => ({\n\tanalytics,\n\tmarketing,\n\tpreferences,\n\tsale_of_data: marketing,\n});\n\n/** Forwards consent to Shopify's Customer Privacy API. */\nexport const shopifyCustomerPrivacy = ({\n\tmapConsent = (_consent, defaults) => defaults,\n}: ShopifyCustomerPrivacyOptions = {}): ConsentSink => {\n\tconst apply = (consent: Consent) => {\n\t\tconst tracking = mapConsent(consent, toShopifyConsent(consent));\n\t\twithCustomerPrivacy((api) =>\n\t\t\tapi.setTrackingConsent(tracking, (result) => {\n\t\t\t\tif (result?.error)\n\t\t\t\t\twarn(\"Shopify rejected the tracking consent\", result.error);\n\t\t\t}),\n\t\t);\n\t};\n\n\treturn {\n\t\tname: \"shopify\",\n\t\tapply,\n\t\tclear: () =>\n\t\t\tapply({\n\t\t\t\tnecessary: true,\n\t\t\t\tpreferences: false,\n\t\t\t\tanalytics: false,\n\t\t\t\tmarketing: false,\n\t\t\t}),\n\t};\n};\n"]}
@@ -3,4 +3,4 @@ type Source = {
3
3
  start(): () => void;
4
4
  };
5
5
 
6
- export type { Source };
6
+ export type { Source as S };
@@ -1,5 +1,4 @@
1
1
  declare const SHAPE: unique symbol;
2
- declare const CONTEXT: unique symbol;
3
2
  type Shape<T> = {
4
3
  readonly [SHAPE]?: T;
5
4
  };
@@ -36,14 +35,11 @@ type SubscribeOptions = {
36
35
  /** Receive the Events held while nobody asked for replay first. */
37
36
  replay?: boolean;
38
37
  };
39
- /** The catalog, carrying the Broker's Context type so `createDestinations()` can read it from `broker.events`. */
40
- type BrokerEvents<C extends Catalog, Cx> = C & {
41
- readonly [CONTEXT]?: Cx;
42
- };
43
38
  type EventBroker<C extends Catalog, Cx = unknown> = {
44
- readonly events: BrokerEvents<C, Cx>;
39
+ /** The catalog, which types what the Broker accepts. */
40
+ readonly events: C;
45
41
  publish<N extends EventName<C>>(name: N, data: EventData<C, N>, composed?: Composition<C, N>): void;
46
42
  subscribe(listener: (event: TrackingEvent<C, EventName<C>, Cx>) => void, options?: SubscribeOptions): () => void;
47
43
  };
48
44
 
49
- export type { BrokerEvents as B, Catalog as C, EventBroker as E, Shape as S, TrackingEvent as T, EventName as a, EventData as b, CatalogEntry as c, Composition as d, EventMeta as e, SubscribeOptions as f };
45
+ export type { Catalog as C, EventName as E, Shape as S, TrackingEvent as T, EventData as a, EventBroker as b, CatalogEntry as c, Composition as d, EventMeta as e, SubscribeOptions as f };
@@ -0,0 +1,104 @@
1
+ # Annotations
2
+
3
+ Nothing is tracked unless an Annotation asks for it. Exact rules: [events.md](events.md#dom-source).
4
+
5
+ ## Roles and Data
6
+
7
+ `data-e` takes Roles (`location`, `list`, `item`, `promotion`, `form`) and Flags (`click`, `video`, `detail`, `page`). Each word's Data goes in `data-e-<word>`, as `key:value;key:value`:
8
+
9
+ ```html
10
+ <section data-e="list" data-e-list="id:summer">
11
+ <article data-e="item" data-e-item="id:product1">
12
+ <h3 data-e-item="name">Linen shirt</h3>
13
+ <button data-e="click" data-e-click="cta:quick-add">Add</button>
14
+ </article>
15
+ </section>
16
+ ```
17
+
18
+ `data-e-item` on an element that isn't an Item is a field of the Item above it; a key without a value takes the element's text, so this Item is `{ id: "product1", name: "Linen shirt" }`. The button's `button:click` carries the Item and List in `composed.item` and `composed.list`.
19
+
20
+ `\;` and `\\` stand for a `;` or `\` in a value. For values from data, like product titles, `encodeData()` from `/dom` writes the escapes:
21
+
22
+ ```tsx
23
+ <main data-e="item detail" data-e-item={encodeData({ id, title })}>
24
+ <h1 data-e-item="name">{title}</h1>
25
+ <button data-e="click" data-e-click="cta:add-to-cart" />
26
+ </main>
27
+ ```
28
+
29
+ ## Pages
30
+
31
+ `pageViews()` publishes one `page:view` per Page with the Data of every `data-e="page"` element:
32
+
33
+ ```html
34
+ <div hidden data-e="page" data-e-page="type:product"></div>
35
+ ```
36
+
37
+ List `pageViews()` first so `page:view` precedes the Page's other Events. Mapping it to GA4's `page_view`? Turn off gtag's own, or Pages count twice.
38
+
39
+ ## Detail pages
40
+
41
+ `data-e="item detail"` publishes `item:view` when the Item is shown; clicks inside it aren't `item:select`. A quick view inside a product card is a detail view too, and doesn't count as a grid entry.
42
+
43
+ ```ts
44
+ // A variant switch isn't a new product view.
45
+ detailViews({ key: (data) => data.handle });
46
+ ```
47
+
48
+ ## Lists
49
+
50
+ An Item's `index` is its position in its List. Paginated or infinite grids pass where they start:
51
+
52
+ ```html
53
+ <ul data-e="list" data-e-list="id:all;offset:24"></ul>
54
+ ```
55
+
56
+ Looping carousels copy slides; mark each copy so it stands for the original:
57
+
58
+ ```tsx
59
+ <li data-e-clone={isClone} data-e="item" data-e-item={encodeData({ id })}>
60
+ ```
61
+
62
+ ## Clicks, forms and videos
63
+
64
+ Opt in per element with a Flag, or per area with `data-e-auto`:
65
+
66
+ ```html
67
+ <footer data-e-auto="links buttons forms videos">…</footer>
68
+ <nav data-e-auto="none">…</nav>
69
+ ```
70
+
71
+ ## Ignoring areas
72
+
73
+ `data-e-ignore` hides an area and everything in it, Annotations included: for loading skeletons, hidden responsive duplicates or CMS previews.
74
+
75
+ ```tsx
76
+ <div data-e-ignore={isLoading}>
77
+ <ProductGrid products={products} />
78
+ </div>
79
+ ```
80
+
81
+ | | Automatic tracking | Flags | Items, Lists, Promotions |
82
+ | -------------------- | ------------------ | ------- | ------------------------ |
83
+ | `data-e-auto="none"` | off | tracked | tracked |
84
+ | `data-e-ignore` | off | off | off |
85
+
86
+ ## Checking Annotations
87
+
88
+ `/devtools` is only bundled when imported:
89
+
90
+ ```ts
91
+ if (process.env.NODE_ENV === "development") {
92
+ const { watchAnnotations, showInspector } = await import(
93
+ "@buildinams/tracking/devtools"
94
+ );
95
+ watchAnnotations(); // Console warnings for mistakes the DOM Source ignores.
96
+ showInspector(); // Outlines Annotated Elements; hover for Data and Composition.
97
+ }
98
+ ```
99
+
100
+ `checkAnnotations(root)` returns the same issues, e.g. for a test.
101
+
102
+ ## Product data from JSON-LD
103
+
104
+ Fields already in the page's `schema.org` JSON-LD, like brand or GTIN, can come from the [Context](context.md) reader instead, as in [`apps/tracking-e2e`](https://github.com/buildinamsterdam/bia-shared/blob/main/apps/tracking-e2e/src/tracking/json-ld.ts). Keep the id in the Annotation.
@@ -0,0 +1,64 @@
1
+ # Context
2
+
3
+ The `context` reader's return type becomes every Event's `context`, typed in Mappings:
4
+
5
+ ```ts
6
+ // src/tracking/context.ts
7
+ import { createClientNavigation } from "@buildinams/tracking/navigation";
8
+
9
+ export const clientNavigation = createClientNavigation();
10
+
11
+ type User =
12
+ | { loggedIn: true; id: string; tier: "member" | "vip" }
13
+ | { loggedIn: false };
14
+
15
+ let user: User = { loggedIn: false };
16
+
17
+ export const setTrackingUser = (next: User) => {
18
+ user = next;
19
+ };
20
+
21
+ export const readContext = () => ({
22
+ url: location.href,
23
+ path: location.pathname,
24
+ // `document.referrer` if every navigation is a full page load.
25
+ referrer: clientNavigation.referrer(),
26
+ user,
27
+ market: document.documentElement.dataset.market ?? "default",
28
+ });
29
+ ```
30
+
31
+ ```ts
32
+ const broker = createEventBroker(catalog, { context: readContext });
33
+
34
+ const destinations = [
35
+ map(broker, gtm(), "none", {
36
+ "item:select": ({ data, context: { user } }) => ({
37
+ name: "select_item",
38
+ payload: {
39
+ user_id: user.loggedIn ? user.id : undefined,
40
+ items: [{ item_id: data.id }],
41
+ },
42
+ }),
43
+ }),
44
+ ];
45
+ ```
46
+
47
+ ```tsx
48
+ // Wherever the session lives
49
+ const TrackingUser = () => {
50
+ const session = useSession();
51
+ React.useEffect(() => {
52
+ setTrackingUser(
53
+ session
54
+ ? { loggedIn: true, id: session.id, tier: session.tier }
55
+ : { loggedIn: false },
56
+ );
57
+ }, [session]);
58
+ return null;
59
+ };
60
+ ```
61
+
62
+ - Read synchronously when an Event is published, so it keeps the Context of that moment; keep async data in a variable, like `user`.
63
+ - Only what a Mapping sends leaves the page, behind that Destination's consent.
64
+ - Browser only: it can use `document` and `window`.
@@ -20,9 +20,9 @@ Options considered:
20
20
  One in-page pipeline, described in [events.md](../events.md):
21
21
 
22
22
  - **Sources publish vendor-neutral Events** declared in a typed Event Catalog to a Broker, which stamps their Meta and Context and keeps them in order.
23
- - **The Broker only publishes and subscribes.** The Current Page provides Context and tells Sources when the Page changes, and the Flow starts the Sources, so the Broker knows neither pages nor Sources.
23
+ - **The Broker only publishes and subscribes.** The project's Context reader, with the Client Navigation's referrer, provides Context; the Client Navigation tells Sources when the Page changes, and the Flow starts the Sources, so the Broker knows neither pages nor Sources.
24
24
  - **Each Event is mapped per Destination,** gated by that Destination's Consent Requirement. Vendor names and fields exist only in Mappings.
25
- - **Composition comes from Annotations** (`data-e`, `data-e-data`) in the rendered markup, not from component props or context.
25
+ - **Composition comes from Annotations** (`data-e`, `data-e-<word>`) in the rendered markup, not from component props or context.
26
26
  - **The cart is observed through Snapshots,** not add and remove calls, so it works with any cart state the storefront already has.
27
27
 
28
28
  ## Consequences
@@ -0,0 +1,34 @@
1
+ # Data per Annotation word
2
+
3
+ Date: 2026-11-17
4
+
5
+ Status: proposed
6
+
7
+ ## Context
8
+
9
+ An Annotation declared its words in `data-e` and its Data in one `data-e-data` attribute. Which word that Data belonged to was inferred from the markup's shape, which attributed it wrongly as soon as Annotations nested or combined:
10
+
11
+ - **Several words on one element shared one Data.** `data-e="item promotion"` gave the Item and the Promotion the same `id`; `data-e="item click"` made the click's Data the Item's.
12
+ - **A field went to the nearest Annotated Element of any Role.** A `<h3 data-e-data="name">` in a List's heading became the `name` of a `location` placed in between, and wrapping markup in a new Role silently moved fields to it.
13
+ - **An element with a Flag could never be a field,** so a `click` button couldn't also give its Item a field.
14
+
15
+ Options considered:
16
+
17
+ - **Explicit references** (`data-e-id` on the owner, `data-e-for` on a field). Fully deterministic, but verbose by hand, and ids must be unique where a product renders in several Lists.
18
+ - **JSON keyed by word in `data-e-data`.** Separates the words on one element but leaves fields ambiguous, and is painful to write in templates.
19
+ - **Fields to the innermost Role only.** Still a guess about the author's intent, just a different one.
20
+
21
+ ## Decision
22
+
23
+ Each word's Data has its own attribute, `data-e-<word>`; `data-e` still declares the words. `data-e-data` is removed.
24
+
25
+ - **Roles own fields by name.** A `data-e-<role>` on an element that doesn't declare that Role is a field of the nearest element above it that does; never of another Role.
26
+ - **Flags with Data** (`click`, `video`, `page`) only read the element's own `data-e-<flag>`; they have no fields.
27
+ - **Composition includes the element's other Roles,** so an Event of `data-e="item click"` carries the Item in `composed.item`.
28
+ - `encodeData()` writes a `data-e-<word>` value, escaping `;` and `\`. Writing the attributes themselves is left to the project.
29
+
30
+ ## Consequences
31
+
32
+ - Breaking for every annotated project: `data-e-data` must become the attribute of the word it was meant for. Ambiguous markup now has to state its intent instead of being read one way or the other.
33
+ - Nesting or combining Annotations can't move Data between words, so annotated markup can be refactored without changing reports.
34
+ - Attributes are longer, but each one says what it feeds.