@buildinams/tracking 0.3.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 (72) hide show
  1. package/README.md +72 -83
  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} +1 -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 +28 -38
  17. package/dist/{sources/dom → dom}/index.js +123 -245
  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 +16 -4
  24. package/dist/flow/index.js.map +1 -1
  25. package/dist/{consent/google → google}/index.d.ts +15 -2
  26. package/dist/{consent/google → google}/index.js +19 -6
  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 +18 -5
  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 +72 -22
  40. package/docs/context.md +14 -14
  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 +86 -81
  44. package/docs/setup.md +63 -28
  45. package/package.json +41 -76
  46. package/dist/chunk-MRBVRDP6.js +0 -6
  47. package/dist/chunk-MRBVRDP6.js.map +0 -1
  48. package/dist/consent/cookiebot/index.js.map +0 -1
  49. package/dist/consent/google/index.js.map +0 -1
  50. package/dist/consent/index.js +0 -3
  51. package/dist/consent/index.js.map +0 -1
  52. package/dist/consent/onetrust/index.js.map +0 -1
  53. package/dist/consent/shopify/index.d.ts +0 -19
  54. package/dist/consent/shopify/index.js.map +0 -1
  55. package/dist/destinations/ga4/index.d.ts +0 -16
  56. package/dist/destinations/ga4/index.js +0 -17
  57. package/dist/destinations/ga4/index.js.map +0 -1
  58. package/dist/destinations/index.d.ts +0 -9
  59. package/dist/destinations/index.js +0 -17
  60. package/dist/destinations/index.js.map +0 -1
  61. package/dist/destinations/shopify/index.d.ts +0 -12
  62. package/dist/destinations/shopify/index.js +0 -18
  63. package/dist/destinations/shopify/index.js.map +0 -1
  64. package/dist/page/index.js.map +0 -1
  65. package/dist/sources/cart/index.js.map +0 -1
  66. package/dist/sources/cart/shopify/index.d.ts +0 -28
  67. package/dist/sources/cart/shopify/index.js +0 -16
  68. package/dist/sources/cart/shopify/index.js.map +0 -1
  69. package/dist/sources/dom/index.js.map +0 -1
  70. package/dist/sources/index.js +0 -3
  71. package/dist/sources/index.js.map +0 -1
  72. package/dist/types-BfJsv8AV.d.ts +0 -30
@@ -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 };
@@ -1,54 +1,104 @@
1
1
  # Annotations
2
2
 
3
- Nothing in the markup is tracked unless an Annotation asks for it. Behavior rules: [events.md](events.md#dom-source).
3
+ Nothing is tracked unless an Annotation asks for it. Exact rules: [events.md](events.md#dom-source).
4
4
 
5
5
  ## Roles and Data
6
6
 
7
- `data-e` takes one or more words in any order: Roles (`location`, `list`, `item`, `promotion`, `form`) and Flags (`click`, `video`, `detail`, `page`). `data-e-data` holds the Data as `key:value` pairs separated by `;`:
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
8
 
9
9
  ```html
10
- <section data-e="list" data-e-data="id:summer;name:Summer">
11
- <article data-e="item" data-e-data="id:product1">
12
- <h3 data-e-data="name">Linen shirt</h3>
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>
13
14
  </article>
14
15
  </section>
15
16
  ```
16
17
 
17
- A `data-e-data` without a value, on a descendant, uses that element's text: the Item above has `name: "Linen shirt"`. Every Event inside an Annotated Element carries it in its Composition, e.g. an `item:select` here has `composed.list`.
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`.
18
19
 
19
- In JSX or templates, spread `annotate()` from `/sources/dom` to write both attributes. It escapes semicolons and backslashes in values; hand-written markup prefixes those with a backslash itself.
20
+ `\;` and `\\` stand for a `;` or `\` in a value. For values from data, like product titles, `encodeData()` from `/dom` writes the escapes:
20
21
 
21
22
  ```tsx
22
- <div {...annotate(["item", "detail"], { id, title })} />
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>
23
27
  ```
24
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
+
25
39
  ## Detail pages
26
40
 
27
- Mark the product on its detail page `data-e="item detail"` for `item:view`. Clicks inside it, like add to cart, aren't `item:select`. `item:view` is published when the Item starts being shown. When its Data includes the variant, `detailViews({ key: (data) => data.handle })` keeps a variant switch from counting as a new view.
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.
28
42
 
29
- Product fields the page already has in its `schema.org` JSON-LD, like the brand or GTIN, don't need repeating in `data-e-data`: read them in the [Context](context.md) reader instead, as [`apps/tracking-e2e`](https://github.com/buildinamsterdam/bia-shared/blob/main/apps/tracking-e2e/src/tracking/json-ld.ts) does. Keep the product's id in the Annotation, since Context comes with every Event on the page.
43
+ ```ts
44
+ // A variant switch isn't a new product view.
45
+ detailViews({ key: (data) => data.handle });
46
+ ```
30
47
 
31
- ## Pages
48
+ ## Lists
32
49
 
33
- Describe each Page with `data-e="page"`: `pageViews()` publishes one `page:view` per Page with the Data of every such element, also when there are none.
50
+ An Item's `index` is its position in its List. Paginated or infinite grids pass where they start:
34
51
 
35
52
  ```html
36
- <div hidden data-e="page" data-e-data="type:product"></div>
53
+ <ul data-e="list" data-e-list="id:all;offset:24"></ul>
37
54
  ```
38
55
 
39
- - Put it on an element without a Role, or that Role's Data is mixed in.
40
- - List `pageViews()` first so `page:view` precedes the Page's other Events.
41
- - When mapping it to GA4's `page_view`, turn off gtag's own (`send_page_view: false` and Enhanced Measurement's history page views) or Pages count twice.
56
+ Looping carousels copy slides; mark each copy so it stands for the original:
42
57
 
43
- ## Clicks and videos
58
+ ```tsx
59
+ <li data-e-clone={isClone} data-e="item" data-e-item={encodeData({ id })}>
60
+ ```
44
61
 
45
- Opt in per element with a Flag (`data-e="click"`, `data-e="video"`), or per area with `data-e-auto="links buttons forms videos"`, e.g. `<footer data-e-auto="links">`. `data-e-auto="none"` opts an area or a single element out.
62
+ ## Clicks, forms and videos
46
63
 
47
- ## Per pathname
64
+ Opt in per element with a Flag, or per area with `data-e-auto`:
48
65
 
49
- Limit a Detector by pathname with `only()` or `except()` from `/sources/dom`:
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:
50
89
 
51
90
  ```ts
52
- except(scroll(), ["/collections/*", "/search", /^\/account\//]);
53
- only(videos(), ["/lookbook/*"]);
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
+ }
54
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.
package/docs/context.md CHANGED
@@ -1,13 +1,12 @@
1
1
  # Context
2
2
 
3
- `context` is any function; its return type becomes every Event's `context`, typed in Mappings. Without it, `context` is `undefined`. Spread `currentPage.read()` into your own to add project data, such as the user:
3
+ The `context` reader's return type becomes every Event's `context`, typed in Mappings:
4
4
 
5
5
  ```ts
6
6
  // src/tracking/context.ts
7
- import { createCurrentPage } from "@buildinams/tracking/page";
7
+ import { createClientNavigation } from "@buildinams/tracking/navigation";
8
8
 
9
- // The one Current Page: also pass it to `createDomSource()` and call its `sync()`.
10
- export const currentPage = createCurrentPage();
9
+ export const clientNavigation = createClientNavigation();
11
10
 
12
11
  type User =
13
12
  | { loggedIn: true; id: string; tier: "member" | "vip" }
@@ -15,13 +14,15 @@ type User =
15
14
 
16
15
  let user: User = { loggedIn: false };
17
16
 
18
- /** Called by the app whenever the session changes. */
19
17
  export const setTrackingUser = (next: User) => {
20
18
  user = next;
21
19
  };
22
20
 
23
21
  export const readContext = () => ({
24
- ...currentPage.read(),
22
+ url: location.href,
23
+ path: location.pathname,
24
+ // `document.referrer` if every navigation is a full page load.
25
+ referrer: clientNavigation.referrer(),
25
26
  user,
26
27
  market: document.documentElement.dataset.market ?? "default",
27
28
  });
@@ -30,8 +31,8 @@ export const readContext = () => ({
30
31
  ```ts
31
32
  const broker = createEventBroker(catalog, { context: readContext });
32
33
 
33
- const destinations = createDestinations(broker.events, [
34
- map(withConsent(ga4(), "none"), {
34
+ const destinations = [
35
+ map(broker, gtm(), "none", {
35
36
  "item:select": ({ data, context: { user } }) => ({
36
37
  name: "select_item",
37
38
  payload: {
@@ -40,14 +41,14 @@ const destinations = createDestinations(broker.events, [
40
41
  },
41
42
  }),
42
43
  }),
43
- ]);
44
+ ];
44
45
  ```
45
46
 
46
47
  ```tsx
47
48
  // Wherever the session lives
48
49
  const TrackingUser = () => {
49
50
  const session = useSession();
50
- useEffect(() => {
51
+ React.useEffect(() => {
51
52
  setTrackingUser(
52
53
  session
53
54
  ? { loggedIn: true, id: session.id, tier: session.tier }
@@ -58,7 +59,6 @@ const TrackingUser = () => {
58
59
  };
59
60
  ```
60
61
 
61
- - **Read on publish.** Each Event keeps the Context of the moment it happened, also while it waits for consent; a login mid-visit shows from the next Event on.
62
- - **Synchronous.** The reader runs inside `publish()`; keep async data, like a fetched profile, in a variable it returns, as `setTrackingUser` does.
63
- - **Only what Mappings send leaves the page.** Context isn't forwarded by itself: each Mapping picks the fields its Destination gets, behind that Destination's consent, so personal data is decided per Destination.
64
- - **Browser only.** The reader never runs on the server, so it can use `document` and `window`.
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.