@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
package/docs/events.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Events module
2
2
 
3
- The events module records what shoppers do on the storefront as vendor-neutral Events and delivers them, consent permitting, to each Destination in that Destination's own format. Why it's shaped this way: [ADR 001](decisions/001-vendor-neutral-event-pipeline.md).
3
+ Vocabulary and behavior of the package. Why it's shaped this way: [ADR 001](decisions/001-vendor-neutral-event-pipeline.md).
4
4
 
5
5
  ## Non-goals
6
6
 
@@ -39,21 +39,21 @@ The events module records what shoppers do on the storefront as vendor-neutral E
39
39
 
40
40
  ### Pipeline
41
41
 
42
- | Term | Definition | Avoid |
43
- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
44
- | Broker | The in-page hub that accepts Events from Sources, stamps their Meta and Context, and hands them on in order. | Bus, dataLayer, emitter |
45
- | Source | Anything that observes part of the storefront and publishes Events to the Broker. | Producer, publisher, tracker |
46
- | DOM Source | The Source that turns shopper interaction with Annotated Elements into Events, using Detectors. | |
47
- | Detector | One way the DOM Source notices something happened: Page views, Item selections, clicks, forms, videos, scroll depth or impressions. | Trigger (GTM's), listener, plugin |
48
- | Annotation | Markup that declares an element's Roles, Flags and Data (`data-e`, `data-e-data`). | Data attributes, tagging |
49
- | Annotated Element | An element with a Role in its Annotation; it contributes that Role and its Data to every Event inside it. | |
50
- | Flag | A `data-e` word that opts an element in to a Detector (`click`, `video`, `detail`, `page`) without giving it a Role. | Marker, opt-in attribute |
51
- | Impression | A Promotion, or an Item in a List, becoming visible to the shopper for the first time on a Page. | View, exposure |
52
- | Page | One visit to a URL as the shopper experiences it, including client-side navigations. | Route, screen, pageview |
53
- | Current Page | Tracks the current Page: reads its facts for Context, starts the next Page on `sync()` when the URL's key changed, and tells subscribed Sources when a Page ends and the next starts. | Page tracker, router, environment |
54
- | Cart Source | The Source that derives cart Events by comparing successive Cart Snapshots. | |
55
- | Cart Snapshot | The full contents of the cart at one moment, as the storefront knows it. | Cart state, cart diff |
56
- | Cart Adapter | How the Cart Source reads a project's cart: its lines, a key per line and a quantity, e.g. `shopifyCart()` for Shopify carts. | Cart mapper, cart parser |
42
+ | Term | Definition | Avoid |
43
+ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
44
+ | Broker | The in-page hub that accepts Events from Sources, stamps their Meta and Context, and hands them on in order. | Bus, dataLayer, emitter |
45
+ | Source | Anything that observes part of the storefront and publishes Events to the Broker. | Producer, publisher, tracker |
46
+ | DOM Source | The Source that turns shopper interaction with Annotated Elements into Events, using Detectors. | |
47
+ | Detector | One way the DOM Source notices something happened: Page views, Item selections, clicks, forms, videos, scroll depth or impressions. | Trigger (GTM's), listener, plugin |
48
+ | Annotation | Markup that declares an element's Roles, Flags and Data (`data-e`, `data-e-<word>`). | Data attributes, tagging |
49
+ | Annotated Element | An element with a Role in its Annotation; it contributes that Role and its Data to every Event inside it. | |
50
+ | Flag | A `data-e` word that opts an element in to a Detector (`click`, `video`, `detail`, `page`) without giving it a Role. | Marker, opt-in attribute |
51
+ | Impression | A Promotion, or an Item in a List, becoming visible to the shopper for the first time on a Page. | View, exposure |
52
+ | Page | One visit to a URL as the shopper experiences it, including client-side navigations. | Route, screen, pageview |
53
+ | Client Navigation | Follows Pages across client-side navigations: gives the referrer for Context, starts the next Page on `sync()` when the URL's key changed, and tells subscribed Sources when a Page ends and the next starts. Not needed when every navigation is a full page load. | Page tracker, router, environment |
54
+ | Cart Source | The Source that derives cart Events by comparing successive Cart Snapshots. | |
55
+ | Cart Snapshot | The full contents of the cart at one moment, as the storefront knows it. | Cart state, cart diff |
56
+ | Cart Adapter | How the Cart Source reads a project's cart: its lines, a key per line and a quantity, e.g. `shopifyCart()` for Shopify carts. | Cart mapper, cart parser |
57
57
 
58
58
  ### Delivery
59
59
 
@@ -61,7 +61,7 @@ The events module records what shoppers do on the storefront as vendor-neutral E
61
61
  | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
62
62
  | Destination | An external analytics service Events are delivered to, such as GA4 or Shopify Analytics. | Sink, integration, provider, vendor |
63
63
  | Mapping | The per-Destination translation from an Event to zero or one Destination event. | Transform, adapter, converter |
64
- | Mapped Destination | A Destination with its Mapping and Consent Requirement; `createDestinations()` gathers them for the Flow. | Route, router |
64
+ | Mapped Destination | A Destination with its Mapping and Consent Requirement, made by `map()`; the Flow delivers to a list of them. | Route, router |
65
65
  | Consent Requirement | The consent categories a Destination needs before it may receive Events; `none` means always. | Permission, gate |
66
66
  | Consent Provider | The consent management platform that reports which categories the shopper granted, such as Cookiebot. | CMP adapter, cookie banner |
67
67
  | Consent Sink | A platform that is told every consent answer so it can gate its own tracking, such as Shopify Customer Privacy. | Consent target, consent forwarder |
@@ -71,26 +71,26 @@ The events module records what shoppers do on the storefront as vendor-neutral E
71
71
 
72
72
  ### Lifecycle + SSR
73
73
 
74
- | Behavior | Description |
75
- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
76
- | B-001 | Creating the Broker, Destinations and Sources has no side effects, so the modules that create them are safe to import on the server. |
77
- | B-002 | Annotations are plain string attributes, so server components and CMS HTML render them without client JavaScript per element. |
78
- | B-003 | Nothing is observed, held or delivered on the server; starting the Flow there does nothing. |
79
- | B-004 | Starting the Flow subscribes it to the Broker with replay, starts the Sources and the Consent Provider, and delivers held Events in Sequence Number order. |
80
- | B-005 | Starting the Flow again (e.g. after HMR) stops the previous Flow and its Sources first, so nothing is subscribed or listened to twice. |
81
- | B-006 | The DOM Source reads server-rendered markup, so Impressions of content visible before hydration are recorded once the Flow starts. |
82
- | B-007 | `currentPage.sync()` must be called on every client-side navigation, after the URL changed and before the new page's DOM is reported: in React, from a layout effect. It starts a new Page only when the URL's key (by default its pathname) changed; otherwise it does nothing. |
83
- | B-008 | The DOM Source flushes when a Page ends and when the document is hidden, so batched Events survive navigation and tab close. |
84
- | B-009 | Starting a new Page tells every subscribed Source the Page ends, then moves the Current Page on (the last URL seen on the previous Page, e.g. with its `?sort=`, becomes the referrer), then tells them the next Page started: every Source flushes under the old Page and resets under the new one. |
74
+ | Behavior | Description |
75
+ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
76
+ | B-001 | Creating the Broker, Destinations and Sources has no side effects, so the modules that create them are safe to import on the server. |
77
+ | B-002 | Annotations are plain string attributes, so server components and CMS HTML render them without client JavaScript per element. |
78
+ | B-003 | Nothing is observed, held or delivered on the server; starting the Flow there does nothing. |
79
+ | B-004 | Starting the Flow subscribes it to the Broker with replay, starts the Sources and the Consent Provider, and delivers held Events in Sequence Number order. |
80
+ | B-005 | Starting the Flow again (e.g. after HMR) stops the previous Flow and its Sources first, so nothing is subscribed or listened to twice. |
81
+ | B-006 | The DOM Source reads server-rendered markup, so Impressions of content visible before hydration are recorded once the Flow starts. |
82
+ | B-007 | `clientNavigation.sync()` must run on every client-side navigation, after the URL changed and before the new page's DOM is reported: in React, from a layout effect. It starts a new Page only when the URL's key (by default its pathname) changed. |
83
+ | B-008 | The DOM Source flushes when a Page ends and when the document is hidden, so batched Events survive navigation and tab close. |
84
+ | B-009 | Starting a new Page tells every subscribed Source the Page ended, moves the referrer to the previous Page's last URL, then tells them the next Page started: Sources flush under the old Page and reset under the new one. |
85
85
 
86
86
  ### Events and the Catalog
87
87
 
88
- | Behavior | Description |
89
- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
90
- | B-101 | Every Event Name is declared in the Event Catalog; publishing an undeclared name is a type error. |
91
- | B-102 | Event Names follow `subject:action` and describe what the shopper did (`item:select`, not `select_item`). |
92
- | B-103 | An Event is immutable once the Broker accepts it; Mappings must not mutate it. |
93
- | B-104 | A Source accepts a Detector or Cart Adapter only when the catalog declares every Event Name it publishes, and every field the catalog declares for it accepts the type it's published with. Fields the catalog adds, such as `data-e-data` ones, or leaves out are fine. |
88
+ | Behavior | Description |
89
+ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
90
+ | B-101 | Every Event Name is declared in the Event Catalog; publishing an undeclared name is a type error. |
91
+ | B-102 | Event Names follow `subject:action` and describe what the shopper did (`item:select`, not `select_item`). |
92
+ | B-103 | An Event is immutable once the Broker accepts it; Mappings must not mutate it. |
93
+ | B-104 | A Source accepts a Detector or Cart Adapter only when the catalog declares each Event Name it publishes, with fields that accept the published types. Extra or missing catalog fields are fine. |
94
94
 
95
95
  ### Broker
96
96
 
@@ -98,43 +98,48 @@ The events module records what shoppers do on the storefront as vendor-neutral E
98
98
  | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
99
99
  | B-201 | On accept, the Broker stamps Meta: a unique Event ID, a Timestamp and the next Sequence Number, counted per page load. |
100
100
  | B-202 | On accept, the Broker reads Context from the reader it was given, so it reflects the moment of the action rather than the moment of delivery. Without a reader, Context is `undefined`. |
101
- | B-203 | While no subscriber asked for replay, the Broker holds accepted Events, up to 100 by default; past it the oldest are dropped with a development warning. |
102
- | B-205 | A subscriber asking for replay first receives the held Events, which are then no longer held; others receive only Events published after they subscribed. |
101
+ | B-203 | While no subscriber asked for replay, the Broker holds accepted Events, up to 100; past it the oldest are dropped with a development warning. |
103
102
  | B-204 | Every subscriber receives Events in Sequence Number order. |
103
+ | B-205 | A subscriber asking for replay first receives the held Events, which are then no longer held; others receive only Events published after they subscribed. |
104
104
 
105
105
  ### DOM Source
106
106
 
107
- | Behavior | Description |
108
- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
109
- | B-301 | `data-e` holds space-separated words in any order: Roles (`location`, `list`, `item`, `promotion`, `form`) make an Annotated Element; Flags (`click`, `video`, `detail`, `page`) opt it in to Detectors. An element may have several, e.g. `data-e="item detail"`. |
110
- | B-302 | `data-e-data="key:value;key:value"` gives an Annotated Element literal Data. `\;` and `\\` stand for a `;` or `\` in a value; `annotate()` writes them. |
111
- | B-303 | A bare `data-e-data="<key>"` on an element without `data-e` contributes its text as field `<key>` of the nearest Annotated Element above it; Flags in between never take fields away from it. |
112
- | B-304 | Composition is built by walking up from the target, taking the nearest Annotated Element of each role; the target's own element is Data. |
113
- | B-305 | A role with no Annotated Element above the target is absent from the Composition, not empty. |
114
- | B-306 | An Impression is counted at most once per Annotated Element per Page. A Promotion's publishes `promotion:view`; Items' are batched per List into one `list:view` with each Item's `index`; Items outside a List aren't reported. |
115
- | B-307 | A new Page publishes `page:view` (B-319), resets Impressions and scroll depth and refreshes Context. |
116
- | B-308 | Links, buttons and videos are tracked only when opted in: by their own `click` / `video` Flag, else by the nearest `data-e-auto` on or above them (`links`, `buttons`, `forms`, `videos`, or `none` to opt out, also on the element itself), else by the Detector's `auto` option, off by default. |
117
- | B-309 | A Form Annotation always tracks its form; other forms follow `data-e-auto` and the `auto` option. |
118
- | B-310 | A tracked element's own `data-e-data` is merged into the Data the Detector derives, and wins on conflicts. |
119
- | B-311 | A link click is outbound when it leads over http(s) to a host other than the page's and the configured internal hosts, and a download when it has a `download` attribute or a known file extension. |
120
- | B-312 | `form:start` is published on the first input in a form per Page; `form:submit` on submission, with the submit button's text. Field values are never read. |
121
- | B-313 | A video publishes `video:start` once per playback, each progress threshold once per playback, and `video:complete` when it ends; playing it again after that is a new playback. |
122
- | B-314 | A link or button click in an Item publishes `item:select`, with the Item's `index` added when it's in a List; whether it counts as a List or Promotion selection is for Mappings to decide from its Composition. Clicks in an Item flagged `detail`, such as add to cart on its own detail page, select nothing; Items nested in it, like related products, still do. |
123
- | B-315 | A link or button click in a Promotion outside any Item publishes `promotion:select`. Clicks elsewhere in an Item or Promotion, e.g. on an image or text, select nothing. |
124
- | B-316 | `list:view` batches are published after a delay, before every link click is handled, when the document is hidden, and before a new Page, so they carry the Page they were seen on. |
125
- | B-317 | `item:view` is published only for an Item flagged `detail` (`data-e="item detail"`, an item detail page), when it starts being shown: once per Item while it stays on screen, across URL changes and re-rendered elements, and again after a Page without it. An Item in a hidden page, like a route a router keeps for back navigation, isn't shown. `detailViews({ key })` decides what makes two Items the same, e.g. one product across its variants. |
126
- | B-318 | `only(detector, paths)` and `except(detector, paths)` limit a Detector to Pages whose URL does or doesn't match one of `paths` (exact pathname, pathname ending in `/*`, `RegExp` or function of the URL). It's decided at the start of each Page, so batches flushed when a Page ends follow the Page they were collected on. |
127
- | B-319 | `page:view` is published once per Page: when the DOM Source starts and whenever a new Page starts, with the Data of every element flagged `page` (`data-e="page"`) merged in document order, later ones winning. A Page without one still publishes it, with empty Data. It reads the DOM at that moment, so page Annotations must be rendered by then, not behind a Suspense boundary; put them on elements without a Role, or that Role's Data is mixed in. |
107
+ | Behavior | Description |
108
+ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
109
+ | B-301 | `data-e` holds space-separated words in any order: Roles (`location`, `list`, `item`, `promotion`, `form`) make an Annotated Element; Flags (`click`, `video`, `detail`, `page`) opt it in to Detectors. An element may have several, e.g. `data-e="item detail"`. |
110
+ | B-302 | `data-e-<word>="key:value;key:value"` gives a word on that element literal Data; each word has its own attribute, and `detail` has none. `\;` and `\\` stand for a `;` or `\` in a value; `encodeData()` writes them. |
111
+ | B-303 | `data-e-<role>` on an element without that Role is a field of the nearest element above it with that Role, never of another Role; a bare `<key>` contributes the element's text. Flags have no fields. |
112
+ | B-304 | Composition is built by walking up from the target, itself included, taking the nearest Annotated Element of each Role other than the word whose Event it is; that word's Data is the Event's Data. |
113
+ | B-305 | A Role with no Annotated Element on or above the target is absent from the Composition, not empty. |
114
+ | B-306 | An Impression counts at most once per Annotated Element per Page. A Promotion's publishes `promotion:view` with all its Items and their `index`; Items' are batched per List into one `list:view`; Items outside a List aren't reported. |
115
+ | B-307 | A new Page publishes `page:view` (B-319), resets Impressions and scroll depth and refreshes Context. |
116
+ | B-308 | Links, buttons and videos are tracked only when opted in: by their own `click` / `video` Flag, else by the nearest `data-e-auto` on or above them (`links`, `buttons`, `forms`, `videos`, or `none`), else by the Detector's `auto` option, off by default. |
117
+ | B-309 | A Form Annotation always tracks its form; other forms follow `data-e-auto` and the `auto` option. |
118
+ | B-310 | A tracked element's own `data-e-click`, `data-e-video` or `data-e-form` is merged into the Data the Detector derives, and wins on conflicts. Its Composition includes the element's own Roles, e.g. `composed.item` for `data-e="item click"`. |
119
+ | B-311 | `link:click` carries the link's absolute `url` and its `text`; whether it's outbound or a download is for Mappings to decide from `url`. |
120
+ | B-312 | `form:start` is published on the first input in a form per Page; `form:submit` on submission, with the submit button's text. Field values are never read. |
121
+ | B-313 | A video publishes `video:start` once per playback, each progress threshold once per playback, and `video:complete` when it ends; playing it again after that is a new playback. |
122
+ | B-314 | A link or button click in an Item publishes `item:select`, with its `index` in its List, else its Promotion; Mappings decide from the Composition which it counts as. Clicks in a `detail` Item select nothing; Items nested in it still do. |
123
+ | B-315 | A link or button click in a Promotion outside any Item publishes `promotion:select`, with its Items as in `promotion:view`. Clicks on anything else select nothing. |
124
+ | B-316 | `list:view` batches are published after a delay, before every link click is handled, when the document is hidden, and before a new Page, so they carry the Page they were seen on. |
125
+ | B-317 | `item:view` is published for an Item flagged `detail` when it starts being shown: once while it stays on screen, across URL changes and re-renders, and again after a Page without it. Items in a hidden page, like a route kept for back navigation, aren't shown. `detailViews({ key })` decides when two Items are the same. |
126
+ | B-319 | `page:view` is published once per Page, also without `page` Annotations, with the Data of every `data-e="page"` element merged in document order. It reads the DOM when the Page starts, so page Annotations can't wait behind Suspense. |
127
+ | B-320 | An Item flagged `detail` is never a List or Promotion entry: impressions, `index` and a Promotion's `items` skip it. |
128
+ | B-321 | The DOM Source never checks Annotations. `watchAnnotations()` from `/devtools` warns once per element about mistakes it ignores; warnings never change what's published. |
129
+ | B-322 | An Item's `index` in a List starts at the List's `offset` Data. A Promotion's starts at 0. |
130
+ | B-323 | An Item in or under `data-e-clone` (any value but `"false"`) isn't a List or Promotion entry; it stands for the entry with the same Data, sharing its impression and `index`. |
131
+ | B-324 | An element's List, Promotion and contained Items are found from the nearest element with that Role on or above it, so an element that is both an Item and a Promotion is that Promotion's single Item. |
132
+ | B-325 | An element with `data-e-ignore` (any value but `"false"`) and everything in it are invisible to the DOM Source: nothing inside publishes or adds Data, fields or entries to anything outside. Nothing further in undoes it. |
128
133
 
129
134
  ### Cart Source
130
135
 
131
- | Behavior | Description |
132
- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
133
- | B-401 | The Cart Source receives whole Cart Snapshots, never individual add or remove calls. |
134
- | B-402 | Events come from the difference between the previous and new Snapshot: a quantity increase adds the difference, a decrease removes it. |
135
- | B-403 | The first Snapshot after load is the baseline and produces no Events, so hydrating an existing cart isn't reported as adds. |
136
- | B-404 | The Cart Source reads carts only through its Cart Adapter and assumes no platform's cart shape; `shopifyCart()` keys Shopify lines by variant, so a variant swap is a remove plus an add. |
137
- | B-405 | The Cart Source diffs Snapshots whether or not the Flow is running; the Broker holds its Events until the Flow starts. Its `start()` does nothing yet; pass it in `sources` so whatever it later needs from the Flow is already wired. |
136
+ | Behavior | Description |
137
+ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
138
+ | B-401 | The Cart Source receives whole Cart Snapshots, never individual add or remove calls. |
139
+ | B-402 | Events come from the difference between the previous and new Snapshot: a quantity increase adds the difference, a decrease removes it. |
140
+ | B-403 | The first Snapshot after load is the baseline and produces no Events, so hydrating an existing cart isn't reported as adds. |
141
+ | B-404 | The Cart Source reads carts only through its Cart Adapter and assumes no platform's cart shape; `shopifyCart()` keys Shopify lines by variant, so a variant swap is a remove plus an add. |
142
+ | B-405 | The Cart Source is a Flow Source. Before the Flow first starts it, the Broker holds its Events; once stopped, Snapshots only move the baseline, so restarting it (e.g. after HMR) doesn't report what changed meanwhile. |
138
143
 
139
144
  ### Destinations
140
145
 
@@ -145,23 +150,23 @@ The events module records what shoppers do on the storefront as vendor-neutral E
145
150
  | B-503 | Mappings produce the Destination's native names and fields; vendor knowledge lives only in Mappings and Destinations. |
146
151
  | B-504 | Mappings pass the Event ID through wherever the Destination supports a dedupe key. |
147
152
  | B-505 | One Destination failing never blocks or fails another. |
148
- | B-506 | `ga4()` pushes `{ ecommerce: null }` before an event with `ecommerce`, since GTM would otherwise merge the previous event's items into it. |
153
+ | B-506 | `gtm()` pushes `{ ecommerce: null }` before an event with `ecommerce`, since GTM would otherwise merge the previous event's items into it. |
149
154
 
150
155
  ### Consent
151
156
 
152
- | Behavior | Description |
153
- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
154
- | B-601 | Consent Requirements use the module's own categories; the Consent Provider translates its platform's (e.g. Cookiebot's `statistics`). |
155
- | B-602 | `none` means the Destination always receives Events; it's for Destinations that enforce consent themselves, like GA4 Consent Mode. |
156
- | B-603 | While consent is unanswered, Events for a gated Destination are held (up to 100, oldest dropped); once granted they're delivered in order, once denied discarded. |
157
- | B-604 | Withdrawing consent stops delivery from that moment; it never recalls what was sent. |
158
- | B-605 | Every consent answer is applied to each Consent Sink before Destinations receive Events under it, including an answer already given when the Flow starts. |
159
- | B-606 | A Consent Sink named like the Consent Provider is skipped, so consent is never written back to its source. |
160
- | B-607 | One Consent Sink failing never blocks another, or delivery. |
161
- | B-608 | Shopify's Customer Privacy API counts once loaded; a headless store's placeholder allows everything until `consentTrackingApiLoaded`. |
162
- | B-609 | `googleConsentMode()` denies every Consent Mode type except `security_storage` when the first one is created for a data layer, waiting 2 seconds for the answer by default, then updates them with each answer: by default `analytics` grants `analytics_storage`, `marketing` the ad signals and `preferences` functionality and personalization storage. `security_storage` is always granted: storage strictly necessary for security, like fraud prevention, needs no consent, and banners never ask for it. `mapConsent` can deny it. |
163
- | B-610 | When an answer is withdrawn back to unanswered, e.g. by a banner reset, each Consent Sink with `clear()` is told, and gated Destinations hold Events again. `googleConsentMode()` and `shopifyCustomerPrivacy()` deny everything again. |
164
- | B-611 | A built-in Consent Sink takes `mapConsent(consent, defaults)` to change how an answer becomes its platform's consent state, `defaults` being its own mapping. The unanswered default and `clear()` go through it too, so a state it always grants is granted from the start. |
157
+ | Behavior | Description |
158
+ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
159
+ | B-601 | Consent Requirements use the module's own categories; the Consent Provider translates its platform's (e.g. Cookiebot's `statistics`). |
160
+ | B-602 | `none` means the Destination always receives Events; it's for Destinations that enforce consent themselves, like GA4 Consent Mode. |
161
+ | B-603 | While consent is unanswered, Events for a gated Destination are held (up to 100, oldest dropped); once granted they're delivered in order, once denied discarded. |
162
+ | B-604 | Withdrawing consent stops delivery from that moment; it never recalls what was sent. |
163
+ | B-605 | Every consent answer is applied to each Consent Sink before Destinations receive Events under it, including an answer already given when the Flow starts. |
164
+ | B-606 | A Consent Sink named like the Consent Provider is skipped, so consent is never written back to its source. |
165
+ | B-607 | One Consent Sink failing never blocks another, or delivery. |
166
+ | B-608 | Shopify's Customer Privacy API counts once loaded; a headless store's placeholder allows everything until `consentTrackingApiLoaded`. |
167
+ | B-609 | `googleConsentMode()` denies every type but `security_storage` when first created for a data layer, waits 2 seconds for the answer, then updates with each answer: `analytics` grants `analytics_storage`, `marketing` the ad signals, `preferences` functionality and personalization storage. `security_storage` is always granted unless `mapConsent` denies it. |
168
+ | B-610 | When an answer is withdrawn back to unanswered, e.g. by a banner reset, each Consent Sink with `clear()` is told, and gated Destinations hold Events again. `googleConsentMode()` and `shopifyCustomerPrivacy()` deny everything again. |
169
+ | B-611 | A built-in Consent Sink takes `mapConsent(consent, defaults)` to change how an answer becomes its platform's consent state, `defaults` being its own mapping. The unanswered default and `clear()` go through it too, so a state it always grants is granted from the start. |
165
170
 
166
171
  ## Built-in Event Names
167
172
 
@@ -170,12 +175,12 @@ A Source's Event Names must be in the Event Catalog for it to be used (B-101). E
170
175
  | Event Name | Published by | Data |
171
176
  | ------------------ | --------------- | ----------------------------------------------------------------------- |
172
177
  | `item:select` | `selections()` | `ItemSelectData`: the Item's Data, plus `index` in its List |
173
- | `promotion:select` | `selections()` | The Promotion's Data |
174
- | `promotion:view` | `impressions()` | The Promotion's Data |
178
+ | `promotion:select` | `selections()` | `PromotionData`: the Promotion's Data, plus `items` with their `index` |
179
+ | `promotion:view` | `impressions()` | `PromotionData`: the Promotion's Data, plus `items` with their `index` |
175
180
  | `list:view` | `impressions()` | `ListViewData`: the List's Data, plus `items` with their `index` |
176
181
  | `item:view` | `detailViews()` | The detail Item's Data |
177
182
  | `page:view` | `pageViews()` | The Data of every `data-e="page"` element |
178
- | `link:click` | `clicks()` | `LinkClickData`: `url`, `text`, `outbound`, `download?` |
183
+ | `link:click` | `clicks()` | `LinkClickData`: `url`, `text` |
179
184
  | `button:click` | `clicks()` | `ButtonClickData`: `text` |
180
185
  | `form:start` | `forms()` | `FormEventData`: `id?`, `name?`, `destination?` |
181
186
  | `form:submit` | `forms()` | `FormSubmitData`: as `form:start`, plus `submitText?`; no field values |
package/docs/setup.md CHANGED
@@ -3,21 +3,8 @@
3
3
  Every Event Name the package publishes, mapped where useful, with every Detector, the Cart Source and consent. Copy it and trim what the project doesn't track. Step by step: [README](../README.md#setup).
4
4
 
5
5
  ```tsx
6
- import { cookiebot } from "@buildinams/tracking/consent/cookiebot";
7
- import { googleConsentMode } from "@buildinams/tracking/consent/google";
8
- import { shopifyCustomerPrivacy } from "@buildinams/tracking/consent/shopify";
9
- import {
10
- createDestinations,
11
- map,
12
- withConsent,
13
- } from "@buildinams/tracking/destinations";
14
- import { ga4 } from "@buildinams/tracking/destinations/ga4";
15
- import { shopify } from "@buildinams/tracking/destinations/shopify";
16
- import { createEventBroker, shape } from "@buildinams/tracking/events";
17
- import { startTracking } from "@buildinams/tracking/flow";
18
- import { createCurrentPage } from "@buildinams/tracking/page";
19
- import { createCartSource } from "@buildinams/tracking/sources/cart";
20
- import { shopifyCart } from "@buildinams/tracking/sources/cart/shopify";
6
+ import { createCartSource } from "@buildinams/tracking/cart";
7
+ import { cookiebot } from "@buildinams/tracking/cookiebot";
21
8
  import type {
22
9
  ButtonClickData,
23
10
  FormEventData,
@@ -25,8 +12,9 @@ import type {
25
12
  ItemSelectData,
26
13
  LinkClickData,
27
14
  ListViewData,
15
+ PromotionData,
28
16
  VideoEventData,
29
- } from "@buildinams/tracking/sources/dom";
17
+ } from "@buildinams/tracking/dom";
30
18
  import {
31
19
  clicks,
32
20
  createDomSource,
@@ -37,7 +25,16 @@ import {
37
25
  scroll,
38
26
  selections,
39
27
  videos,
40
- } from "@buildinams/tracking/sources/dom";
28
+ } from "@buildinams/tracking/dom";
29
+ import { createEventBroker, shape } from "@buildinams/tracking/events";
30
+ import type { Destination } from "@buildinams/tracking/flow";
31
+ import { map, startTracking } from "@buildinams/tracking/flow";
32
+ import { googleConsentMode, gtm } from "@buildinams/tracking/google";
33
+ import { createClientNavigation } from "@buildinams/tracking/navigation";
34
+ import {
35
+ shopifyCart,
36
+ shopifyCustomerPrivacy,
37
+ } from "@buildinams/tracking/shopify";
41
38
 
42
39
  type Item = { id: string; name?: string; price?: string };
43
40
  type CartLine = { id: string; quantity: number; merchandise: { id: string } };
@@ -45,8 +42,22 @@ type CartFragment = { lines: { nodes: CartLine[] } };
45
42
  type Named = { id?: string; name?: string };
46
43
  type Surroundings = { list: Named; promotion: Named; location: Named };
47
44
 
48
- // A new Page per pathname; pass `key` to count e.g. `?page=2` as one too.
49
- export const currentPage = createCurrentPage();
45
+ // For client-side navigation: a new Page per pathname; pass `key` to count e.g. `?page=2` as one too. Drop it with full page loads only.
46
+ export const clientNavigation = createClientNavigation();
47
+
48
+ declare global {
49
+ // eslint-disable-next-line @typescript-eslint/consistent-type-definitions -- declaration merging
50
+ interface Window {
51
+ Shopify?: { analytics?: { publish(name: string, payload: unknown): void } };
52
+ }
53
+ }
54
+
55
+ // Your own Destination: here Shopify's analytics bus on a theme; Hydrogen has `useAnalytics().publish`.
56
+ const shopifyAnalytics: Destination<{ name: string; payload: unknown }> = {
57
+ name: "shopify",
58
+ send: ({ name, payload }) =>
59
+ window.Shopify?.analytics?.publish(name, payload),
60
+ };
50
61
 
51
62
  export const broker = createEventBroker(
52
63
  {
@@ -56,10 +67,13 @@ export const broker = createEventBroker(
56
67
  },
57
68
  "item:view": { data: shape<Item>(), composed: shape<Surroundings>() },
58
69
  "promotion:select": {
59
- data: shape<Named>(),
70
+ data: shape<Named & PromotionData>(),
71
+ composed: shape<Surroundings>(),
72
+ },
73
+ "promotion:view": {
74
+ data: shape<Named & PromotionData>(),
60
75
  composed: shape<Surroundings>(),
61
76
  },
62
- "promotion:view": { data: shape<Named>(), composed: shape<Surroundings>() },
63
77
  "list:view": {
64
78
  data: shape<ListViewData>(),
65
79
  composed: shape<Surroundings>(),
@@ -89,11 +103,18 @@ export const broker = createEventBroker(
89
103
  "cart:remove": { data: shape<{ line: CartLine; quantity: number }>() },
90
104
  },
91
105
  // Optional; its return type becomes every Event's `context`.
92
- { context: () => ({ ...currentPage.read(), market: "nl" }) },
106
+ {
107
+ context: () => ({
108
+ url: location.href,
109
+ path: location.pathname,
110
+ referrer: clientNavigation.referrer(),
111
+ market: "nl",
112
+ }),
113
+ },
93
114
  );
94
115
 
95
- const destinations = createDestinations(broker.events, [
96
- map(withConsent(ga4(), "none"), {
116
+ const destinations = [
117
+ map(broker, gtm(), "none", {
97
118
  // The Composition decides: an Item in a Promotion but not a List is a promotion selection.
98
119
  "item:select": ({ data, composed: { list, promotion }, meta: { id } }) =>
99
120
  promotion && !list
@@ -118,11 +139,24 @@ const destinations = createDestinations(broker.events, [
118
139
  ],
119
140
  },
120
141
  },
142
+ // Outbound links only; the Mapping decides what counts as outbound.
143
+ "link:click": ({ data }) => {
144
+ const url = new URL(data.url);
145
+ return url.protocol.startsWith("http") &&
146
+ url.hostname !== location.hostname
147
+ ? { name: "click", payload: { link_url: data.url, outbound: true } }
148
+ : null;
149
+ },
150
+ // Leaves out collection pages: Mappings filter by pathname.
151
+ "page:scroll": ({ data, context }) =>
152
+ context.path.startsWith("/collections/")
153
+ ? null
154
+ : { name: "scroll", payload: { percent_scrolled: Number(data.depth) } },
121
155
  }),
122
- map(withConsent(shopify(), ["analytics"]), {
156
+ map(broker, shopifyAnalytics, ["analytics"], {
123
157
  "item:view": ({ data }) => ({ name: "product_viewed", payload: { data } }),
124
158
  }),
125
- ]);
159
+ ];
126
160
 
127
161
  export const domSource = createDomSource(
128
162
  broker,
@@ -137,9 +171,10 @@ export const domSource = createDomSource(
137
171
  scroll(),
138
172
  ],
139
173
  // Flushes Detectors when a Page ends and resets them when the next starts.
140
- { currentPage },
174
+ { clientNavigation },
141
175
  );
142
176
  // Or your own adapter: { lines: (cart) => …, key: (line) => …, quantity: (line) => … }
177
+ // Call `cartSource.setSnapshot(cart)` whenever the storefront's cart changes.
143
178
  export const cartSource = createCartSource(broker, shopifyCart<CartFragment>());
144
179
 
145
180
  // In the browser, once, e.g. in instrumentation-client.ts:
@@ -151,4 +186,4 @@ startTracking(broker, cookiebot(), destinations, {
151
186
  });
152
187
  ```
153
188
 
154
- Use `onetrust()` from `@buildinams/tracking/consent/onetrust` or `shopifyConsent()` from `@buildinams/tracking/consent/shopify` instead of `cookiebot()` for OneTrust or Shopify's privacy banner.
189
+ Use `onetrust()` from `@buildinams/tracking/onetrust` or `shopifyConsent()` from `@buildinams/tracking/shopify` instead of `cookiebot()` for OneTrust or Shopify's privacy banner.