@buildinams/tracking 0.1.0 → 0.3.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 +95 -206
- package/dist/chunk-MRBVRDP6.js +6 -0
- package/dist/chunk-MRBVRDP6.js.map +1 -0
- package/dist/consent/google/index.d.ts +19 -0
- package/dist/consent/google/index.js +53 -0
- package/dist/consent/google/index.js.map +1 -0
- package/dist/consent/index.d.ts +5 -1
- package/dist/consent/shopify/index.d.ts +11 -5
- package/dist/consent/shopify/index.js +53 -22
- package/dist/consent/shopify/index.js.map +1 -1
- package/dist/destinations/ga4/index.js +5 -3
- package/dist/destinations/ga4/index.js.map +1 -1
- package/dist/flow/index.js +7 -5
- package/dist/flow/index.js.map +1 -1
- package/dist/sources/dom/index.d.ts +19 -3
- package/dist/sources/dom/index.js +74 -11
- package/dist/sources/dom/index.js.map +1 -1
- package/docs/annotations.md +54 -0
- package/docs/context.md +64 -0
- package/docs/events.md +23 -18
- package/docs/setup.md +154 -0
- package/package.json +8 -1
package/docs/context.md
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Context
|
|
2
|
+
|
|
3
|
+
`context` is any function; its return type becomes every Event's `context`, typed in Mappings. Without it, `context` is `undefined`. Spread `currentPage.read()` into your own to add project data, such as the user:
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
// src/tracking/context.ts
|
|
7
|
+
import { createCurrentPage } from "@buildinams/tracking/page";
|
|
8
|
+
|
|
9
|
+
// The one Current Page: also pass it to `createDomSource()` and call its `sync()`.
|
|
10
|
+
export const currentPage = createCurrentPage();
|
|
11
|
+
|
|
12
|
+
type User =
|
|
13
|
+
| { loggedIn: true; id: string; tier: "member" | "vip" }
|
|
14
|
+
| { loggedIn: false };
|
|
15
|
+
|
|
16
|
+
let user: User = { loggedIn: false };
|
|
17
|
+
|
|
18
|
+
/** Called by the app whenever the session changes. */
|
|
19
|
+
export const setTrackingUser = (next: User) => {
|
|
20
|
+
user = next;
|
|
21
|
+
};
|
|
22
|
+
|
|
23
|
+
export const readContext = () => ({
|
|
24
|
+
...currentPage.read(),
|
|
25
|
+
user,
|
|
26
|
+
market: document.documentElement.dataset.market ?? "default",
|
|
27
|
+
});
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
const broker = createEventBroker(catalog, { context: readContext });
|
|
32
|
+
|
|
33
|
+
const destinations = createDestinations(broker.events, [
|
|
34
|
+
map(withConsent(ga4(), "none"), {
|
|
35
|
+
"item:select": ({ data, context: { user } }) => ({
|
|
36
|
+
name: "select_item",
|
|
37
|
+
payload: {
|
|
38
|
+
user_id: user.loggedIn ? user.id : undefined,
|
|
39
|
+
items: [{ item_id: data.id }],
|
|
40
|
+
},
|
|
41
|
+
}),
|
|
42
|
+
}),
|
|
43
|
+
]);
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
```tsx
|
|
47
|
+
// Wherever the session lives
|
|
48
|
+
const TrackingUser = () => {
|
|
49
|
+
const session = useSession();
|
|
50
|
+
useEffect(() => {
|
|
51
|
+
setTrackingUser(
|
|
52
|
+
session
|
|
53
|
+
? { loggedIn: true, id: session.id, tier: session.tier }
|
|
54
|
+
: { loggedIn: false },
|
|
55
|
+
);
|
|
56
|
+
}, [session]);
|
|
57
|
+
return null;
|
|
58
|
+
};
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
- **Read on publish.** Each Event keeps the Context of the moment it happened, also while it waits for consent; a login mid-visit shows from the next Event on.
|
|
62
|
+
- **Synchronous.** The reader runs inside `publish()`; keep async data, like a fetched profile, in a variable it returns, as `setTrackingUser` does.
|
|
63
|
+
- **Only what Mappings send leaves the page.** Context isn't forwarded by itself: each Mapping picks the fields its Destination gets, behind that Destination's consent, so personal data is decided per Destination.
|
|
64
|
+
- **Browser only.** The reader never runs on the server, so it can use `document` and `window`.
|
package/docs/events.md
CHANGED
|
@@ -107,7 +107,7 @@ The events module records what shoppers do on the storefront as vendor-neutral E
|
|
|
107
107
|
| Behavior | Description |
|
|
108
108
|
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
109
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.
|
|
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
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
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
113
|
| B-305 | A role with no Annotated Element above the target is absent from the Composition, not empty. |
|
|
@@ -122,7 +122,7 @@ The events module records what shoppers do on the storefront as vendor-neutral E
|
|
|
122
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
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
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
|
|
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
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
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
128
|
|
|
@@ -138,25 +138,30 @@ The events module records what shoppers do on the storefront as vendor-neutral E
|
|
|
138
138
|
|
|
139
139
|
### Destinations
|
|
140
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.
|
|
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
|
+
| B-506 | `ga4()` pushes `{ ecommerce: null }` before an event with `ecommerce`, since GTM would otherwise merge the previous event's items into it. |
|
|
148
149
|
|
|
149
150
|
### Consent
|
|
150
151
|
|
|
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.
|
|
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. |
|
|
160
165
|
|
|
161
166
|
## Built-in Event Names
|
|
162
167
|
|
package/docs/setup.md
ADDED
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
# Complete setup
|
|
2
|
+
|
|
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
|
+
|
|
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";
|
|
21
|
+
import type {
|
|
22
|
+
ButtonClickData,
|
|
23
|
+
FormEventData,
|
|
24
|
+
FormSubmitData,
|
|
25
|
+
ItemSelectData,
|
|
26
|
+
LinkClickData,
|
|
27
|
+
ListViewData,
|
|
28
|
+
VideoEventData,
|
|
29
|
+
} from "@buildinams/tracking/sources/dom";
|
|
30
|
+
import {
|
|
31
|
+
clicks,
|
|
32
|
+
createDomSource,
|
|
33
|
+
detailViews,
|
|
34
|
+
forms,
|
|
35
|
+
impressions,
|
|
36
|
+
pageViews,
|
|
37
|
+
scroll,
|
|
38
|
+
selections,
|
|
39
|
+
videos,
|
|
40
|
+
} from "@buildinams/tracking/sources/dom";
|
|
41
|
+
|
|
42
|
+
type Item = { id: string; name?: string; price?: string };
|
|
43
|
+
type CartLine = { id: string; quantity: number; merchandise: { id: string } };
|
|
44
|
+
type CartFragment = { lines: { nodes: CartLine[] } };
|
|
45
|
+
type Named = { id?: string; name?: string };
|
|
46
|
+
type Surroundings = { list: Named; promotion: Named; location: Named };
|
|
47
|
+
|
|
48
|
+
// A new Page per pathname; pass `key` to count e.g. `?page=2` as one too.
|
|
49
|
+
export const currentPage = createCurrentPage();
|
|
50
|
+
|
|
51
|
+
export const broker = createEventBroker(
|
|
52
|
+
{
|
|
53
|
+
"item:select": {
|
|
54
|
+
data: shape<Item & ItemSelectData>(),
|
|
55
|
+
composed: shape<Surroundings>(),
|
|
56
|
+
},
|
|
57
|
+
"item:view": { data: shape<Item>(), composed: shape<Surroundings>() },
|
|
58
|
+
"promotion:select": {
|
|
59
|
+
data: shape<Named>(),
|
|
60
|
+
composed: shape<Surroundings>(),
|
|
61
|
+
},
|
|
62
|
+
"promotion:view": { data: shape<Named>(), composed: shape<Surroundings>() },
|
|
63
|
+
"list:view": {
|
|
64
|
+
data: shape<ListViewData>(),
|
|
65
|
+
composed: shape<Surroundings>(),
|
|
66
|
+
},
|
|
67
|
+
"link:click": {
|
|
68
|
+
data: shape<LinkClickData>(),
|
|
69
|
+
composed: shape<Surroundings>(),
|
|
70
|
+
},
|
|
71
|
+
"button:click": {
|
|
72
|
+
data: shape<ButtonClickData>(),
|
|
73
|
+
composed: shape<Surroundings>(),
|
|
74
|
+
},
|
|
75
|
+
"form:start": {
|
|
76
|
+
data: shape<FormEventData>(),
|
|
77
|
+
composed: shape<Surroundings>(),
|
|
78
|
+
},
|
|
79
|
+
"form:submit": {
|
|
80
|
+
data: shape<FormSubmitData>(),
|
|
81
|
+
composed: shape<Surroundings>(),
|
|
82
|
+
},
|
|
83
|
+
"video:start": { data: shape<VideoEventData>() },
|
|
84
|
+
"video:progress": { data: shape<VideoEventData>() },
|
|
85
|
+
"video:complete": { data: shape<VideoEventData>() },
|
|
86
|
+
"page:view": { data: shape<{ type?: string }>() },
|
|
87
|
+
"page:scroll": { data: shape<{ depth: string }>() },
|
|
88
|
+
"cart:add": { data: shape<{ line: CartLine; quantity: number }>() },
|
|
89
|
+
"cart:remove": { data: shape<{ line: CartLine; quantity: number }>() },
|
|
90
|
+
},
|
|
91
|
+
// Optional; its return type becomes every Event's `context`.
|
|
92
|
+
{ context: () => ({ ...currentPage.read(), market: "nl" }) },
|
|
93
|
+
);
|
|
94
|
+
|
|
95
|
+
const destinations = createDestinations(broker.events, [
|
|
96
|
+
map(withConsent(ga4(), "none"), {
|
|
97
|
+
// The Composition decides: an Item in a Promotion but not a List is a promotion selection.
|
|
98
|
+
"item:select": ({ data, composed: { list, promotion }, meta: { id } }) =>
|
|
99
|
+
promotion && !list
|
|
100
|
+
? {
|
|
101
|
+
name: "select_promotion",
|
|
102
|
+
payload: {
|
|
103
|
+
event_id: id,
|
|
104
|
+
promotion_id: promotion.data.id,
|
|
105
|
+
items: [{ item_id: data.id }],
|
|
106
|
+
},
|
|
107
|
+
}
|
|
108
|
+
: {
|
|
109
|
+
name: "select_item",
|
|
110
|
+
payload: {
|
|
111
|
+
event_id: id,
|
|
112
|
+
items: [
|
|
113
|
+
{
|
|
114
|
+
item_id: data.id,
|
|
115
|
+
item_list_id: list?.data.id,
|
|
116
|
+
index: data.index,
|
|
117
|
+
},
|
|
118
|
+
],
|
|
119
|
+
},
|
|
120
|
+
},
|
|
121
|
+
}),
|
|
122
|
+
map(withConsent(shopify(), ["analytics"]), {
|
|
123
|
+
"item:view": ({ data }) => ({ name: "product_viewed", payload: { data } }),
|
|
124
|
+
}),
|
|
125
|
+
]);
|
|
126
|
+
|
|
127
|
+
export const domSource = createDomSource(
|
|
128
|
+
broker,
|
|
129
|
+
[
|
|
130
|
+
pageViews(),
|
|
131
|
+
selections(),
|
|
132
|
+
impressions(),
|
|
133
|
+
detailViews(),
|
|
134
|
+
clicks(),
|
|
135
|
+
forms(),
|
|
136
|
+
videos(),
|
|
137
|
+
scroll(),
|
|
138
|
+
],
|
|
139
|
+
// Flushes Detectors when a Page ends and resets them when the next starts.
|
|
140
|
+
{ currentPage },
|
|
141
|
+
);
|
|
142
|
+
// Or your own adapter: { lines: (cart) => …, key: (line) => …, quantity: (line) => … }
|
|
143
|
+
export const cartSource = createCartSource(broker, shopifyCart<CartFragment>());
|
|
144
|
+
|
|
145
|
+
// In the browser, once, e.g. in instrumentation-client.ts:
|
|
146
|
+
startTracking(broker, cookiebot(), destinations, {
|
|
147
|
+
sources: [domSource, cartSource],
|
|
148
|
+
// Tells Shopify and Google Consent Mode what the shopper answered in Cookiebot.
|
|
149
|
+
// googleConsentMode() denies by default when created: before GTM loads.
|
|
150
|
+
consentSinks: [shopifyCustomerPrivacy(), googleConsentMode()],
|
|
151
|
+
});
|
|
152
|
+
```
|
|
153
|
+
|
|
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.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@buildinams/tracking",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"sideEffects": false,
|
|
6
6
|
"author": "Build in Amsterdam <development@buildinamsterdam.com> (https://www.buildinamsterdam.com/)",
|
|
@@ -61,6 +61,10 @@
|
|
|
61
61
|
"types": "./dist/consent/cookiebot/index.d.ts",
|
|
62
62
|
"default": "./dist/consent/cookiebot/index.js"
|
|
63
63
|
},
|
|
64
|
+
"./consent/google": {
|
|
65
|
+
"types": "./dist/consent/google/index.d.ts",
|
|
66
|
+
"default": "./dist/consent/google/index.js"
|
|
67
|
+
},
|
|
64
68
|
"./consent/onetrust": {
|
|
65
69
|
"types": "./dist/consent/onetrust/index.d.ts",
|
|
66
70
|
"default": "./dist/consent/onetrust/index.js"
|
|
@@ -111,6 +115,9 @@
|
|
|
111
115
|
"./consent/cookiebot": [
|
|
112
116
|
"./dist/consent/cookiebot/index.d.ts"
|
|
113
117
|
],
|
|
118
|
+
"./consent/google": [
|
|
119
|
+
"./dist/consent/google/index.d.ts"
|
|
120
|
+
],
|
|
114
121
|
"./consent/onetrust": [
|
|
115
122
|
"./dist/consent/onetrust/index.d.ts"
|
|
116
123
|
],
|