@buildinams/tracking 0.0.0-stage → 0.1.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 +267 -2
- package/dist/chunk-KLN5K6PR.js +6 -0
- package/dist/chunk-KLN5K6PR.js.map +1 -0
- package/dist/compatibility-Dc1JmTeG.d.ts +35 -0
- package/dist/consent/cookiebot/index.d.ts +5 -0
- package/dist/consent/cookiebot/index.js +27 -0
- package/dist/consent/cookiebot/index.js.map +1 -0
- package/dist/consent/index.d.ts +18 -0
- package/dist/consent/index.js +3 -0
- package/dist/consent/index.js.map +1 -0
- package/dist/consent/onetrust/index.d.ts +9 -0
- package/dist/consent/onetrust/index.js +35 -0
- package/dist/consent/onetrust/index.js.map +1 -0
- package/dist/consent/shopify/index.d.ts +13 -0
- package/dist/consent/shopify/index.js +77 -0
- package/dist/consent/shopify/index.js.map +1 -0
- package/dist/destinations/ga4/index.d.ts +16 -0
- package/dist/destinations/ga4/index.js +15 -0
- package/dist/destinations/ga4/index.js.map +1 -0
- package/dist/destinations/index.d.ts +9 -0
- package/dist/destinations/index.js +17 -0
- package/dist/destinations/index.js.map +1 -0
- package/dist/destinations/shopify/index.d.ts +12 -0
- package/dist/destinations/shopify/index.js +18 -0
- package/dist/destinations/shopify/index.js.map +1 -0
- package/dist/events/index.d.ts +16 -0
- package/dist/events/index.js +77 -0
- package/dist/events/index.js.map +1 -0
- package/dist/flow/index.d.ts +16 -0
- package/dist/flow/index.js +82 -0
- package/dist/flow/index.js.map +1 -0
- package/dist/page/index.d.ts +27 -0
- package/dist/page/index.js +56 -0
- package/dist/page/index.js.map +1 -0
- package/dist/sources/cart/index.d.ts +27 -0
- package/dist/sources/cart/index.js +38 -0
- package/dist/sources/cart/index.js.map +1 -0
- package/dist/sources/cart/shopify/index.d.ts +28 -0
- package/dist/sources/cart/shopify/index.js +16 -0
- package/dist/sources/cart/shopify/index.js.map +1 -0
- package/dist/sources/dom/index.d.ts +190 -0
- package/dist/sources/dom/index.js +558 -0
- package/dist/sources/dom/index.js.map +1 -0
- package/dist/sources/index.d.ts +6 -0
- package/dist/sources/index.js +3 -0
- package/dist/sources/index.js.map +1 -0
- package/dist/types-BfJsv8AV.d.ts +30 -0
- package/dist/types-DfPz7mBl.d.ts +49 -0
- package/docs/decisions/001-vendor-neutral-event-pipeline.md +33 -0
- package/docs/events.md +186 -0
- package/package.json +141 -5
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import { ConsentRequirement } from './consent/index.js';
|
|
2
|
+
import { C as Catalog, T as TrackingEvent, a as EventName, B as BrokerEvents } from './types-DfPz7mBl.js';
|
|
3
|
+
|
|
4
|
+
type DestinationEvent = {
|
|
5
|
+
name: string;
|
|
6
|
+
payload: unknown;
|
|
7
|
+
};
|
|
8
|
+
type Destination<E extends DestinationEvent = DestinationEvent> = {
|
|
9
|
+
name: string;
|
|
10
|
+
send(event: E): void | Promise<void>;
|
|
11
|
+
};
|
|
12
|
+
type ConsentedDestination<E extends DestinationEvent> = {
|
|
13
|
+
destination: Destination<E>;
|
|
14
|
+
requires: ConsentRequirement;
|
|
15
|
+
};
|
|
16
|
+
type Mapping<C extends Catalog, E extends DestinationEvent, Cx> = {
|
|
17
|
+
[N in EventName<C>]?: (event: TrackingEvent<C, N, Cx>) => E | null | undefined;
|
|
18
|
+
};
|
|
19
|
+
type MappedDestination<C extends Catalog, Cx = unknown> = {
|
|
20
|
+
name: string;
|
|
21
|
+
requires: ConsentRequirement;
|
|
22
|
+
/** Maps and sends; `false` when the Event has no Mapping or it returned nothing. */
|
|
23
|
+
deliver(event: TrackingEvent<C, EventName<C>, Cx>): false | void | Promise<void>;
|
|
24
|
+
};
|
|
25
|
+
type Destinations<C extends Catalog, Cx = unknown> = {
|
|
26
|
+
readonly events: BrokerEvents<C, Cx>;
|
|
27
|
+
readonly mapped: readonly MappedDestination<C, Cx>[];
|
|
28
|
+
};
|
|
29
|
+
|
|
30
|
+
export type { ConsentedDestination as C, Destinations as D, MappedDestination as M, DestinationEvent as a, Mapping as b, Destination as c };
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
declare const SHAPE: unique symbol;
|
|
2
|
+
declare const CONTEXT: unique symbol;
|
|
3
|
+
type Shape<T> = {
|
|
4
|
+
readonly [SHAPE]?: T;
|
|
5
|
+
};
|
|
6
|
+
type CatalogEntry = {
|
|
7
|
+
data: Shape<unknown>;
|
|
8
|
+
composed?: Shape<Record<string, unknown>>;
|
|
9
|
+
};
|
|
10
|
+
type Catalog = Record<string, CatalogEntry>;
|
|
11
|
+
type ShapeOf<S> = S extends Shape<infer T> ? T : never;
|
|
12
|
+
type EventName<C extends Catalog> = keyof C & string;
|
|
13
|
+
type EventData<C extends Catalog, N extends EventName<C>> = ShapeOf<C[N]["data"]>;
|
|
14
|
+
type Composition<C extends Catalog, N extends EventName<C>> = C[N] extends {
|
|
15
|
+
composed: infer S;
|
|
16
|
+
} ? {
|
|
17
|
+
[R in keyof ShapeOf<S>]?: {
|
|
18
|
+
data: ShapeOf<S>[R];
|
|
19
|
+
};
|
|
20
|
+
} : Record<never, never>;
|
|
21
|
+
type EventMeta = {
|
|
22
|
+
id: string;
|
|
23
|
+
timestamp: number;
|
|
24
|
+
seq: number;
|
|
25
|
+
};
|
|
26
|
+
type TrackingEvent<C extends Catalog, N extends EventName<C> = EventName<C>, Cx = unknown> = {
|
|
27
|
+
[K in N]: {
|
|
28
|
+
readonly name: K;
|
|
29
|
+
readonly data: EventData<C, K>;
|
|
30
|
+
readonly composed: Readonly<Composition<C, K>>;
|
|
31
|
+
readonly context: Readonly<Cx>;
|
|
32
|
+
readonly meta: Readonly<EventMeta>;
|
|
33
|
+
};
|
|
34
|
+
}[N];
|
|
35
|
+
type SubscribeOptions = {
|
|
36
|
+
/** Receive the Events held while nobody asked for replay first. */
|
|
37
|
+
replay?: boolean;
|
|
38
|
+
};
|
|
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
|
+
type EventBroker<C extends Catalog, Cx = unknown> = {
|
|
44
|
+
readonly events: BrokerEvents<C, Cx>;
|
|
45
|
+
publish<N extends EventName<C>>(name: N, data: EventData<C, N>, composed?: Composition<C, N>): void;
|
|
46
|
+
subscribe(listener: (event: TrackingEvent<C, EventName<C>, Cx>) => void, options?: SubscribeOptions): () => void;
|
|
47
|
+
};
|
|
48
|
+
|
|
49
|
+
export type { BrokerEvents as B, Catalog as C, EventBroker as E, Shape as S, TrackingEvent as T, EventName as a, EventData as b, CatalogEntry as c, Composition as d, EventMeta as e, SubscribeOptions as f };
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Vendor-neutral events, mapped per Destination
|
|
2
|
+
|
|
3
|
+
Date: 2026-11-13
|
|
4
|
+
|
|
5
|
+
Status: proposed
|
|
6
|
+
|
|
7
|
+
## Context
|
|
8
|
+
|
|
9
|
+
The same shopper action feeds several Destinations (GA4, Shopify Analytics) with different event names, schemas and consent needs. Ecommerce reports are only useful with an action's surroundings: which List, Promotion and Location an Item sat in. Passing those by hand through every component is where tracking usually breaks.
|
|
10
|
+
|
|
11
|
+
Options considered:
|
|
12
|
+
|
|
13
|
+
- **Vendor calls in components** (`gtag(...)`, `Shopify.analytics.publish(...)`). Every component knows every vendor schema, consent is checked in N places, and adding a Destination touches the whole codebase.
|
|
14
|
+
- **GTM's `dataLayer` as the hub.** Untyped and GA4-shaped, with mapping logic in a GTM container outside version control and review.
|
|
15
|
+
- **A hosted CDP** (Segment, RudderStack). Cost and a third party in the data path for what is mostly fan-out to two Destinations.
|
|
16
|
+
- **Composition through React context.** Needs client components around every List and Item, and misses markup rendered by server components or a CMS.
|
|
17
|
+
|
|
18
|
+
## Decision
|
|
19
|
+
|
|
20
|
+
One in-page pipeline, described in [events.md](../events.md):
|
|
21
|
+
|
|
22
|
+
- **Sources publish vendor-neutral Events** declared in a typed Event Catalog to a Broker, which stamps their Meta and Context and keeps them in order.
|
|
23
|
+
- **The Broker only publishes and subscribes.** The Current Page provides Context and tells Sources when the Page changes, and the Flow starts the Sources, so the Broker knows neither pages nor Sources.
|
|
24
|
+
- **Each Event is mapped per Destination,** gated by that Destination's Consent Requirement. Vendor names and fields exist only in Mappings.
|
|
25
|
+
- **Composition comes from Annotations** (`data-e`, `data-e-data`) in the rendered markup, not from component props or context.
|
|
26
|
+
- **The cart is observed through Snapshots,** not add and remove calls, so it works with any cart state the storefront already has.
|
|
27
|
+
|
|
28
|
+
## Consequences
|
|
29
|
+
|
|
30
|
+
- Adding or removing a Destination is a Mapping plus its adapter; no Source or component changes.
|
|
31
|
+
- Annotations are part of the analytics contract: renaming or removing a `data-e` attribute silently changes reports, so annotated markup needs the care of an API.
|
|
32
|
+
- Catalog shapes aren't validated at runtime, and DOM-derived Data is strings, so Mappings must tolerate missing or loosely typed fields.
|
|
33
|
+
- A CDP can still be added later as one more Destination.
|
package/docs/events.md
ADDED
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
# Events module
|
|
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).
|
|
4
|
+
|
|
5
|
+
## Non-goals
|
|
6
|
+
|
|
7
|
+
- **Sending from the server.** Events are collected and delivered in the browser only.
|
|
8
|
+
- **Loading vendor scripts.** A Destination delivers to a vendor script the project already loads.
|
|
9
|
+
- **Deciding consent.** The module reads consent from a Consent Provider; it never shows a banner or stores an answer.
|
|
10
|
+
- **Tracking without Annotations.** Nothing in the markup is tracked unless an Annotation asks for it.
|
|
11
|
+
- **Validating Data at runtime.** Catalog shapes exist only in the types.
|
|
12
|
+
- **Persisting across page loads.** Events still held when the document unloads are lost.
|
|
13
|
+
|
|
14
|
+
## Glossary
|
|
15
|
+
|
|
16
|
+
### Events
|
|
17
|
+
|
|
18
|
+
| Term | Definition | Avoid |
|
|
19
|
+
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
|
|
20
|
+
| Event | A record of one thing a shopper did or saw, made of its Event Name, Data, Composition, Context and Meta. | Hit, tag, track call |
|
|
21
|
+
| Event Name | The `subject:action` identifier of an Event, e.g. `item:select`. Describes the shopper's action, never a vendor's event name. | Event type, action |
|
|
22
|
+
| Event Catalog | The single list of every Event Name the storefront may emit, with the shape of its Data and Composition. | Schema, registry |
|
|
23
|
+
| Data | The subject of an Event: the thing acted upon, such as a product variant or a form. | Payload, properties |
|
|
24
|
+
| Composition | The named surroundings the subject sat inside when the Event happened, such as its List, Promotion and Location. Each entry carries its own Data. | Parents, ancestors, container |
|
|
25
|
+
| Context | Facts about the browsing situation rather than the subject, such as current page and referrer. Its shape is the project's. | Environment, page data |
|
|
26
|
+
| Meta | The identity and ordering of an Event: its Event ID, Timestamp and Sequence Number. | |
|
|
27
|
+
| Event ID | The unique identifier of one Event, reused by every Destination so duplicates can be detected downstream. | Hit ID |
|
|
28
|
+
| Sequence Number | The position of an Event in the order the Broker accepted it. | Index, counter |
|
|
29
|
+
|
|
30
|
+
### Composition roles
|
|
31
|
+
|
|
32
|
+
| Term | Definition | Avoid |
|
|
33
|
+
| --------- | ----------------------------------------------------------------------------- | ---------------------------- |
|
|
34
|
+
| Location | A named region of a page, such as a content block or section. | Section, block, slot |
|
|
35
|
+
| List | An ordered collection of Items shown together, such as a product grid. | Collection (Shopify's), grid |
|
|
36
|
+
| Item | A single product (variant) shown or acted upon. | Product card, tile |
|
|
37
|
+
| Promotion | Marketing content that frames an Item or Location, such as a campaign banner. | Campaign, banner |
|
|
38
|
+
| Form | A shopper-facing form whose submission is an Event, e.g. a newsletter signup. | |
|
|
39
|
+
|
|
40
|
+
### Pipeline
|
|
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 |
|
|
57
|
+
|
|
58
|
+
### Delivery
|
|
59
|
+
|
|
60
|
+
| Term | Definition | Avoid |
|
|
61
|
+
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
|
|
62
|
+
| Destination | An external analytics service Events are delivered to, such as GA4 or Shopify Analytics. | Sink, integration, provider, vendor |
|
|
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 |
|
|
65
|
+
| Consent Requirement | The consent categories a Destination needs before it may receive Events; `none` means always. | Permission, gate |
|
|
66
|
+
| Consent Provider | The consent management platform that reports which categories the shopper granted, such as Cookiebot. | CMP adapter, cookie banner |
|
|
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 |
|
|
68
|
+
| Flow | The running pipeline connecting the Broker, the Sources, the Mapped Destinations and the Consent Provider; `startTracking()` starts it. | Analytics instance, pipeline |
|
|
69
|
+
|
|
70
|
+
## Behavior rules
|
|
71
|
+
|
|
72
|
+
### Lifecycle + SSR
|
|
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. |
|
|
85
|
+
|
|
86
|
+
### Events and the Catalog
|
|
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. |
|
|
94
|
+
|
|
95
|
+
### Broker
|
|
96
|
+
|
|
97
|
+
| Behavior | Description |
|
|
98
|
+
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
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
|
+
| 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. |
|
|
103
|
+
| B-204 | Every subscriber receives Events in Sequence Number order. |
|
|
104
|
+
|
|
105
|
+
### DOM Source
|
|
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. |
|
|
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), once per Item it shows, including when the same element shows another Item after a navigation. |
|
|
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. |
|
|
128
|
+
|
|
129
|
+
### Cart Source
|
|
130
|
+
|
|
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. |
|
|
138
|
+
|
|
139
|
+
### Destinations
|
|
140
|
+
|
|
141
|
+
| Behavior | Description |
|
|
142
|
+
| -------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
|
143
|
+
| B-501 | A Mapping is a pure function from one Event to zero or one Destination event `{ name, payload }`; returning nothing skips it. |
|
|
144
|
+
| B-502 | An Event without a Mapping for a Destination is never sent to it. |
|
|
145
|
+
| B-503 | Mappings produce the Destination's native names and fields; vendor knowledge lives only in Mappings and Destinations. |
|
|
146
|
+
| B-504 | Mappings pass the Event ID through wherever the Destination supports a dedupe key. |
|
|
147
|
+
| B-505 | One Destination failing never blocks or fails another. |
|
|
148
|
+
|
|
149
|
+
### Consent
|
|
150
|
+
|
|
151
|
+
| Behavior | Description |
|
|
152
|
+
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
153
|
+
| B-601 | Consent Requirements use the module's own categories; the Consent Provider translates its platform's (e.g. Cookiebot's `statistics`). |
|
|
154
|
+
| B-602 | `none` means the Destination always receives Events; it's for Destinations that enforce consent themselves, like GA4 Consent Mode. |
|
|
155
|
+
| 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. |
|
|
156
|
+
| B-604 | Withdrawing consent stops delivery from that moment; it never recalls what was sent. |
|
|
157
|
+
| 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. |
|
|
158
|
+
| B-606 | A Consent Sink named like the Consent Provider is skipped, so consent is never written back to its source. |
|
|
159
|
+
| B-607 | One Consent Sink failing never blocks another, or delivery. |
|
|
160
|
+
|
|
161
|
+
## Built-in Event Names
|
|
162
|
+
|
|
163
|
+
A Source's Event Names must be in the Event Catalog for it to be used (B-101). Each element's own Annotation Data is merged into the derived Data (B-310).
|
|
164
|
+
|
|
165
|
+
| Event Name | Published by | Data |
|
|
166
|
+
| ------------------ | --------------- | ----------------------------------------------------------------------- |
|
|
167
|
+
| `item:select` | `selections()` | `ItemSelectData`: the Item's Data, plus `index` in its List |
|
|
168
|
+
| `promotion:select` | `selections()` | The Promotion's Data |
|
|
169
|
+
| `promotion:view` | `impressions()` | The Promotion's Data |
|
|
170
|
+
| `list:view` | `impressions()` | `ListViewData`: the List's Data, plus `items` with their `index` |
|
|
171
|
+
| `item:view` | `detailViews()` | The detail Item's Data |
|
|
172
|
+
| `page:view` | `pageViews()` | The Data of every `data-e="page"` element |
|
|
173
|
+
| `link:click` | `clicks()` | `LinkClickData`: `url`, `text`, `outbound`, `download?` |
|
|
174
|
+
| `button:click` | `clicks()` | `ButtonClickData`: `text` |
|
|
175
|
+
| `form:start` | `forms()` | `FormEventData`: `id?`, `name?`, `destination?` |
|
|
176
|
+
| `form:submit` | `forms()` | `FormSubmitData`: as `form:start`, plus `submitText?`; no field values |
|
|
177
|
+
| `video:start` | `videos()` | `VideoEventData`: `url`, `title?`, `duration`, `currentTime`, `percent` |
|
|
178
|
+
| `video:progress` | `videos()` | `VideoEventData`, `percent` being the threshold reached |
|
|
179
|
+
| `video:complete` | `videos()` | `VideoEventData` |
|
|
180
|
+
| `page:scroll` | `scroll()` | `{ depth }`, the threshold reached |
|
|
181
|
+
| `cart:add` | Cart Source | `{ line, quantity }`, quantity added |
|
|
182
|
+
| `cart:remove` | Cart Source | `{ line, quantity }`, quantity removed |
|
|
183
|
+
|
|
184
|
+
## Open questions
|
|
185
|
+
|
|
186
|
+
- **Embedded players.** `videos()` covers `<video>` elements; YouTube and Vimeo embeds need their players' APIs.
|
package/package.json
CHANGED
|
@@ -1,6 +1,142 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
2
|
+
"name": "@buildinams/tracking",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"sideEffects": false,
|
|
6
|
+
"author": "Build in Amsterdam <development@buildinamsterdam.com> (https://www.buildinamsterdam.com/)",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "https://github.com/buildinamsterdam/bia-shared.git"
|
|
10
|
+
},
|
|
11
|
+
"bugs": {
|
|
12
|
+
"url": "https://github.com/buildinamsterdam/bia-shared/issues"
|
|
13
|
+
},
|
|
14
|
+
"publishConfig": {
|
|
15
|
+
"registry": "https://registry.npmjs.org",
|
|
16
|
+
"access": "public"
|
|
17
|
+
},
|
|
18
|
+
"scripts": {
|
|
19
|
+
"build": "tsup",
|
|
20
|
+
"dev": "tsup --watch",
|
|
21
|
+
"lint": "eslint .",
|
|
22
|
+
"typecheck": "tsc --noEmit",
|
|
23
|
+
"test": "vitest watch",
|
|
24
|
+
"test:ci": "vitest run",
|
|
25
|
+
"lint:fix": "eslint . --fix"
|
|
26
|
+
},
|
|
27
|
+
"exports": {
|
|
28
|
+
"./events": {
|
|
29
|
+
"types": "./dist/events/index.d.ts",
|
|
30
|
+
"default": "./dist/events/index.js"
|
|
31
|
+
},
|
|
32
|
+
"./page": {
|
|
33
|
+
"types": "./dist/page/index.d.ts",
|
|
34
|
+
"default": "./dist/page/index.js"
|
|
35
|
+
},
|
|
36
|
+
"./flow": {
|
|
37
|
+
"types": "./dist/flow/index.d.ts",
|
|
38
|
+
"default": "./dist/flow/index.js"
|
|
39
|
+
},
|
|
40
|
+
"./sources": {
|
|
41
|
+
"types": "./dist/sources/index.d.ts",
|
|
42
|
+
"default": "./dist/sources/index.js"
|
|
43
|
+
},
|
|
44
|
+
"./sources/dom": {
|
|
45
|
+
"types": "./dist/sources/dom/index.d.ts",
|
|
46
|
+
"default": "./dist/sources/dom/index.js"
|
|
47
|
+
},
|
|
48
|
+
"./sources/cart": {
|
|
49
|
+
"types": "./dist/sources/cart/index.d.ts",
|
|
50
|
+
"default": "./dist/sources/cart/index.js"
|
|
51
|
+
},
|
|
52
|
+
"./sources/cart/shopify": {
|
|
53
|
+
"types": "./dist/sources/cart/shopify/index.d.ts",
|
|
54
|
+
"default": "./dist/sources/cart/shopify/index.js"
|
|
55
|
+
},
|
|
56
|
+
"./consent": {
|
|
57
|
+
"types": "./dist/consent/index.d.ts",
|
|
58
|
+
"default": "./dist/consent/index.js"
|
|
59
|
+
},
|
|
60
|
+
"./consent/cookiebot": {
|
|
61
|
+
"types": "./dist/consent/cookiebot/index.d.ts",
|
|
62
|
+
"default": "./dist/consent/cookiebot/index.js"
|
|
63
|
+
},
|
|
64
|
+
"./consent/onetrust": {
|
|
65
|
+
"types": "./dist/consent/onetrust/index.d.ts",
|
|
66
|
+
"default": "./dist/consent/onetrust/index.js"
|
|
67
|
+
},
|
|
68
|
+
"./consent/shopify": {
|
|
69
|
+
"types": "./dist/consent/shopify/index.d.ts",
|
|
70
|
+
"default": "./dist/consent/shopify/index.js"
|
|
71
|
+
},
|
|
72
|
+
"./destinations": {
|
|
73
|
+
"types": "./dist/destinations/index.d.ts",
|
|
74
|
+
"default": "./dist/destinations/index.js"
|
|
75
|
+
},
|
|
76
|
+
"./destinations/ga4": {
|
|
77
|
+
"types": "./dist/destinations/ga4/index.d.ts",
|
|
78
|
+
"default": "./dist/destinations/ga4/index.js"
|
|
79
|
+
},
|
|
80
|
+
"./destinations/shopify": {
|
|
81
|
+
"types": "./dist/destinations/shopify/index.d.ts",
|
|
82
|
+
"default": "./dist/destinations/shopify/index.js"
|
|
83
|
+
}
|
|
84
|
+
},
|
|
85
|
+
"typesVersions": {
|
|
86
|
+
"*": {
|
|
87
|
+
"./events": [
|
|
88
|
+
"./dist/events/index.d.ts"
|
|
89
|
+
],
|
|
90
|
+
"./page": [
|
|
91
|
+
"./dist/page/index.d.ts"
|
|
92
|
+
],
|
|
93
|
+
"./flow": [
|
|
94
|
+
"./dist/flow/index.d.ts"
|
|
95
|
+
],
|
|
96
|
+
"./sources": [
|
|
97
|
+
"./dist/sources/index.d.ts"
|
|
98
|
+
],
|
|
99
|
+
"./sources/dom": [
|
|
100
|
+
"./dist/sources/dom/index.d.ts"
|
|
101
|
+
],
|
|
102
|
+
"./sources/cart": [
|
|
103
|
+
"./dist/sources/cart/index.d.ts"
|
|
104
|
+
],
|
|
105
|
+
"./sources/cart/shopify": [
|
|
106
|
+
"./dist/sources/cart/shopify/index.d.ts"
|
|
107
|
+
],
|
|
108
|
+
"./consent": [
|
|
109
|
+
"./dist/consent/index.d.ts"
|
|
110
|
+
],
|
|
111
|
+
"./consent/cookiebot": [
|
|
112
|
+
"./dist/consent/cookiebot/index.d.ts"
|
|
113
|
+
],
|
|
114
|
+
"./consent/onetrust": [
|
|
115
|
+
"./dist/consent/onetrust/index.d.ts"
|
|
116
|
+
],
|
|
117
|
+
"./consent/shopify": [
|
|
118
|
+
"./dist/consent/shopify/index.d.ts"
|
|
119
|
+
],
|
|
120
|
+
"./destinations": [
|
|
121
|
+
"./dist/destinations/index.d.ts"
|
|
122
|
+
],
|
|
123
|
+
"./destinations/ga4": [
|
|
124
|
+
"./dist/destinations/ga4/index.d.ts"
|
|
125
|
+
],
|
|
126
|
+
"./destinations/shopify": [
|
|
127
|
+
"./dist/destinations/shopify/index.d.ts"
|
|
128
|
+
]
|
|
129
|
+
}
|
|
130
|
+
},
|
|
131
|
+
"files": [
|
|
132
|
+
"dist",
|
|
133
|
+
"docs"
|
|
134
|
+
],
|
|
135
|
+
"devDependencies": {
|
|
136
|
+
"@buildinams/lint": "^0.4.0",
|
|
137
|
+
"jsdom": "^27.4.0",
|
|
138
|
+
"tsup": "^8.0.1",
|
|
139
|
+
"typescript": "^5.4.5",
|
|
140
|
+
"vitest": "^5.1.0"
|
|
141
|
+
}
|
|
142
|
+
}
|