@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
|
@@ -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
|
-
|
|
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 {
|
|
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 };
|
package/docs/annotations.md
CHANGED
|
@@ -1,54 +1,104 @@
|
|
|
1
1
|
# Annotations
|
|
2
2
|
|
|
3
|
-
Nothing
|
|
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
|
|
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-
|
|
11
|
-
<article data-e="item" data-e-
|
|
12
|
-
<h3 data-e-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
<
|
|
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
|
-
|
|
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
|
-
|
|
43
|
+
```ts
|
|
44
|
+
// A variant switch isn't a new product view.
|
|
45
|
+
detailViews({ key: (data) => data.handle });
|
|
46
|
+
```
|
|
30
47
|
|
|
31
|
-
##
|
|
48
|
+
## Lists
|
|
32
49
|
|
|
33
|
-
|
|
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
|
-
<
|
|
53
|
+
<ul data-e="list" data-e-list="id:all;offset:24"></ul>
|
|
37
54
|
```
|
|
38
55
|
|
|
39
|
-
|
|
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
|
-
|
|
58
|
+
```tsx
|
|
59
|
+
<li data-e-clone={isClone} data-e="item" data-e-item={encodeData({ id })}>
|
|
60
|
+
```
|
|
44
61
|
|
|
45
|
-
|
|
62
|
+
## Clicks, forms and videos
|
|
46
63
|
|
|
47
|
-
|
|
64
|
+
Opt in per element with a Flag, or per area with `data-e-auto`:
|
|
48
65
|
|
|
49
|
-
|
|
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
|
-
|
|
53
|
-
|
|
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`
|
|
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 {
|
|
7
|
+
import { createClientNavigation } from "@buildinams/tracking/navigation";
|
|
8
8
|
|
|
9
|
-
|
|
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
|
-
|
|
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 =
|
|
34
|
-
map(
|
|
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
|
-
-
|
|
62
|
-
-
|
|
63
|
-
-
|
|
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
|
|
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
|
|
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.
|