@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.
- package/README.md +72 -83
- package/dist/{sources/cart → cart}/index.d.ts +4 -4
- package/dist/{sources/cart → cart}/index.js +13 -3
- package/dist/cart/index.js.map +1 -0
- package/dist/chunk-JZ6HFGVJ.js +163 -0
- package/dist/chunk-JZ6HFGVJ.js.map +1 -0
- package/dist/{compatibility-Dc1JmTeG.d.ts → compatibility-wHn2I_ws.d.ts} +2 -2
- package/dist/{consent/index.d.ts → consent-types-DgKtGapr.d.ts} +1 -1
- package/dist/{consent/cookiebot → cookiebot}/index.d.ts +1 -1
- package/dist/{consent/cookiebot → cookiebot}/index.js +1 -1
- package/dist/cookiebot/index.js.map +1 -0
- package/dist/destination-types-DNMBOW_e.d.ts +22 -0
- package/dist/devtools/index.d.ts +18 -0
- package/dist/devtools/index.js +299 -0
- package/dist/devtools/index.js.map +1 -0
- package/dist/{sources/dom → dom}/index.d.ts +28 -38
- package/dist/{sources/dom → dom}/index.js +123 -245
- package/dist/dom/index.js.map +1 -0
- package/dist/events/index.d.ts +3 -6
- package/dist/events/index.js +5 -4
- package/dist/events/index.js.map +1 -1
- package/dist/flow/index.d.ts +10 -8
- package/dist/flow/index.js +16 -4
- package/dist/flow/index.js.map +1 -1
- package/dist/{consent/google → google}/index.d.ts +15 -2
- package/dist/{consent/google → google}/index.js +19 -6
- package/dist/google/index.js.map +1 -0
- package/dist/{page → navigation}/index.d.ts +7 -12
- package/dist/{page → navigation}/index.js +4 -10
- package/dist/navigation/index.js.map +1 -0
- package/dist/{consent/onetrust → onetrust}/index.d.ts +1 -1
- package/dist/{consent/onetrust → onetrust}/index.js +1 -1
- package/dist/onetrust/index.js.map +1 -0
- package/dist/shopify/index.d.ts +45 -0
- package/dist/{consent/shopify → shopify}/index.js +18 -5
- package/dist/shopify/index.js.map +1 -0
- package/dist/{sources/index.d.ts → source-types-fJXZeF2Q.d.ts} +1 -1
- package/dist/{types-DfPz7mBl.d.ts → types-CZEg03xW.d.ts} +3 -7
- package/docs/annotations.md +72 -22
- package/docs/context.md +14 -14
- package/docs/decisions/001-vendor-neutral-event-pipeline.md +2 -2
- package/docs/decisions/002-data-per-annotation-word.md +34 -0
- package/docs/events.md +86 -81
- package/docs/setup.md +63 -28
- package/package.json +41 -76
- package/dist/chunk-MRBVRDP6.js +0 -6
- package/dist/chunk-MRBVRDP6.js.map +0 -1
- package/dist/consent/cookiebot/index.js.map +0 -1
- package/dist/consent/google/index.js.map +0 -1
- package/dist/consent/index.js +0 -3
- package/dist/consent/index.js.map +0 -1
- package/dist/consent/onetrust/index.js.map +0 -1
- package/dist/consent/shopify/index.d.ts +0 -19
- package/dist/consent/shopify/index.js.map +0 -1
- package/dist/destinations/ga4/index.d.ts +0 -16
- package/dist/destinations/ga4/index.js +0 -17
- package/dist/destinations/ga4/index.js.map +0 -1
- package/dist/destinations/index.d.ts +0 -9
- package/dist/destinations/index.js +0 -17
- package/dist/destinations/index.js.map +0 -1
- package/dist/destinations/shopify/index.d.ts +0 -12
- package/dist/destinations/shopify/index.js +0 -18
- package/dist/destinations/shopify/index.js.map +0 -1
- package/dist/page/index.js.map +0 -1
- package/dist/sources/cart/index.js.map +0 -1
- package/dist/sources/cart/shopify/index.d.ts +0 -28
- package/dist/sources/cart/shopify/index.js +0 -16
- package/dist/sources/cart/shopify/index.js.map +0 -1
- package/dist/sources/dom/index.js.map +0 -1
- package/dist/sources/index.js +0 -3
- package/dist/sources/index.js.map +0 -1
- package/dist/types-BfJsv8AV.d.ts +0 -30
package/docs/events.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Events module
|
|
2
2
|
|
|
3
|
-
|
|
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
|
|
43
|
-
| ----------------- |
|
|
44
|
-
| Broker | The in-page hub that accepts Events from Sources, stamps their Meta and Context, and hands them on in order.
|
|
45
|
-
| Source | Anything that observes part of the storefront and publishes Events to the Broker.
|
|
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.
|
|
48
|
-
| Annotation | Markup that declares an element's Roles, Flags and Data (`data-e`, `data-e
|
|
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.
|
|
51
|
-
| Impression | A Promotion, or an Item in a List, becoming visible to the shopper for the first time on a Page.
|
|
52
|
-
| Page | One visit to a URL as the shopper experiences it, including client-side navigations.
|
|
53
|
-
|
|
|
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.
|
|
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.
|
|
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
|
|
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 | `
|
|
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
|
|
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
|
|
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
|
|
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
|
|
111
|
-
| B-303 |
|
|
112
|
-
| B-304 | Composition is built by walking up from the target, taking the nearest Annotated Element of each
|
|
113
|
-
| B-305 | A
|
|
114
|
-
| B-306 | An Impression
|
|
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`
|
|
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 |
|
|
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
|
|
123
|
-
| B-315 | A link or button click in a Promotion outside any Item publishes `promotion:select
|
|
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
|
|
126
|
-
| B-
|
|
127
|
-
| B-
|
|
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
|
|
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 | `
|
|
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
|
|
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()` |
|
|
174
|
-
| `promotion:view` | `impressions()` |
|
|
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
|
|
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 {
|
|
7
|
-
import {
|
|
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/
|
|
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/
|
|
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
|
-
//
|
|
49
|
-
export const
|
|
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
|
-
{
|
|
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 =
|
|
96
|
-
map(
|
|
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(
|
|
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
|
-
{
|
|
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/
|
|
189
|
+
Use `onetrust()` from `@buildinams/tracking/onetrust` or `shopifyConsent()` from `@buildinams/tracking/shopify` instead of `cookiebot()` for OneTrust or Shopify's privacy banner.
|