@buildinams/tracking 0.2.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 +86 -208
- 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} +5 -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 +34 -40
- package/dist/{sources/dom → dom}/index.js +149 -247
- 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 +23 -9
- package/dist/flow/index.js.map +1 -1
- package/dist/google/index.d.ts +32 -0
- package/dist/google/index.js +66 -0
- 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 +48 -20
- 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 +104 -0
- package/docs/context.md +64 -0
- 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 +93 -84
- package/docs/setup.md +189 -0
- package/package.json +41 -69
- package/dist/consent/cookiebot/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 -13
- 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 -15
- 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,6 +1,19 @@
|
|
|
1
|
-
import { IS_DEVELOPMENT } from '
|
|
1
|
+
import { IS_DEVELOPMENT } from '../chunk-KLN5K6PR.js';
|
|
2
2
|
|
|
3
|
-
// src/
|
|
3
|
+
// src/shopify/shopify-cart.ts
|
|
4
|
+
var shopifyCart = () => ({
|
|
5
|
+
lines(cart) {
|
|
6
|
+
const lines = cart.lines;
|
|
7
|
+
if (!lines) return [];
|
|
8
|
+
if ("nodes" in lines) return lines.nodes;
|
|
9
|
+
if ("edges" in lines) return lines.edges.map(({ node }) => node);
|
|
10
|
+
return lines;
|
|
11
|
+
},
|
|
12
|
+
key: (line) => line.merchandise?.id ?? line.id,
|
|
13
|
+
quantity: (line) => line.quantity
|
|
14
|
+
});
|
|
15
|
+
|
|
16
|
+
// src/shopify/customer-privacy-api.ts
|
|
4
17
|
var warn = (...args) => {
|
|
5
18
|
if (IS_DEVELOPMENT) console.warn("[tracking]", ...args);
|
|
6
19
|
};
|
|
@@ -37,7 +50,7 @@ var withCustomerPrivacy = (callback) => {
|
|
|
37
50
|
);
|
|
38
51
|
};
|
|
39
52
|
|
|
40
|
-
// src/
|
|
53
|
+
// src/shopify/shopify-consent.ts
|
|
41
54
|
var read = () => {
|
|
42
55
|
const api = readCustomerPrivacy();
|
|
43
56
|
if (!api) return null;
|
|
@@ -68,26 +81,41 @@ var shopifyConsent = () => ({
|
|
|
68
81
|
}
|
|
69
82
|
});
|
|
70
83
|
|
|
71
|
-
// src/
|
|
84
|
+
// src/shopify/shopify-customer-privacy.ts
|
|
85
|
+
var toShopifyConsent = ({
|
|
86
|
+
analytics,
|
|
87
|
+
marketing,
|
|
88
|
+
preferences
|
|
89
|
+
}) => ({
|
|
90
|
+
analytics,
|
|
91
|
+
marketing,
|
|
92
|
+
preferences,
|
|
93
|
+
sale_of_data: marketing
|
|
94
|
+
});
|
|
72
95
|
var shopifyCustomerPrivacy = ({
|
|
73
|
-
|
|
74
|
-
} = {}) =>
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
const { analytics, marketing, preferences } = consent;
|
|
78
|
-
const sale_of_data = typeof saleOfData === "function" ? saleOfData(consent) : consent[saleOfData];
|
|
96
|
+
mapConsent = (_consent, defaults) => defaults
|
|
97
|
+
} = {}) => {
|
|
98
|
+
const apply = (consent) => {
|
|
99
|
+
const tracking = mapConsent(consent, toShopifyConsent(consent));
|
|
79
100
|
withCustomerPrivacy(
|
|
80
|
-
(api) => api.setTrackingConsent(
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
warn("Shopify rejected the tracking consent", result.error);
|
|
85
|
-
}
|
|
86
|
-
)
|
|
101
|
+
(api) => api.setTrackingConsent(tracking, (result) => {
|
|
102
|
+
if (result?.error)
|
|
103
|
+
warn("Shopify rejected the tracking consent", result.error);
|
|
104
|
+
})
|
|
87
105
|
);
|
|
88
|
-
}
|
|
89
|
-
|
|
106
|
+
};
|
|
107
|
+
return {
|
|
108
|
+
name: "shopify",
|
|
109
|
+
apply,
|
|
110
|
+
clear: () => apply({
|
|
111
|
+
necessary: true,
|
|
112
|
+
preferences: false,
|
|
113
|
+
analytics: false,
|
|
114
|
+
marketing: false
|
|
115
|
+
})
|
|
116
|
+
};
|
|
117
|
+
};
|
|
90
118
|
|
|
91
|
-
export { shopifyConsent, shopifyCustomerPrivacy };
|
|
119
|
+
export { shopifyCart, shopifyConsent, shopifyCustomerPrivacy };
|
|
92
120
|
//# sourceMappingURL=index.js.map
|
|
93
121
|
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../../src/shopify/shopify-cart.ts","../../src/shopify/customer-privacy-api.ts","../../src/shopify/shopify-consent.ts","../../src/shopify/shopify-customer-privacy.ts"],"names":[],"mappings":";;;AAwBO,IAAM,cAAc,OAEyB;AAAA,EACnD,MAAM,IAAA,EAAM;AACX,IAAA,MAAM,QAAQ,IAAA,CAAK,KAAA;AAInB,IAAA,IAAI,CAAC,KAAA,EAAO,OAAO,EAAC;AACpB,IAAA,IAAI,OAAA,IAAW,KAAA,EAAO,OAAO,KAAA,CAAM,KAAA;AACnC,IAAA,IAAI,OAAA,IAAW,KAAA,EAAO,OAAO,KAAA,CAAM,KAAA,CAAM,IAAI,CAAC,EAAE,IAAA,EAAK,KAAM,IAAI,CAAA;AAC/D,IAAA,OAAO,KAAA;AAAA,EACR,CAAA;AAAA,EACA,KAAK,CAAC,IAAA,KAAS,IAAA,CAAK,WAAA,EAAa,MAAM,IAAA,CAAK,EAAA;AAAA,EAC5C,QAAA,EAAU,CAAC,IAAA,KAAS,IAAA,CAAK;AAC1B,CAAA;;;ACFO,IAAM,IAAA,GAAO,IAAI,IAAA,KAAoB;AAC3C,EAAA,IAAI,cAAA,EAAgB,OAAA,CAAQ,IAAA,CAAK,YAAA,EAAc,GAAG,IAAI,CAAA;AACvD,CAAA;AAGA,IAAM,gBAAA,GAAmB,0BAAA;AAGzB,IAAM,QAAA,GAAW,CAChB,GAAA,KAEA,OAAO,KAAK,kBAAA,KAAuB,UAAA,IACnC,IAAI,aAAA,KAAkB,SAAA;AAGhB,IAAM,sBAAsB,MAAM;AACxC,EAAA,MAAM,GAAA,GAAO,OAAyB,OAAA,EAAS,eAAA;AAC/C,EAAA,OAAO,QAAA,CAAS,GAAG,CAAA,GAAI,GAAA,GAAM,MAAA;AAC9B,CAAA;AAGO,IAAM,mBAAA,GAAsB,CAClC,QAAA,KACI;AACJ,EAAA,MAAM,MAAM,mBAAA,EAAoB;AAChC,EAAA,IAAI,GAAA,EAAK,OAAO,QAAA,CAAS,GAAG,CAAA;AAC5B,EAAA,MAAM,UAAW,MAAA,CAAyB,OAAA;AAC1C,EAAA,IAAI,CAAC,SAAS,YAAA,EAAc;AAC3B,IAAA,QAAA,CAAS,gBAAA;AAAA,MACR,gBAAA;AAAA,MACA,MAAM;AACL,QAAA,MAAM,SAAS,mBAAA,EAAoB;AACnC,QAAA,IAAI,MAAA,WAAiB,MAAM,CAAA;AAAA,kBACjB,4CAA4C,CAAA;AAAA,MACvD,CAAA;AAAA,MACA,EAAE,MAAM,IAAA;AAAK,KACd;AACA,IAAA;AAAA,EACD;AACA,EAAA,OAAA,CAAQ,YAAA;AAAA,IACP,CAAC,EAAE,IAAA,EAAM,sBAAA,EAAwB,OAAA,EAAS,OAAO,CAAA;AAAA,IACjD,CAAC,KAAA,KAAU;AACV,MAAA,MAAM,SAAS,mBAAA,EAAoB;AACnC,MAAA,IAAI,SAAS,CAAC,MAAA;AACb,QAAA,IAAA,CAAK,8CAA8C,KAAK,CAAA;AAAA,oBAC3C,MAAM,CAAA;AAAA,IACrB;AAAA,GACD;AACD,CAAA;;;AC/EA,IAAM,OAAO,MAAsB;AAClC,EAAA,MAAM,MAAM,mBAAA,EAAoB;AAChC,EAAA,IAAI,CAAC,KAAK,OAAO,IAAA;AACjB,EAAA,MAAM,EAAE,SAAA,EAAW,SAAA,EAAW,WAAA,EAAY,GAAI,IAAI,qBAAA,EAAsB;AAExE,EAAA,MAAM,QAAA,GACL,CAAC,GAAA,CAAI,gBAAA,EAAiB,IACtB,CAAC,SAAA,EAAW,SAAA,EAAW,WAAW,CAAA,CAAE,IAAA,CAAK,OAAO,CAAA;AACjD,EAAA,IAAI,CAAC,UAAU,OAAO,IAAA;AACtB,EAAA,OAAO;AAAA,IACN,SAAA,EAAW,IAAA;AAAA,IACX,WAAA,EAAa,IAAI,4BAAA,EAA6B;AAAA,IAC9C,SAAA,EAAW,IAAI,0BAAA,EAA2B;AAAA,IAC1C,SAAA,EAAW,IAAI,gBAAA;AAAiB,GACjC;AACD,CAAA;AAGO,IAAM,iBAAiB,OAAwB;AAAA,EACrD,IAAA,EAAM,SAAA;AAAA,EACN,GAAA,EAAK,IAAA;AAAA,EACL,UAAU,QAAA,EAAU;AACnB,IAAA,IAAI,MAAA,GAAS,IAAA;AACb,IAAA,MAAM,QAAA,GAAW,MAAM,QAAA,CAAS,IAAA,EAAM,CAAA;AACtC,IAAA,QAAA,CAAS,gBAAA,CAAiB,2BAA2B,QAAQ,CAAA;AAC7D,IAAA,mBAAA,CAAoB,MAAM;AACzB,MAAA,IAAI,QAAQ,QAAA,EAAS;AAAA,IACtB,CAAC,CAAA;AACD,IAAA,OAAO,MAAM;AACZ,MAAA,MAAA,GAAS,KAAA;AACT,MAAA,QAAA,CAAS,mBAAA,CAAoB,2BAA2B,QAAQ,CAAA;AAAA,IACjE,CAAA;AAAA,EACD;AACD,CAAA;;;ACxBA,IAAM,mBAAmB,CAAC;AAAA,EACzB,SAAA;AAAA,EACA,SAAA;AAAA,EACA;AACD,CAAA,MAAwC;AAAA,EACvC,SAAA;AAAA,EACA,SAAA;AAAA,EACA,WAAA;AAAA,EACA,YAAA,EAAc;AACf,CAAA,CAAA;AAGO,IAAM,yBAAyB,CAAC;AAAA,EACtC,UAAA,GAAa,CAAC,QAAA,EAAU,QAAA,KAAa;AACtC,CAAA,GAAmC,EAAC,KAAmB;AACtD,EAAA,MAAM,KAAA,GAAQ,CAAC,OAAA,KAAqB;AACnC,IAAA,MAAM,QAAA,GAAW,UAAA,CAAW,OAAA,EAAS,gBAAA,CAAiB,OAAO,CAAC,CAAA;AAC9D,IAAA,mBAAA;AAAA,MAAoB,CAAC,GAAA,KACpB,GAAA,CAAI,kBAAA,CAAmB,QAAA,EAAU,CAAC,MAAA,KAAW;AAC5C,QAAA,IAAI,MAAA,EAAQ,KAAA;AACX,UAAA,IAAA,CAAK,uCAAA,EAAyC,OAAO,KAAK,CAAA;AAAA,MAC5D,CAAC;AAAA,KACF;AAAA,EACD,CAAA;AAEA,EAAA,OAAO;AAAA,IACN,IAAA,EAAM,SAAA;AAAA,IACN,KAAA;AAAA,IACA,KAAA,EAAO,MACN,KAAA,CAAM;AAAA,MACL,SAAA,EAAW,IAAA;AAAA,MACX,WAAA,EAAa,KAAA;AAAA,MACb,SAAA,EAAW,KAAA;AAAA,MACX,SAAA,EAAW;AAAA,KACX;AAAA,GACH;AACD","file":"index.js","sourcesContent":["import type { CartAdapter } from \"../cart\";\n\nexport type ShopifyCartLine = {\n\tid: string;\n\tquantity: number;\n\tmerchandise?: { id: string };\n};\n\n/** Storefront API connections and Hydrogen's flattened arrays both fit. */\ntype Lines<Line> =\n\t| readonly Line[]\n\t| { nodes: readonly Line[] }\n\t| { edges: readonly { node: Line }[] };\n\nexport type ShopifyCart = { lines?: Lines<ShopifyCartLine> | null };\n\nexport type ShopifyCartLineOf<Cart extends ShopifyCart> = (NonNullable<\n\tCart[\"lines\"]\n> extends Lines<infer Line>\n\t? Line\n\t: never) &\n\tShopifyCartLine;\n\n/** Reads Storefront API and Hydrogen carts, keying lines by variant. */\nexport const shopifyCart = <\n\tCart extends ShopifyCart = ShopifyCart,\n>(): CartAdapter<Cart, ShopifyCartLineOf<Cart>> => ({\n\tlines(cart) {\n\t\tconst lines = cart.lines as\n\t\t\t| Lines<ShopifyCartLineOf<Cart>>\n\t\t\t| null\n\t\t\t| undefined;\n\t\tif (!lines) return [];\n\t\tif (\"nodes\" in lines) return lines.nodes;\n\t\tif (\"edges\" in lines) return lines.edges.map(({ node }) => node);\n\t\treturn lines;\n\t},\n\tkey: (line) => line.merchandise?.id ?? line.id,\n\tquantity: (line) => line.quantity,\n});\n","import { IS_DEVELOPMENT } from \"../config\";\n\ntype ConsentValue = \"yes\" | \"no\" | \"\";\n\nexport type CustomerPrivacyApi = {\n\tsetTrackingConsent(\n\t\tconsent: {\n\t\t\tanalytics: boolean;\n\t\t\tmarketing: boolean;\n\t\t\tpreferences: boolean;\n\t\t\tsale_of_data: boolean;\n\t\t},\n\t\tcallback: (result?: { error?: unknown }) => void,\n\t): void;\n\tcurrentVisitorConsent(): {\n\t\tanalytics: ConsentValue;\n\t\tmarketing: ConsentValue;\n\t\tpreferences: ConsentValue;\n\t};\n\tshouldShowBanner(): boolean;\n\tanalyticsProcessingAllowed(): boolean;\n\tmarketingAllowed(): boolean;\n\tpreferencesProcessingAllowed(): boolean;\n\t/** Set on headless storefronts, by Shopify's scripts. */\n\tconsentStatus?: \"loading\" | \"loaded\";\n};\n\ntype ShopifyGlobal = {\n\tShopify?: {\n\t\tcustomerPrivacy?: Partial<CustomerPrivacyApi>;\n\t\tloadFeatures?(\n\t\t\tfeatures: { name: string; version: string }[],\n\t\t\tcallback: (error?: unknown) => void,\n\t\t): void;\n\t};\n};\n\nexport const warn = (...args: unknown[]) => {\n\tif (IS_DEVELOPMENT) console.warn(\"[tracking]\", ...args);\n};\n\n/** Fired on `document` by Shopify's scripts on headless storefronts once the API has loaded. */\nconst API_LOADED_EVENT = \"consentTrackingApiLoaded\";\n\n// Headless storefronts expose a placeholder first: without methods, then one that allows everything while loading.\nconst isLoaded = (\n\tapi: Partial<CustomerPrivacyApi> | undefined,\n): api is CustomerPrivacyApi =>\n\ttypeof api?.setTrackingConsent === \"function\" &&\n\tapi.consentStatus !== \"loading\";\n\n/** The API once it has loaded, else `undefined`. */\nexport const readCustomerPrivacy = () => {\n\tconst api = (window as ShopifyGlobal).Shopify?.customerPrivacy;\n\treturn isLoaded(api) ? api : undefined;\n};\n\n/** Calls back with the API once it has loaded: loading it on themes, waiting for Shopify's scripts on headless storefronts. */\nexport const withCustomerPrivacy = (\n\tcallback: (api: CustomerPrivacyApi) => void,\n) => {\n\tconst api = readCustomerPrivacy();\n\tif (api) return callback(api);\n\tconst shopify = (window as ShopifyGlobal).Shopify;\n\tif (!shopify?.loadFeatures) {\n\t\tdocument.addEventListener(\n\t\t\tAPI_LOADED_EVENT,\n\t\t\t() => {\n\t\t\t\tconst loaded = readCustomerPrivacy();\n\t\t\t\tif (loaded) callback(loaded);\n\t\t\t\telse warn(\"Shopify's Customer Privacy API didn't load\");\n\t\t\t},\n\t\t\t{ once: true },\n\t\t);\n\t\treturn;\n\t}\n\tshopify.loadFeatures(\n\t\t[{ name: \"consent-tracking-api\", version: \"0.1\" }],\n\t\t(error) => {\n\t\t\tconst loaded = readCustomerPrivacy();\n\t\t\tif (error || !loaded)\n\t\t\t\twarn(\"Shopify's Customer Privacy API didn't load\", error);\n\t\t\telse callback(loaded);\n\t\t},\n\t);\n};\n","import type { Consent, ConsentProvider } from \"../flow\";\nimport {\n\treadCustomerPrivacy,\n\twithCustomerPrivacy,\n} from \"./customer-privacy-api\";\n\nconst read = (): Consent | null => {\n\tconst api = readCustomerPrivacy();\n\tif (!api) return null;\n\tconst { analytics, marketing, preferences } = api.currentVisitorConsent();\n\t// Where no banner is required, Shopify's regional defaults are the answer.\n\tconst answered =\n\t\t!api.shouldShowBanner() ||\n\t\t[analytics, marketing, preferences].some(Boolean);\n\tif (!answered) return null;\n\treturn {\n\t\tnecessary: true,\n\t\tpreferences: api.preferencesProcessingAllowed(),\n\t\tanalytics: api.analyticsProcessingAllowed(),\n\t\tmarketing: api.marketingAllowed(),\n\t};\n};\n\n/** Reads consent from Shopify's Customer Privacy API, e.g. its privacy banner. */\nexport const shopifyConsent = (): ConsentProvider => ({\n\tname: \"shopify\",\n\tget: read,\n\tsubscribe(listener) {\n\t\tlet active = true;\n\t\tconst onChange = () => listener(read());\n\t\tdocument.addEventListener(\"visitorConsentCollected\", onChange);\n\t\twithCustomerPrivacy(() => {\n\t\t\tif (active) onChange();\n\t\t});\n\t\treturn () => {\n\t\t\tactive = false;\n\t\t\tdocument.removeEventListener(\"visitorConsentCollected\", onChange);\n\t\t};\n\t},\n});\n","import type { Consent, ConsentMapping, ConsentSink } from \"../flow\";\nimport { warn, withCustomerPrivacy } from \"./customer-privacy-api\";\n\nexport type ShopifyTrackingConsent = {\n\tanalytics: boolean;\n\tmarketing: boolean;\n\tpreferences: boolean;\n\tsale_of_data: boolean;\n};\n\nexport type ShopifyCustomerPrivacyOptions = {\n\t/** By default `sale_of_data` follows `marketing`. */\n\tmapConsent?: ConsentMapping<ShopifyTrackingConsent>;\n};\n\nconst toShopifyConsent = ({\n\tanalytics,\n\tmarketing,\n\tpreferences,\n}: Consent): ShopifyTrackingConsent => ({\n\tanalytics,\n\tmarketing,\n\tpreferences,\n\tsale_of_data: marketing,\n});\n\n/** Forwards consent to Shopify's Customer Privacy API. */\nexport const shopifyCustomerPrivacy = ({\n\tmapConsent = (_consent, defaults) => defaults,\n}: ShopifyCustomerPrivacyOptions = {}): ConsentSink => {\n\tconst apply = (consent: Consent) => {\n\t\tconst tracking = mapConsent(consent, toShopifyConsent(consent));\n\t\twithCustomerPrivacy((api) =>\n\t\t\tapi.setTrackingConsent(tracking, (result) => {\n\t\t\t\tif (result?.error)\n\t\t\t\t\twarn(\"Shopify rejected the tracking consent\", result.error);\n\t\t\t}),\n\t\t);\n\t};\n\n\treturn {\n\t\tname: \"shopify\",\n\t\tapply,\n\t\tclear: () =>\n\t\t\tapply({\n\t\t\t\tnecessary: true,\n\t\t\t\tpreferences: false,\n\t\t\t\tanalytics: false,\n\t\t\t\tmarketing: false,\n\t\t\t}),\n\t};\n};\n"]}
|
|
@@ -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 };
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# Annotations
|
|
2
|
+
|
|
3
|
+
Nothing is tracked unless an Annotation asks for it. Exact rules: [events.md](events.md#dom-source).
|
|
4
|
+
|
|
5
|
+
## Roles and Data
|
|
6
|
+
|
|
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
|
+
|
|
9
|
+
```html
|
|
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>
|
|
14
|
+
</article>
|
|
15
|
+
</section>
|
|
16
|
+
```
|
|
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`.
|
|
19
|
+
|
|
20
|
+
`\;` and `\\` stand for a `;` or `\` in a value. For values from data, like product titles, `encodeData()` from `/dom` writes the escapes:
|
|
21
|
+
|
|
22
|
+
```tsx
|
|
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>
|
|
27
|
+
```
|
|
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
|
+
|
|
39
|
+
## Detail pages
|
|
40
|
+
|
|
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.
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
// A variant switch isn't a new product view.
|
|
45
|
+
detailViews({ key: (data) => data.handle });
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Lists
|
|
49
|
+
|
|
50
|
+
An Item's `index` is its position in its List. Paginated or infinite grids pass where they start:
|
|
51
|
+
|
|
52
|
+
```html
|
|
53
|
+
<ul data-e="list" data-e-list="id:all;offset:24"></ul>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Looping carousels copy slides; mark each copy so it stands for the original:
|
|
57
|
+
|
|
58
|
+
```tsx
|
|
59
|
+
<li data-e-clone={isClone} data-e="item" data-e-item={encodeData({ id })}>
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Clicks, forms and videos
|
|
63
|
+
|
|
64
|
+
Opt in per element with a Flag, or per area with `data-e-auto`:
|
|
65
|
+
|
|
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:
|
|
89
|
+
|
|
90
|
+
```ts
|
|
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
|
+
}
|
|
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
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Context
|
|
2
|
+
|
|
3
|
+
The `context` reader's return type becomes every Event's `context`, typed in Mappings:
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
// src/tracking/context.ts
|
|
7
|
+
import { createClientNavigation } from "@buildinams/tracking/navigation";
|
|
8
|
+
|
|
9
|
+
export const clientNavigation = createClientNavigation();
|
|
10
|
+
|
|
11
|
+
type User =
|
|
12
|
+
| { loggedIn: true; id: string; tier: "member" | "vip" }
|
|
13
|
+
| { loggedIn: false };
|
|
14
|
+
|
|
15
|
+
let user: User = { loggedIn: false };
|
|
16
|
+
|
|
17
|
+
export const setTrackingUser = (next: User) => {
|
|
18
|
+
user = next;
|
|
19
|
+
};
|
|
20
|
+
|
|
21
|
+
export const readContext = () => ({
|
|
22
|
+
url: location.href,
|
|
23
|
+
path: location.pathname,
|
|
24
|
+
// `document.referrer` if every navigation is a full page load.
|
|
25
|
+
referrer: clientNavigation.referrer(),
|
|
26
|
+
user,
|
|
27
|
+
market: document.documentElement.dataset.market ?? "default",
|
|
28
|
+
});
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
```ts
|
|
32
|
+
const broker = createEventBroker(catalog, { context: readContext });
|
|
33
|
+
|
|
34
|
+
const destinations = [
|
|
35
|
+
map(broker, gtm(), "none", {
|
|
36
|
+
"item:select": ({ data, context: { user } }) => ({
|
|
37
|
+
name: "select_item",
|
|
38
|
+
payload: {
|
|
39
|
+
user_id: user.loggedIn ? user.id : undefined,
|
|
40
|
+
items: [{ item_id: data.id }],
|
|
41
|
+
},
|
|
42
|
+
}),
|
|
43
|
+
}),
|
|
44
|
+
];
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
```tsx
|
|
48
|
+
// Wherever the session lives
|
|
49
|
+
const TrackingUser = () => {
|
|
50
|
+
const session = useSession();
|
|
51
|
+
React.useEffect(() => {
|
|
52
|
+
setTrackingUser(
|
|
53
|
+
session
|
|
54
|
+
? { loggedIn: true, id: session.id, tier: session.tier }
|
|
55
|
+
: { loggedIn: false },
|
|
56
|
+
);
|
|
57
|
+
}, [session]);
|
|
58
|
+
return null;
|
|
59
|
+
};
|
|
60
|
+
```
|
|
61
|
+
|
|
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.
|