@buildinams/tracking 0.0.0-stage → 0.2.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 +93 -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 +202 -0
- package/dist/sources/dom/index.js +597 -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 +187 -0
- package/package.json +141 -5
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
import { C as CheckPublished } from '../../compatibility-Dc1JmTeG.js';
|
|
2
|
+
import { C as Catalog, E as EventBroker } from '../../types-DfPz7mBl.js';
|
|
3
|
+
import { CurrentPage } from '../../page/index.js';
|
|
4
|
+
import { Source } from '../index.js';
|
|
5
|
+
|
|
6
|
+
declare const ROLES: readonly ["location", "list", "item", "promotion", "form"];
|
|
7
|
+
declare const FLAGS: readonly ["click", "video", "detail", "page"];
|
|
8
|
+
type Role = (typeof ROLES)[number];
|
|
9
|
+
type Flag = (typeof FLAGS)[number];
|
|
10
|
+
type AnnotationData = Record<string, string>;
|
|
11
|
+
type AnnotationValue = string | number | boolean | null | undefined;
|
|
12
|
+
/** Attributes to spread onto an element. */
|
|
13
|
+
type Annotation = {
|
|
14
|
+
"data-e": string;
|
|
15
|
+
"data-e-data"?: string;
|
|
16
|
+
};
|
|
17
|
+
type Annotated = {
|
|
18
|
+
data: AnnotationData;
|
|
19
|
+
composed: Partial<Record<Role, {
|
|
20
|
+
data: AnnotationData;
|
|
21
|
+
}>>;
|
|
22
|
+
};
|
|
23
|
+
/**
|
|
24
|
+
* The `data-e` and `data-e-data` attributes for an element with these Roles and Flags and this Data,
|
|
25
|
+
* e.g. `<div {...annotate(["item", "detail"], { id, title })} />`. Values may contain `;`;
|
|
26
|
+
* `null` and `undefined` ones are left out.
|
|
27
|
+
*/
|
|
28
|
+
declare const annotate: <D extends { [K in keyof D]: AnnotationValue; }>(words: Role | Flag | readonly (Role | Flag)[], data?: D) => Annotation;
|
|
29
|
+
|
|
30
|
+
type DetectorContext = {
|
|
31
|
+
publish(name: string, event: {
|
|
32
|
+
data: object;
|
|
33
|
+
composed: Annotated["composed"];
|
|
34
|
+
}): void;
|
|
35
|
+
};
|
|
36
|
+
/** `P` maps each Event Name it publishes to the Data it guarantees; the catalog must declare them compatibly. */
|
|
37
|
+
type Detector<P extends Record<string, object> = Record<string, object>> = {
|
|
38
|
+
readonly events: readonly (keyof P & string)[];
|
|
39
|
+
/** Type-only: never set at runtime. */
|
|
40
|
+
readonly published?: P;
|
|
41
|
+
start(context: DetectorContext): () => void;
|
|
42
|
+
/** Publishes anything batched. */
|
|
43
|
+
flush?(): void;
|
|
44
|
+
/** Forgets what was seen on the previous Page. */
|
|
45
|
+
reset?(): void;
|
|
46
|
+
};
|
|
47
|
+
|
|
48
|
+
type LinkClickData = {
|
|
49
|
+
url: string;
|
|
50
|
+
text: string;
|
|
51
|
+
/** On another host than the page and `internalHosts`. */
|
|
52
|
+
outbound: boolean;
|
|
53
|
+
download?: {
|
|
54
|
+
name: string;
|
|
55
|
+
extension: string;
|
|
56
|
+
};
|
|
57
|
+
[field: string]: unknown;
|
|
58
|
+
};
|
|
59
|
+
type ButtonClickData = {
|
|
60
|
+
text: string;
|
|
61
|
+
[field: string]: unknown;
|
|
62
|
+
};
|
|
63
|
+
type ClicksOptions = {
|
|
64
|
+
/** Whether links and buttons are tracked where no `data-e-auto` decides. */
|
|
65
|
+
auto?: {
|
|
66
|
+
links?: boolean;
|
|
67
|
+
buttons?: boolean;
|
|
68
|
+
};
|
|
69
|
+
/** Hosts besides the page's own that links aren't outbound to. */
|
|
70
|
+
internalHosts?: string[];
|
|
71
|
+
downloadExtensions?: string[];
|
|
72
|
+
};
|
|
73
|
+
/** Publishes `link:click` and `button:click` for opted-in links and buttons. */
|
|
74
|
+
declare const clicks: ({ auto, internalHosts, downloadExtensions, }?: ClicksOptions) => Detector<{
|
|
75
|
+
"link:click": LinkClickData;
|
|
76
|
+
"button:click": ButtonClickData;
|
|
77
|
+
}>;
|
|
78
|
+
|
|
79
|
+
type DomSourceOptions = {
|
|
80
|
+
currentPage: Pick<CurrentPage, "subscribe">;
|
|
81
|
+
};
|
|
82
|
+
type DomSource = Source & {
|
|
83
|
+
flush(): void;
|
|
84
|
+
};
|
|
85
|
+
declare const createDomSource: <C extends Catalog, const D extends readonly Detector<any>[]>(broker: EventBroker<C>, detectors: [...D] & { [I in keyof D]: D[I] extends Detector<infer P> ? Detector<CheckPublished<C, P>> : never; }, { currentPage }: DomSourceOptions) => DomSource;
|
|
86
|
+
|
|
87
|
+
/** Publishes `item:view` when an Item flagged `detail` (`data-e="item detail"`), e.g. a product page's, is rendered or shows another Item. */
|
|
88
|
+
declare const detailViews: () => Detector<{
|
|
89
|
+
"item:view": AnnotationData;
|
|
90
|
+
}>;
|
|
91
|
+
|
|
92
|
+
type FormEventData = {
|
|
93
|
+
id?: string;
|
|
94
|
+
name?: string;
|
|
95
|
+
/** The form's `action`, absolute. */
|
|
96
|
+
destination?: string;
|
|
97
|
+
[field: string]: unknown;
|
|
98
|
+
};
|
|
99
|
+
type FormSubmitData = FormEventData & {
|
|
100
|
+
/** The submitting button's text. */
|
|
101
|
+
submitText?: string;
|
|
102
|
+
};
|
|
103
|
+
type FormsOptions = {
|
|
104
|
+
/** Whether forms are tracked where neither a Form Annotation nor `data-e-auto` decides. */
|
|
105
|
+
auto?: boolean;
|
|
106
|
+
};
|
|
107
|
+
/** Publishes `form:start` on the first interaction with a form per Page, and `form:submit`; field values are never read. */
|
|
108
|
+
declare const forms: ({ auto }?: FormsOptions) => Detector<{
|
|
109
|
+
"form:start": FormEventData;
|
|
110
|
+
"form:submit": FormSubmitData;
|
|
111
|
+
}>;
|
|
112
|
+
|
|
113
|
+
type ListViewItem = {
|
|
114
|
+
index: number;
|
|
115
|
+
[field: string]: unknown;
|
|
116
|
+
};
|
|
117
|
+
type ListViewData = {
|
|
118
|
+
/** The List's Items seen since the last batch, in List order. */
|
|
119
|
+
items: ListViewItem[];
|
|
120
|
+
[field: string]: unknown;
|
|
121
|
+
};
|
|
122
|
+
type ImpressionsOptions = {
|
|
123
|
+
/** Share of an element that must be visible. */
|
|
124
|
+
threshold?: number;
|
|
125
|
+
/** Milliseconds Items are batched per List before `list:view` is published. */
|
|
126
|
+
delay?: number;
|
|
127
|
+
};
|
|
128
|
+
/**
|
|
129
|
+
* Publishes `promotion:view` the first time a Promotion is visible on a Page, and
|
|
130
|
+
* `list:view` with the Items of a List first visible on a Page, batched per List.
|
|
131
|
+
*/
|
|
132
|
+
declare const impressions: ({ threshold, delay, }?: ImpressionsOptions) => Detector<{
|
|
133
|
+
"promotion:view": AnnotationData;
|
|
134
|
+
"list:view": ListViewData;
|
|
135
|
+
}>;
|
|
136
|
+
|
|
137
|
+
/** Publishes `page:view` once per Page, with the Data of every element flagged `page` (`data-e="page"`), later ones winning on conflicts. */
|
|
138
|
+
declare const pageViews: () => Detector<{
|
|
139
|
+
"page:view": AnnotationData;
|
|
140
|
+
}>;
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* An exact pathname (`"/search"`), a pathname ending in `/*` for everything below it
|
|
144
|
+
* (`"/collections/*"`), a `RegExp` tested against the pathname, or a function of the URL.
|
|
145
|
+
*/
|
|
146
|
+
type PathMatcher = string | RegExp | ((url: URL) => boolean);
|
|
147
|
+
/** Publishes the Detector's Events only on Pages matching one of `paths`. */
|
|
148
|
+
declare const only: <P extends Record<string, object>>(detector: Detector<P>, paths: PathMatcher[]) => Detector<P>;
|
|
149
|
+
/** Publishes the Detector's Events on every Page except those matching one of `paths`. */
|
|
150
|
+
declare const except: <P extends Record<string, object>>(detector: Detector<P>, paths: PathMatcher[]) => Detector<P>;
|
|
151
|
+
|
|
152
|
+
type ScrollOptions = {
|
|
153
|
+
/** Percentages of the page height. */
|
|
154
|
+
thresholds?: number[];
|
|
155
|
+
};
|
|
156
|
+
/** Publishes `page:scroll` once per threshold per Page, with `{ depth }`. */
|
|
157
|
+
declare const scroll: ({ thresholds, }?: ScrollOptions) => Detector<{
|
|
158
|
+
"page:scroll": {
|
|
159
|
+
depth: string;
|
|
160
|
+
};
|
|
161
|
+
}>;
|
|
162
|
+
|
|
163
|
+
type ItemSelectData = {
|
|
164
|
+
/** Position in its List, when it's in one. */
|
|
165
|
+
index?: number;
|
|
166
|
+
[field: string]: unknown;
|
|
167
|
+
};
|
|
168
|
+
/**
|
|
169
|
+
* Publishes `item:select` for link and button clicks in an Item, its List and Promotion in its
|
|
170
|
+
* Composition, and `promotion:select` for link and button clicks in a Promotion outside any Item.
|
|
171
|
+
* Clicks in an Item flagged `detail` select nothing.
|
|
172
|
+
*/
|
|
173
|
+
declare const selections: () => Detector<{
|
|
174
|
+
"item:select": ItemSelectData;
|
|
175
|
+
"promotion:select": AnnotationData;
|
|
176
|
+
}>;
|
|
177
|
+
|
|
178
|
+
type VideoEventData = {
|
|
179
|
+
url: string;
|
|
180
|
+
title?: string;
|
|
181
|
+
/** Seconds, rounded. */
|
|
182
|
+
duration: number;
|
|
183
|
+
/** Seconds, rounded. */
|
|
184
|
+
currentTime: number;
|
|
185
|
+
/** For `video:progress`, the threshold reached; otherwise the share played. */
|
|
186
|
+
percent: number;
|
|
187
|
+
[field: string]: unknown;
|
|
188
|
+
};
|
|
189
|
+
type VideosOptions = {
|
|
190
|
+
/** Whether videos are tracked where neither a `video` Flag nor `data-e-auto` decides. */
|
|
191
|
+
auto?: boolean;
|
|
192
|
+
/** Percentages reported once per video per Page. */
|
|
193
|
+
thresholds?: number[];
|
|
194
|
+
};
|
|
195
|
+
/** Publishes `video:start`, `video:progress` and `video:complete` for opted-in `<video>` elements. */
|
|
196
|
+
declare const videos: ({ auto, thresholds, }?: VideosOptions) => Detector<{
|
|
197
|
+
"video:start": VideoEventData;
|
|
198
|
+
"video:progress": VideoEventData;
|
|
199
|
+
"video:complete": VideoEventData;
|
|
200
|
+
}>;
|
|
201
|
+
|
|
202
|
+
export { type Annotation, type AnnotationData, type AnnotationValue, type ButtonClickData, type ClicksOptions, type Detector, type DetectorContext, type DomSource, type DomSourceOptions, type Flag, type FormEventData, type FormSubmitData, type FormsOptions, type ImpressionsOptions, type ItemSelectData, type LinkClickData, type ListViewData, type ListViewItem, type PathMatcher, type Role, type ScrollOptions, type VideoEventData, type VideosOptions, annotate, clicks, createDomSource, detailViews, except, forms, impressions, only, pageViews, scroll, selections, videos };
|