@codefast/tracking 0.5.0-canary.5 → 0.5.0-canary.6
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/CHANGELOG.md +467 -0
- package/README.md +176 -126
- package/dist/adapters/tanstack-start.d.ts +80 -0
- package/dist/adapters/tanstack-start.d.ts.map +1 -0
- package/dist/adapters/tanstack-start.js +74 -0
- package/dist/adapters/tanstack-start.js.map +1 -0
- package/dist/client/ad-framework-consent.d.ts +62 -0
- package/dist/client/ad-framework-consent.d.ts.map +1 -0
- package/dist/client/ad-framework-consent.js +40 -0
- package/dist/client/ad-framework-consent.js.map +1 -0
- package/dist/client/browser-cookie.d.ts +9 -0
- package/dist/client/browser-cookie.d.ts.map +1 -0
- package/dist/client/browser-cookie.js +15 -0
- package/dist/client/browser-cookie.js.map +1 -0
- package/dist/client/consent-runtime.d.ts +53 -0
- package/dist/client/consent-runtime.d.ts.map +1 -0
- package/dist/client/consent-runtime.js +33 -0
- package/dist/client/consent-runtime.js.map +1 -0
- package/dist/client/{consent-storage.d.mts → consent-storage.d.ts} +8 -6
- package/dist/client/consent-storage.d.ts.map +1 -0
- package/dist/client/consent-storage.js +109 -0
- package/dist/client/consent-storage.js.map +1 -0
- package/dist/client/consent-withdrawal.d.ts +18 -0
- package/dist/client/consent-withdrawal.d.ts.map +1 -0
- package/dist/client/consent-withdrawal.js +17 -0
- package/dist/client/consent-withdrawal.js.map +1 -0
- package/dist/client/cookie-anonymous-id.d.ts +41 -0
- package/dist/client/cookie-anonymous-id.d.ts.map +1 -0
- package/dist/client/cookie-anonymous-id.js +65 -0
- package/dist/client/cookie-anonymous-id.js.map +1 -0
- package/dist/client/create-client-tracker.d.ts +60 -0
- package/dist/client/create-client-tracker.d.ts.map +1 -0
- package/dist/client/create-client-tracker.js +91 -0
- package/dist/client/create-client-tracker.js.map +1 -0
- package/dist/client/gpc.d.ts +10 -0
- package/dist/client/gpc.d.ts.map +1 -0
- package/dist/client/gpc.js +12 -0
- package/dist/client/gpc.js.map +1 -0
- package/dist/client/initial-consent-store.d.ts +63 -0
- package/dist/client/initial-consent-store.d.ts.map +1 -0
- package/dist/client/initial-consent-store.js +138 -0
- package/dist/client/initial-consent-store.js.map +1 -0
- package/dist/client/is-analytics-allowed.d.ts +26 -0
- package/dist/client/is-analytics-allowed.d.ts.map +1 -0
- package/dist/client/is-analytics-allowed.js +22 -0
- package/dist/client/is-analytics-allowed.js.map +1 -0
- package/dist/client/server-persisted-anonymous-id.d.ts +30 -0
- package/dist/client/server-persisted-anonymous-id.d.ts.map +1 -0
- package/dist/client/server-persisted-anonymous-id.js +72 -0
- package/dist/client/server-persisted-anonymous-id.js.map +1 -0
- package/dist/core/consent-config.d.ts +24 -0
- package/dist/core/consent-config.d.ts.map +1 -0
- package/dist/core/consent-config.js +9 -0
- package/dist/core/consent-config.js.map +1 -0
- package/dist/core/consent-receipt.d.ts +71 -0
- package/dist/core/consent-receipt.d.ts.map +1 -0
- package/dist/core/consent-receipt.js +39 -0
- package/dist/core/consent-receipt.js.map +1 -0
- package/dist/core/consent.d.ts +182 -0
- package/dist/core/consent.d.ts.map +1 -0
- package/dist/core/consent.js +159 -0
- package/dist/core/consent.js.map +1 -0
- package/dist/core/cookie.d.ts +15 -0
- package/dist/core/cookie.d.ts.map +1 -0
- package/dist/core/cookie.js +26 -0
- package/dist/core/cookie.js.map +1 -0
- package/dist/core/destination.d.ts +29 -0
- package/dist/core/destination.d.ts.map +1 -0
- package/dist/core/destination.js +2 -0
- package/dist/core/destination.js.map +1 -0
- package/dist/core/event-catalog.d.ts +35 -0
- package/dist/core/event-catalog.d.ts.map +1 -0
- package/dist/core/event-catalog.js +30 -0
- package/dist/core/event-catalog.js.map +1 -0
- package/dist/core/event-id.d.ts +7 -0
- package/dist/core/event-id.d.ts.map +1 -0
- package/dist/core/event-id.js +9 -0
- package/dist/core/event-id.js.map +1 -0
- package/dist/core/tracked-event.d.ts +15 -0
- package/dist/core/tracked-event.d.ts.map +1 -0
- package/dist/core/tracked-event.js +2 -0
- package/dist/core/tracked-event.js.map +1 -0
- package/dist/destinations/ad-consent.d.ts +23 -0
- package/dist/destinations/ad-consent.d.ts.map +1 -0
- package/dist/destinations/ad-consent.js +12 -0
- package/dist/destinations/ad-consent.js.map +1 -0
- package/dist/destinations/google-analytics.d.ts +148 -0
- package/dist/destinations/google-analytics.d.ts.map +1 -0
- package/dist/destinations/google-analytics.js +156 -0
- package/dist/destinations/google-analytics.js.map +1 -0
- package/dist/destinations/google-consent.d.ts +62 -0
- package/dist/destinations/google-consent.d.ts.map +1 -0
- package/dist/destinations/google-consent.js +109 -0
- package/dist/destinations/google-consent.js.map +1 -0
- package/dist/destinations/meta.d.ts +63 -0
- package/dist/destinations/meta.d.ts.map +1 -0
- package/dist/destinations/meta.js +44 -0
- package/dist/destinations/meta.js.map +1 -0
- package/dist/destinations/microsoft-uet.d.ts +56 -0
- package/dist/destinations/microsoft-uet.d.ts.map +1 -0
- package/dist/destinations/microsoft-uet.js +41 -0
- package/dist/destinations/microsoft-uet.js.map +1 -0
- package/dist/destinations/shared.d.ts +18 -0
- package/dist/destinations/shared.d.ts.map +1 -0
- package/dist/destinations/shared.js +19 -0
- package/dist/destinations/shared.js.map +1 -0
- package/dist/destinations/tiktok.d.ts +55 -0
- package/dist/destinations/tiktok.d.ts.map +1 -0
- package/dist/destinations/tiktok.js +40 -0
- package/dist/destinations/tiktok.js.map +1 -0
- package/dist/destinations/vercel-analytics.d.ts +25 -0
- package/dist/destinations/vercel-analytics.d.ts.map +1 -0
- package/dist/destinations/vercel-analytics.js +23 -0
- package/dist/destinations/vercel-analytics.js.map +1 -0
- package/dist/index.d.ts +64 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +41 -0
- package/dist/index.js.map +1 -0
- package/dist/react/consent-banner.d.ts +155 -0
- package/dist/react/consent-banner.d.ts.map +1 -0
- package/dist/react/consent-banner.js +171 -0
- package/dist/react/consent-banner.js.map +1 -0
- package/dist/react/gtag-consent-bootstrap.d.ts +17 -0
- package/dist/react/gtag-consent-bootstrap.d.ts.map +1 -0
- package/dist/react/gtag-consent-bootstrap.js +22 -0
- package/dist/react/gtag-consent-bootstrap.js.map +1 -0
- package/dist/react/use-consent.d.ts +42 -0
- package/dist/react/use-consent.d.ts.map +1 -0
- package/dist/react/use-consent.js +60 -0
- package/dist/react/use-consent.js.map +1 -0
- package/dist/react/use-google-consent-sync.d.ts +20 -0
- package/dist/react/use-google-consent-sync.d.ts.map +1 -0
- package/dist/react/use-google-consent-sync.js +22 -0
- package/dist/react/use-google-consent-sync.js.map +1 -0
- package/dist/react/use-initial-consent.d.ts +11 -0
- package/dist/react/use-initial-consent.d.ts.map +1 -0
- package/dist/react/use-initial-consent.js +18 -0
- package/dist/react/use-initial-consent.js.map +1 -0
- package/dist/server/anonymous-id-cookie.d.ts +67 -0
- package/dist/server/anonymous-id-cookie.d.ts.map +1 -0
- package/dist/server/anonymous-id-cookie.js +71 -0
- package/dist/server/anonymous-id-cookie.js.map +1 -0
- package/dist/server/consent-receipt-store.d.ts +56 -0
- package/dist/server/consent-receipt-store.d.ts.map +1 -0
- package/dist/server/consent-receipt-store.js +44 -0
- package/dist/server/consent-receipt-store.js.map +1 -0
- package/dist/server/consent-receipt.d.ts +41 -0
- package/dist/server/consent-receipt.d.ts.map +1 -0
- package/dist/server/consent-receipt.js +60 -0
- package/dist/server/consent-receipt.js.map +1 -0
- package/dist/server/initial-consent.d.ts +26 -0
- package/dist/server/initial-consent.d.ts.map +1 -0
- package/dist/server/initial-consent.js +31 -0
- package/dist/server/initial-consent.js.map +1 -0
- package/dist/server/measurement-protocol.d.ts +69 -0
- package/dist/server/measurement-protocol.d.ts.map +1 -0
- package/dist/server/measurement-protocol.js +61 -0
- package/dist/server/measurement-protocol.js.map +1 -0
- package/dist/server/region.d.ts +27 -0
- package/dist/server/region.d.ts.map +1 -0
- package/dist/server/region.js +69 -0
- package/dist/server/region.js.map +1 -0
- package/dist/server/user-deletion.d.ts +64 -0
- package/dist/server/user-deletion.d.ts.map +1 -0
- package/dist/server/user-deletion.js +54 -0
- package/dist/server/user-deletion.js.map +1 -0
- package/dist/tooling/import-protection.d.ts +19 -0
- package/dist/tooling/import-protection.d.ts.map +1 -0
- package/dist/tooling/import-protection.js +23 -0
- package/dist/tooling/import-protection.js.map +1 -0
- package/package.json +201 -107
- package/src/adapters/tanstack-start.ts +135 -0
- package/src/client/ad-framework-consent.ts +86 -0
- package/src/client/browser-cookie.ts +16 -0
- package/src/client/consent-runtime.ts +80 -0
- package/src/client/consent-storage.ts +31 -1
- package/src/client/consent-withdrawal.ts +32 -0
- package/src/client/cookie-anonymous-id.ts +112 -0
- package/src/client/create-client-tracker.ts +128 -86
- package/src/client/gpc.ts +4 -2
- package/src/client/initial-consent-store.ts +218 -0
- package/src/client/is-analytics-allowed.ts +43 -0
- package/src/client/server-persisted-anonymous-id.ts +102 -0
- package/src/core/consent-config.ts +27 -0
- package/src/core/consent-receipt.ts +115 -0
- package/src/core/consent.ts +164 -10
- package/src/core/cookie.ts +29 -0
- package/src/core/destination.ts +17 -8
- package/src/core/event-catalog.ts +29 -15
- package/src/core/event-id.ts +1 -2
- package/src/core/tracked-event.ts +4 -4
- package/src/destinations/ad-consent.ts +29 -0
- package/src/destinations/google-analytics.ts +196 -133
- package/src/destinations/google-consent.ts +164 -0
- package/src/destinations/meta.ts +96 -0
- package/src/destinations/microsoft-uet.ts +86 -0
- package/src/destinations/shared.ts +45 -0
- package/src/destinations/tiktok.ts +85 -0
- package/src/destinations/vercel-analytics.ts +23 -24
- package/src/index.ts +165 -8
- package/src/react/consent-banner.tsx +40 -14
- package/src/react/gtag-consent-bootstrap.tsx +48 -0
- package/src/react/use-consent.ts +53 -45
- package/src/react/use-google-consent-sync.ts +38 -0
- package/src/react/use-initial-consent.ts +22 -0
- package/src/server/anonymous-id-cookie.ts +103 -0
- package/src/server/consent-receipt-store.ts +79 -0
- package/src/server/consent-receipt.ts +89 -0
- package/src/server/initial-consent.ts +46 -0
- package/src/server/measurement-protocol.ts +114 -0
- package/src/server/region.ts +22 -15
- package/src/server/user-deletion.ts +93 -0
- package/src/tooling/import-protection.ts +22 -0
- package/dist/client/consent-storage.mjs +0 -63
- package/dist/client/create-client-tracker.d.mts +0 -37
- package/dist/client/create-client-tracker.mjs +0 -66
- package/dist/client/gpc.d.mts +0 -10
- package/dist/client/gpc.mjs +0 -12
- package/dist/client/index.d.mts +0 -8
- package/dist/client/index.mjs +0 -8
- package/dist/client/lifecycle.d.mts +0 -23
- package/dist/client/lifecycle.mjs +0 -30
- package/dist/client/local-storage.d.mts +0 -13
- package/dist/client/local-storage.mjs +0 -31
- package/dist/client/queue.d.mts +0 -49
- package/dist/client/queue.mjs +0 -71
- package/dist/client/router.d.mts +0 -30
- package/dist/client/router.mjs +0 -17
- package/dist/core/consent.d.mts +0 -89
- package/dist/core/consent.mjs +0 -57
- package/dist/core/destination.d.mts +0 -23
- package/dist/core/destination.mjs +0 -1
- package/dist/core/event-catalog.d.mts +0 -36
- package/dist/core/event-catalog.mjs +0 -12
- package/dist/core/event-id.d.mts +0 -10
- package/dist/core/event-id.mjs +0 -12
- package/dist/core/index.d.mts +0 -6
- package/dist/core/index.mjs +0 -4
- package/dist/core/tracked-event.d.mts +0 -17
- package/dist/core/tracked-event.mjs +0 -1
- package/dist/destinations/ga4-measurement-protocol.d.mts +0 -54
- package/dist/destinations/ga4-measurement-protocol.mjs +0 -89
- package/dist/destinations/google-analytics.d.mts +0 -98
- package/dist/destinations/google-analytics.mjs +0 -126
- package/dist/destinations/http-destination.d.mts +0 -20
- package/dist/destinations/http-destination.mjs +0 -25
- package/dist/destinations/index.d.mts +0 -5
- package/dist/destinations/index.mjs +0 -5
- package/dist/destinations/vercel-analytics.d.mts +0 -13
- package/dist/destinations/vercel-analytics.mjs +0 -30
- package/dist/index.d.mts +0 -6
- package/dist/index.mjs +0 -4
- package/dist/react/consent-banner.d.mts +0 -163
- package/dist/react/consent-banner.mjs +0 -209
- package/dist/react/index.d.mts +0 -3
- package/dist/react/index.mjs +0 -3
- package/dist/react/use-consent.d.mts +0 -49
- package/dist/react/use-consent.mjs +0 -54
- package/dist/server/create-server-tracker.d.mts +0 -42
- package/dist/server/create-server-tracker.mjs +0 -67
- package/dist/server/index.d.mts +0 -3
- package/dist/server/index.mjs +0 -3
- package/dist/server/region.d.mts +0 -20
- package/dist/server/region.mjs +0 -56
- package/src/client/index.ts +0 -17
- package/src/client/lifecycle.ts +0 -50
- package/src/client/local-storage.ts +0 -44
- package/src/client/queue.ts +0 -117
- package/src/client/router.ts +0 -37
- package/src/core/index.ts +0 -24
- package/src/destinations/ga4-measurement-protocol.ts +0 -166
- package/src/destinations/http-destination.ts +0 -33
- package/src/destinations/index.ts +0 -20
- package/src/react/index.ts +0 -29
- package/src/server/create-server-tracker.ts +0 -128
- package/src/server/index.ts +0 -4
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import type { ConsentDecision } from "#/core/consent";
|
|
2
|
+
import type { Destination } from "#/core/destination";
|
|
3
|
+
import { toAdConsentState } from "#/destinations/ad-consent";
|
|
4
|
+
import type { FlatPropertyValue } from "#/destinations/shared";
|
|
5
|
+
import { flattenEventProps } from "#/destinations/shared";
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Meta's `dataProcessingOptions` restriction. `['LDU'], 0, 0` turns on Limited Data Use and
|
|
9
|
+
* lets Meta geolocate the user — the recommended default beyond California, where only
|
|
10
|
+
* country `1` (USA) / state `1000` (California) are documented codes (spec-destinations §5).
|
|
11
|
+
* `[]` applies no restriction.
|
|
12
|
+
*
|
|
13
|
+
* @since 1.0.0-canary.7
|
|
14
|
+
*/
|
|
15
|
+
export interface MetaDataProcessingOptions {
|
|
16
|
+
country: number;
|
|
17
|
+
options: ReadonlyArray<string>;
|
|
18
|
+
state: number;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Maps a `ConsentDecision` to Meta's `dataProcessingOptions`: LDU when `ads` is denied.
|
|
23
|
+
*
|
|
24
|
+
* @since 1.0.0-canary.7
|
|
25
|
+
*/
|
|
26
|
+
export function toMetaDataProcessingOptions(decision: ConsentDecision): MetaDataProcessingOptions {
|
|
27
|
+
return toAdConsentState(decision).limitedDataUse
|
|
28
|
+
? { country: 0, options: ["LDU"], state: 0 }
|
|
29
|
+
: { country: 0, options: [], state: 0 };
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* The mapped per-event payload handed to a Meta transport (Pixel `fbq` or a CAPI request).
|
|
34
|
+
*
|
|
35
|
+
* @since 1.0.0-canary.7
|
|
36
|
+
*/
|
|
37
|
+
export interface MetaEventPayload {
|
|
38
|
+
dataProcessingOptions: MetaDataProcessingOptions;
|
|
39
|
+
name: string;
|
|
40
|
+
properties: Record<string, FlatPropertyValue>;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* @since 1.0.0-canary.7
|
|
45
|
+
*/
|
|
46
|
+
export interface MetaDestinationOptions {
|
|
47
|
+
/**
|
|
48
|
+
* Erasure cookie-clear seam — invoked by `onErasure` to drop Meta's `_fbp`/`_fbc` cookies
|
|
49
|
+
* (spec-data-subject-rights DSR-V4). Meta exposes no per-visitor deletion API, so erasure
|
|
50
|
+
* is cookie-clear + stop-send only. Omit if the integrator clears cookies elsewhere.
|
|
51
|
+
*/
|
|
52
|
+
clearCookies?: (() => void) | undefined;
|
|
53
|
+
/** Read per event so an `ads` change restricts data use without recreating the destination. */
|
|
54
|
+
getDecision: () => ConsentDecision;
|
|
55
|
+
name?: string | undefined;
|
|
56
|
+
/**
|
|
57
|
+
* Delivers one mapped event — the transport seam. Wire it to `fbq(...)` (Pixel) or a
|
|
58
|
+
* Conversions API request; this package ships the consent mapping, never the credentials
|
|
59
|
+
* or network client.
|
|
60
|
+
*/
|
|
61
|
+
transport: (payload: MetaEventPayload) => Promise<void> | void;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* Reference ad destination: maps each event to Meta's shape and applies Limited Data Use
|
|
66
|
+
* from the live `ads` decision (spec-destinations §5), then hands it to an injected
|
|
67
|
+
* transport. Consent-restriction mapping only — the Pixel/CAPI transport and credentials
|
|
68
|
+
* are the integrator's to supply. `consentRequirement` stays `"required"`: an ad sink is
|
|
69
|
+
* never exempt.
|
|
70
|
+
*
|
|
71
|
+
* @since 1.0.0-canary.7
|
|
72
|
+
*/
|
|
73
|
+
export function createMetaDestination(options: MetaDestinationOptions): Destination {
|
|
74
|
+
// Erasure halts delivery for the rest of the session — Meta has no per-visitor deletion API.
|
|
75
|
+
let stopped = false;
|
|
76
|
+
|
|
77
|
+
return {
|
|
78
|
+
consentRequirement: "required",
|
|
79
|
+
name: options.name ?? "meta",
|
|
80
|
+
onErasure() {
|
|
81
|
+
stopped = true;
|
|
82
|
+
options.clearCookies?.();
|
|
83
|
+
},
|
|
84
|
+
async send(event) {
|
|
85
|
+
if (stopped) {
|
|
86
|
+
return;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
await options.transport({
|
|
90
|
+
dataProcessingOptions: toMetaDataProcessingOptions(options.getDecision()),
|
|
91
|
+
name: event.name,
|
|
92
|
+
properties: flattenEventProps(event.properties),
|
|
93
|
+
});
|
|
94
|
+
},
|
|
95
|
+
};
|
|
96
|
+
}
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
import type { ConsentDecision } from "#/core/consent";
|
|
2
|
+
import type { Destination } from "#/core/destination";
|
|
3
|
+
import { toAdConsentState } from "#/destinations/ad-consent";
|
|
4
|
+
import type { FlatPropertyValue } from "#/destinations/shared";
|
|
5
|
+
import { flattenEventProps } from "#/destinations/shared";
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Microsoft UET consent. UET enforces **only** `ad_storage` — it has no `analytics_storage`,
|
|
9
|
+
* and its `ad_user_data`/`ad_personalization` fields have no documented behavior, so this
|
|
10
|
+
* models the one enforced signal (spec-destinations §5). Pushed via
|
|
11
|
+
* `uetq.push('consent','update', …)`.
|
|
12
|
+
*
|
|
13
|
+
* @since 1.0.0-canary.7
|
|
14
|
+
*/
|
|
15
|
+
export interface MicrosoftUetConsent {
|
|
16
|
+
ad_storage: "denied" | "granted";
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* Maps a `ConsentDecision` to UET's enforced `ad_storage` signal via the shared ad lever, so
|
|
21
|
+
* it can't drift from Meta/TikTok — `ad_storage` is the inverse of Limited Data Use.
|
|
22
|
+
*
|
|
23
|
+
* @since 1.0.0-canary.7
|
|
24
|
+
*/
|
|
25
|
+
export function toMicrosoftUetConsent(decision: ConsentDecision): MicrosoftUetConsent {
|
|
26
|
+
return { ad_storage: toAdConsentState(decision).limitedDataUse ? "denied" : "granted" };
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* The mapped per-event payload handed to a UET transport (`uetq.push`).
|
|
31
|
+
*
|
|
32
|
+
* @since 1.0.0-canary.7
|
|
33
|
+
*/
|
|
34
|
+
export interface MicrosoftUetEventPayload {
|
|
35
|
+
consent: MicrosoftUetConsent;
|
|
36
|
+
name: string;
|
|
37
|
+
properties: Record<string, FlatPropertyValue>;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* @since 1.0.0-canary.7
|
|
42
|
+
*/
|
|
43
|
+
export interface MicrosoftUetDestinationOptions {
|
|
44
|
+
/** Erasure cookie-clear seam — UET exposes no per-visitor deletion API, so erasure is cookie-clear + stop-send (DSR-V4). */
|
|
45
|
+
clearCookies?: (() => void) | undefined;
|
|
46
|
+
/** Read per event so an `ads` change updates `ad_storage` without recreating the destination. */
|
|
47
|
+
getDecision: () => ConsentDecision;
|
|
48
|
+
name?: string | undefined;
|
|
49
|
+
/**
|
|
50
|
+
* Delivers one mapped event — the transport seam. Wire it to `uetq.push(...)`; this package
|
|
51
|
+
* ships the consent mapping, never the tag id or network client.
|
|
52
|
+
*/
|
|
53
|
+
transport: (payload: MicrosoftUetEventPayload) => Promise<void> | void;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Reference ad destination for Microsoft UET: maps each event and the live `ads` decision to
|
|
58
|
+
* UET's `ad_storage` signal, then hands it to an injected transport. Consent-restriction
|
|
59
|
+
* mapping only — the tag id and `uetq` transport are the integrator's. `consentRequirement`
|
|
60
|
+
* stays `"required"`.
|
|
61
|
+
*
|
|
62
|
+
* @since 1.0.0-canary.7
|
|
63
|
+
*/
|
|
64
|
+
export function createMicrosoftUetDestination(options: MicrosoftUetDestinationOptions): Destination {
|
|
65
|
+
let stopped = false;
|
|
66
|
+
|
|
67
|
+
return {
|
|
68
|
+
consentRequirement: "required",
|
|
69
|
+
name: options.name ?? "microsoft-uet",
|
|
70
|
+
onErasure() {
|
|
71
|
+
stopped = true;
|
|
72
|
+
options.clearCookies?.();
|
|
73
|
+
},
|
|
74
|
+
async send(event) {
|
|
75
|
+
if (stopped) {
|
|
76
|
+
return;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
await options.transport({
|
|
80
|
+
consent: toMicrosoftUetConsent(options.getDecision()),
|
|
81
|
+
name: event.name,
|
|
82
|
+
properties: flattenEventProps(event.properties),
|
|
83
|
+
});
|
|
84
|
+
},
|
|
85
|
+
};
|
|
86
|
+
}
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @since 1.0.0-canary.6
|
|
3
|
+
*/
|
|
4
|
+
export type FlatPropertyValue = boolean | number | string;
|
|
5
|
+
|
|
6
|
+
interface FlattenEventPropsOptions {
|
|
7
|
+
/** Vercel Analytics accepts `null` directly; GA4 (gtag.js/Measurement Protocol) does not. */
|
|
8
|
+
allowNull?: boolean | undefined;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Event params must be flat string/number/boolean (optionally `null`) — stringify
|
|
13
|
+
* anything else instead of letting the destination silently drop it.
|
|
14
|
+
*
|
|
15
|
+
* @since 1.0.0-canary.6
|
|
16
|
+
*/
|
|
17
|
+
export function flattenEventProps(properties: Record<string, unknown>): Record<string, FlatPropertyValue>;
|
|
18
|
+
/**
|
|
19
|
+
* @since 1.0.0-canary.6
|
|
20
|
+
*/
|
|
21
|
+
export function flattenEventProps(
|
|
22
|
+
properties: Record<string, unknown>,
|
|
23
|
+
options: { allowNull: true },
|
|
24
|
+
): Record<string, FlatPropertyValue | null>;
|
|
25
|
+
/**
|
|
26
|
+
* @since 1.0.0-canary.6
|
|
27
|
+
*/
|
|
28
|
+
export function flattenEventProps(
|
|
29
|
+
properties: Record<string, unknown>,
|
|
30
|
+
options: FlattenEventPropsOptions = {},
|
|
31
|
+
): Record<string, FlatPropertyValue | null> {
|
|
32
|
+
const result: Record<string, FlatPropertyValue | null> = {};
|
|
33
|
+
|
|
34
|
+
for (const [key, value] of Object.entries(properties)) {
|
|
35
|
+
if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
|
|
36
|
+
result[key] = value;
|
|
37
|
+
} else if (options.allowNull === true && value === null) {
|
|
38
|
+
result[key] = null;
|
|
39
|
+
} else if (value !== undefined && value !== null) {
|
|
40
|
+
result[key] = JSON.stringify(value);
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
return result;
|
|
45
|
+
}
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import type { ConsentDecision } from "#/core/consent";
|
|
2
|
+
import type { Destination } from "#/core/destination";
|
|
3
|
+
import { toAdConsentState } from "#/destinations/ad-consent";
|
|
4
|
+
import type { FlatPropertyValue } from "#/destinations/shared";
|
|
5
|
+
import { flattenEventProps } from "#/destinations/shared";
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* TikTok consent. TikTok uses a **single Limited Data Use boolean**, not Meta's
|
|
9
|
+
* `dataProcessingOptions` structure and no signal object (spec-destinations §5). Its
|
|
10
|
+
* transmission gate (`ttq.grantConsent()`/`revokeConsent()`) follows `analytics` and is the
|
|
11
|
+
* tracker's job; this models the `ads`-driven LDU lever.
|
|
12
|
+
*
|
|
13
|
+
* @since 1.0.0-canary.7
|
|
14
|
+
*/
|
|
15
|
+
export interface TiktokConsent {
|
|
16
|
+
limited_data_use: boolean;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* Maps a `ConsentDecision` to TikTok's LDU boolean — on when `ads` is denied.
|
|
21
|
+
*
|
|
22
|
+
* @since 1.0.0-canary.7
|
|
23
|
+
*/
|
|
24
|
+
export function toTiktokConsent(decision: ConsentDecision): TiktokConsent {
|
|
25
|
+
return { limited_data_use: toAdConsentState(decision).limitedDataUse };
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* The mapped per-event payload handed to a TikTok transport (`ttq.track` / Events API).
|
|
30
|
+
*
|
|
31
|
+
* @since 1.0.0-canary.7
|
|
32
|
+
*/
|
|
33
|
+
export interface TiktokEventPayload {
|
|
34
|
+
consent: TiktokConsent;
|
|
35
|
+
name: string;
|
|
36
|
+
properties: Record<string, FlatPropertyValue>;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* @since 1.0.0-canary.7
|
|
41
|
+
*/
|
|
42
|
+
export interface TiktokDestinationOptions {
|
|
43
|
+
/** Erasure cookie-clear seam — TikTok exposes no per-visitor deletion API, so erasure is cookie-clear + stop-send (DSR-V4). */
|
|
44
|
+
clearCookies?: (() => void) | undefined;
|
|
45
|
+
/** Read per event so an `ads` change flips LDU without recreating the destination. */
|
|
46
|
+
getDecision: () => ConsentDecision;
|
|
47
|
+
name?: string | undefined;
|
|
48
|
+
/**
|
|
49
|
+
* Delivers one mapped event — the transport seam. Wire it to `ttq.track(...)` (Pixel) or the
|
|
50
|
+
* Events API; this package ships the consent mapping, never the pixel id or network client.
|
|
51
|
+
*/
|
|
52
|
+
transport: (payload: TiktokEventPayload) => Promise<void> | void;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Reference ad destination for TikTok: maps each event and the live `ads` decision to
|
|
57
|
+
* TikTok's LDU boolean, then hands it to an injected transport. Consent-restriction mapping
|
|
58
|
+
* only — the pixel id and `ttq` transport are the integrator's. `consentRequirement` stays
|
|
59
|
+
* `"required"`.
|
|
60
|
+
*
|
|
61
|
+
* @since 1.0.0-canary.7
|
|
62
|
+
*/
|
|
63
|
+
export function createTiktokDestination(options: TiktokDestinationOptions): Destination {
|
|
64
|
+
let stopped = false;
|
|
65
|
+
|
|
66
|
+
return {
|
|
67
|
+
consentRequirement: "required",
|
|
68
|
+
name: options.name ?? "tiktok",
|
|
69
|
+
onErasure() {
|
|
70
|
+
stopped = true;
|
|
71
|
+
options.clearCookies?.();
|
|
72
|
+
},
|
|
73
|
+
async send(event) {
|
|
74
|
+
if (stopped) {
|
|
75
|
+
return;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
await options.transport({
|
|
79
|
+
consent: toTiktokConsent(options.getDecision()),
|
|
80
|
+
name: event.name,
|
|
81
|
+
properties: flattenEventProps(event.properties),
|
|
82
|
+
});
|
|
83
|
+
},
|
|
84
|
+
};
|
|
85
|
+
}
|
|
@@ -1,40 +1,39 @@
|
|
|
1
|
-
import { track } from "@vercel/analytics
|
|
1
|
+
import { track } from "@vercel/analytics";
|
|
2
2
|
|
|
3
3
|
import type { Destination } from "#/core/destination";
|
|
4
|
-
|
|
5
|
-
type VercelAnalyticsPropertyValue = boolean | number | string | null;
|
|
4
|
+
import { flattenEventProps } from "#/destinations/shared";
|
|
6
5
|
|
|
7
6
|
/**
|
|
8
|
-
*
|
|
9
|
-
* to a string instead of silently dropping it.
|
|
7
|
+
* @since 1.0.0-canary.6
|
|
10
8
|
*/
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
}
|
|
21
|
-
|
|
22
|
-
return result;
|
|
9
|
+
export interface VercelAnalyticsDestinationOptions {
|
|
10
|
+
/**
|
|
11
|
+
* Vercel Analytics is cookieless and its events carry no identifier from this
|
|
12
|
+
* package, so it qualifies for `"exempt"` — it then keeps receiving events while the
|
|
13
|
+
* tracker's analytics gate is closed. Defaults to `"required"` so pre-consent delivery
|
|
14
|
+
* stays an explicit opt-in.
|
|
15
|
+
*/
|
|
16
|
+
consentRequirement?: "exempt" | "required" | undefined;
|
|
17
|
+
name?: string | undefined;
|
|
23
18
|
}
|
|
24
19
|
|
|
25
20
|
/**
|
|
26
21
|
* `track()` only pushes onto Vercel's own in-page queue (`window.va`/`window.vaq`), which
|
|
27
|
-
* handles batching and unload delivery itself
|
|
28
|
-
* `<Analytics />` from `@vercel/analytics/react
|
|
22
|
+
* handles batching and unload delivery itself. Requires the Vercel Analytics script to be
|
|
23
|
+
* loaded once elsewhere in the app (`<Analytics />` from `@vercel/analytics/react`, or the
|
|
24
|
+
* framework-agnostic `inject()`) — this destination only queues events, so it imports the
|
|
25
|
+
* base `@vercel/analytics` package and has no React dependency of its own.
|
|
29
26
|
*
|
|
30
27
|
* @since 0.5.0-canary.4
|
|
31
28
|
*/
|
|
32
|
-
export function createVercelAnalyticsDestination(
|
|
29
|
+
export function createVercelAnalyticsDestination(options: VercelAnalyticsDestinationOptions = {}): Destination {
|
|
33
30
|
return {
|
|
34
|
-
|
|
35
|
-
name,
|
|
36
|
-
|
|
37
|
-
|
|
31
|
+
consentRequirement: options.consentRequirement ?? "required",
|
|
32
|
+
name: options.name ?? "vercel-analytics",
|
|
33
|
+
// Synchronous today, but declared async so a throw here rejects the returned Promise
|
|
34
|
+
// instead of escaping as a synchronous throw — matches Destination.send's contract.
|
|
35
|
+
async send(event) {
|
|
36
|
+
track(event.name, flattenEventProps(event.properties, { allowNull: true }));
|
|
38
37
|
},
|
|
39
38
|
};
|
|
40
39
|
}
|
package/src/index.ts
CHANGED
|
@@ -1,13 +1,170 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* \@codefast/tracking
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
4
|
+
* Consent-gated, type-safe event tracking for TanStack Start apps: define an event
|
|
5
|
+
* catalog over any Standard Schema library, wire a `ConsentConfig` + `createConsentRuntime`,
|
|
6
|
+
* and fan tracked events out to gtag / Vercel Analytics destinations.
|
|
7
7
|
*
|
|
8
|
-
*
|
|
9
|
-
* -
|
|
10
|
-
* -
|
|
11
|
-
*
|
|
8
|
+
* This root is the client entry: it re-exports the isomorphic core plus the whole
|
|
9
|
+
* browser-side surface (tracker, consent runtime, React bindings, client destinations).
|
|
10
|
+
* Server-only lanes are their own subpaths and never belong here — `@codefast/tracking/server/*`
|
|
11
|
+
* and `@codefast/tracking/adapters/*` (deny them in the client environment via
|
|
12
|
+
* `SERVER_ONLY_SUBPATHS`). The Vercel destination stays on `@codefast/tracking/destinations/
|
|
13
|
+
* vercel-analytics` so its `@vercel/analytics` peer is only pulled in when used.
|
|
12
14
|
*/
|
|
13
|
-
|
|
15
|
+
|
|
16
|
+
// ── Core (isomorphic) ───────────────────────────────────────────────────────────────
|
|
17
|
+
export type {
|
|
18
|
+
ConsentCategory,
|
|
19
|
+
ConsentDecision,
|
|
20
|
+
ConsentMode,
|
|
21
|
+
ConsentRecord,
|
|
22
|
+
ConsentRegion,
|
|
23
|
+
ConsentStorage,
|
|
24
|
+
InitialConsent,
|
|
25
|
+
ResolveDefaultConsentOptions,
|
|
26
|
+
ResolveEffectiveConsentOptions,
|
|
27
|
+
} from "#/core/consent";
|
|
28
|
+
export {
|
|
29
|
+
CONSENT_CATEGORIES,
|
|
30
|
+
CONSENT_REGIONS,
|
|
31
|
+
createConsentDecision,
|
|
32
|
+
isConsentDecision,
|
|
33
|
+
isConsentRecord,
|
|
34
|
+
isConsentRegion,
|
|
35
|
+
isInitialConsent,
|
|
36
|
+
normalizeConsentDecision,
|
|
37
|
+
readStoredDecision,
|
|
38
|
+
resolveConsentMode,
|
|
39
|
+
resolveDefaultConsent,
|
|
40
|
+
resolveEffectiveConsent,
|
|
41
|
+
STRICTEST_INITIAL_CONSENT,
|
|
42
|
+
} from "#/core/consent";
|
|
43
|
+
|
|
44
|
+
export type { ConsentConfig } from "#/core/consent-config";
|
|
45
|
+
export { defineConsentConfig } from "#/core/consent-config";
|
|
46
|
+
|
|
47
|
+
export type {
|
|
48
|
+
ConsentReceipt,
|
|
49
|
+
ConsentReceiptEventType,
|
|
50
|
+
ConsentReceiptInput,
|
|
51
|
+
ConsentReceiptMethod,
|
|
52
|
+
ConsentReceiptSubjectIdType,
|
|
53
|
+
} from "#/core/consent-receipt";
|
|
54
|
+
export { isConsentReceiptInput } from "#/core/consent-receipt";
|
|
55
|
+
|
|
56
|
+
export { readCookieValue } from "#/core/cookie";
|
|
57
|
+
|
|
58
|
+
export type { Destination } from "#/core/destination";
|
|
59
|
+
|
|
60
|
+
export type { EventCatalog, EventDefinition } from "#/core/event-catalog";
|
|
61
|
+
export { assertValidEventProperties, defineEventCatalog } from "#/core/event-catalog";
|
|
62
|
+
|
|
63
|
+
export { generateEventId } from "#/core/event-id";
|
|
64
|
+
|
|
65
|
+
export type { TrackedEvent } from "#/core/tracked-event";
|
|
66
|
+
|
|
67
|
+
// ── Client ──────────────────────────────────────────────────────────────────────────
|
|
68
|
+
export type { CmpConsentSignal, CmpStatus, ReconcileAdFrameworkConsentOptions } from "#/client/ad-framework-consent";
|
|
69
|
+
export { hasGppApi, hasTcfApi, reconcileAdFrameworkConsent } from "#/client/ad-framework-consent";
|
|
70
|
+
|
|
71
|
+
export type { ConsentRuntime, ConsentRuntimeOptions } from "#/client/consent-runtime";
|
|
72
|
+
export { createConsentRuntime } from "#/client/consent-runtime";
|
|
73
|
+
|
|
74
|
+
export { createLocalStorageConsentStorage } from "#/client/consent-storage";
|
|
75
|
+
|
|
76
|
+
export type { ConsentWithdrawalHandlerOptions } from "#/client/consent-withdrawal";
|
|
77
|
+
export { createConsentWithdrawalHandler } from "#/client/consent-withdrawal";
|
|
78
|
+
|
|
79
|
+
export type { CookieAnonymousId, CookieAnonymousIdOptions } from "#/client/cookie-anonymous-id";
|
|
80
|
+
export { createCookieAnonymousId } from "#/client/cookie-anonymous-id";
|
|
81
|
+
|
|
82
|
+
export type { ClientTracker, ClientTrackerOptions, DeliveryErrorContext } from "#/client/create-client-tracker";
|
|
83
|
+
export { createClientTracker } from "#/client/create-client-tracker";
|
|
84
|
+
|
|
85
|
+
export { hasGlobalPrivacyControlSignal } from "#/client/gpc";
|
|
86
|
+
|
|
87
|
+
export type {
|
|
88
|
+
InitialConsentSnapshot,
|
|
89
|
+
InitialConsentStore,
|
|
90
|
+
InitialConsentStoreOptions,
|
|
91
|
+
} from "#/client/initial-consent-store";
|
|
92
|
+
export { createInitialConsentStore } from "#/client/initial-consent-store";
|
|
93
|
+
|
|
94
|
+
export type { IsAnalyticsAllowedOptions } from "#/client/is-analytics-allowed";
|
|
95
|
+
export { createIsAnalyticsAllowed } from "#/client/is-analytics-allowed";
|
|
96
|
+
|
|
97
|
+
export type { ServerPersistedAnonymousIdOptions } from "#/client/server-persisted-anonymous-id";
|
|
98
|
+
export { createServerPersistedAnonymousId } from "#/client/server-persisted-anonymous-id";
|
|
99
|
+
|
|
100
|
+
// ── React ───────────────────────────────────────────────────────────────────────────
|
|
101
|
+
export type {
|
|
102
|
+
ConsentBannerAcceptProps,
|
|
103
|
+
ConsentBannerActionsProps,
|
|
104
|
+
ConsentBannerCategoryProps,
|
|
105
|
+
ConsentBannerCustomizeProps,
|
|
106
|
+
ConsentBannerDescriptionProps,
|
|
107
|
+
ConsentBannerPreferencesProps,
|
|
108
|
+
ConsentBannerProps,
|
|
109
|
+
ConsentBannerRejectProps,
|
|
110
|
+
ConsentBannerSaveProps,
|
|
111
|
+
ConsentBannerTitleProps,
|
|
112
|
+
ConsentToggleProps,
|
|
113
|
+
} from "#/react/consent-banner";
|
|
114
|
+
export {
|
|
115
|
+
ConsentBanner,
|
|
116
|
+
ConsentBannerAccept,
|
|
117
|
+
ConsentBannerActions,
|
|
118
|
+
ConsentBannerCategory,
|
|
119
|
+
ConsentBannerCustomize,
|
|
120
|
+
ConsentBannerDescription,
|
|
121
|
+
ConsentBannerPreferences,
|
|
122
|
+
ConsentBannerReject,
|
|
123
|
+
ConsentBannerSave,
|
|
124
|
+
ConsentBannerTitle,
|
|
125
|
+
ConsentToggle,
|
|
126
|
+
} from "#/react/consent-banner";
|
|
127
|
+
|
|
128
|
+
export type { GtagConsentBootstrapProps } from "#/react/gtag-consent-bootstrap";
|
|
129
|
+
export { GtagConsentBootstrap } from "#/react/gtag-consent-bootstrap";
|
|
130
|
+
|
|
131
|
+
export type { UseConsentOptions, UseConsentResult } from "#/react/use-consent";
|
|
132
|
+
export { useConsent } from "#/react/use-consent";
|
|
133
|
+
|
|
134
|
+
export type { UseGoogleConsentSyncOptions } from "#/react/use-google-consent-sync";
|
|
135
|
+
export { useGoogleConsentSync } from "#/react/use-google-consent-sync";
|
|
136
|
+
|
|
137
|
+
export { useInitialConsent } from "#/react/use-initial-consent";
|
|
138
|
+
|
|
139
|
+
// ── Destinations (client-lane; Vercel stays on its own subpath) ───────────────────────
|
|
140
|
+
export type { AdConsentState } from "#/destinations/ad-consent";
|
|
141
|
+
export { toAdConsentState } from "#/destinations/ad-consent";
|
|
142
|
+
|
|
143
|
+
export type {
|
|
144
|
+
EnsureGtagOptions,
|
|
145
|
+
GoogleAnalyticsDestinationOptions,
|
|
146
|
+
GtagConsentBootstrapOptions,
|
|
147
|
+
GtagFunction,
|
|
148
|
+
LoadGtagScriptOptions,
|
|
149
|
+
} from "#/destinations/google-analytics";
|
|
150
|
+
export {
|
|
151
|
+
buildGtagConsentBootstrapScript,
|
|
152
|
+
clearGoogleAnalyticsCookies,
|
|
153
|
+
createGoogleAnalyticsDestination,
|
|
154
|
+
ensureGtag,
|
|
155
|
+
loadGtagScript,
|
|
156
|
+
updateGoogleConsent,
|
|
157
|
+
} from "#/destinations/google-analytics";
|
|
158
|
+
|
|
159
|
+
export type { MetaDataProcessingOptions, MetaDestinationOptions, MetaEventPayload } from "#/destinations/meta";
|
|
160
|
+
export { createMetaDestination, toMetaDataProcessingOptions } from "#/destinations/meta";
|
|
161
|
+
|
|
162
|
+
export type {
|
|
163
|
+
MicrosoftUetConsent,
|
|
164
|
+
MicrosoftUetDestinationOptions,
|
|
165
|
+
MicrosoftUetEventPayload,
|
|
166
|
+
} from "#/destinations/microsoft-uet";
|
|
167
|
+
export { createMicrosoftUetDestination, toMicrosoftUetConsent } from "#/destinations/microsoft-uet";
|
|
168
|
+
|
|
169
|
+
export type { TiktokConsent, TiktokDestinationOptions, TiktokEventPayload } from "#/destinations/tiktok";
|
|
170
|
+
export { createTiktokDestination, toTiktokConsent } from "#/destinations/tiktok";
|