@codefast/tracking 0.5.0-canary.4 → 1.0.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 +171 -0
- package/README.md +123 -96
- package/dist/client/browser-cookie.d.mts +11 -0
- package/dist/client/browser-cookie.mjs +15 -0
- package/dist/client/consent-runtime.d.mts +56 -0
- package/dist/client/consent-runtime.mjs +35 -0
- package/dist/client/consent-storage.d.mts +5 -0
- package/dist/client/consent-storage.mjs +20 -1
- package/dist/client/consent-withdrawal.d.mts +21 -0
- package/dist/client/consent-withdrawal.mjs +17 -0
- package/dist/client/cookie-anonymous-id.d.mts +37 -0
- package/dist/client/cookie-anonymous-id.mjs +46 -0
- package/dist/client/create-client-tracker.d.mts +11 -16
- package/dist/client/create-client-tracker.mjs +27 -53
- package/dist/client/gpc.d.mts +2 -0
- package/dist/client/gpc.mjs +3 -1
- package/dist/client/index.d.mts +7 -5
- package/dist/client/index.mjs +8 -6
- package/dist/client/initial-consent-store.d.mts +66 -0
- package/dist/client/initial-consent-store.mjs +119 -0
- package/dist/client/is-analytics-allowed.d.mts +29 -0
- package/dist/client/is-analytics-allowed.mjs +23 -0
- package/dist/client/server-persisted-anonymous-id.d.mts +33 -0
- package/dist/client/server-persisted-anonymous-id.mjs +50 -0
- package/dist/core/consent-config.d.mts +27 -0
- package/dist/core/consent-config.mjs +11 -0
- package/dist/core/consent.d.mts +99 -4
- package/dist/core/consent.mjs +99 -4
- package/dist/core/cookie.d.mts +17 -0
- package/dist/core/cookie.mjs +23 -0
- package/dist/core/destination.d.mts +10 -8
- package/dist/core/event-catalog.d.mts +16 -13
- package/dist/core/event-catalog.mjs +19 -1
- package/dist/core/event-id.d.mts +1 -2
- package/dist/core/event-id.mjs +1 -2
- package/dist/core/index.d.mts +6 -4
- package/dist/core/index.mjs +5 -3
- package/dist/core/tracked-event.d.mts +21 -8
- package/dist/destinations/google-analytics.d.mts +100 -48
- package/dist/destinations/google-analytics.mjs +89 -85
- package/dist/destinations/google-consent.d.mts +64 -0
- package/dist/destinations/google-consent.mjs +102 -0
- package/dist/destinations/index.d.mts +2 -5
- package/dist/destinations/index.mjs +2 -5
- package/dist/destinations/shared.d.mts +20 -0
- package/dist/destinations/shared.mjs +13 -0
- package/dist/destinations/vercel-analytics.d.mts +19 -4
- package/dist/destinations/vercel-analytics.mjs +11 -18
- package/dist/import-protection.d.mts +19 -0
- package/dist/import-protection.mjs +23 -0
- package/dist/index.d.mts +6 -4
- package/dist/index.mjs +5 -3
- package/dist/react/consent-banner.d.mts +143 -38
- package/dist/react/consent-banner.mjs +192 -92
- package/dist/react/gtag-consent-bootstrap.d.mts +27 -0
- package/dist/react/gtag-consent-bootstrap.mjs +29 -0
- package/dist/react/index.d.mts +5 -2
- package/dist/react/index.mjs +5 -2
- package/dist/react/use-consent.d.mts +9 -13
- package/dist/react/use-consent.mjs +42 -25
- package/dist/react/use-google-consent-sync.d.mts +23 -0
- package/dist/react/use-google-consent-sync.mjs +24 -0
- package/dist/react/use-initial-consent.d.mts +14 -0
- package/dist/react/use-initial-consent.mjs +19 -0
- package/dist/server/anonymous-id-cookie.d.mts +46 -0
- package/dist/server/anonymous-id-cookie.mjs +51 -0
- package/dist/server/index.d.mts +5 -3
- package/dist/server/index.mjs +4 -3
- package/dist/server/initial-consent.d.mts +29 -0
- package/dist/server/initial-consent.mjs +31 -0
- package/dist/server/region.d.mts +21 -4
- package/dist/server/region.mjs +26 -5
- package/dist/tanstack-start/index.d.mts +58 -0
- package/dist/tanstack-start/index.mjs +45 -0
- package/package.json +27 -110
- 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 +93 -0
- package/src/client/create-client-tracker.ts +56 -85
- package/src/client/gpc.ts +4 -2
- package/src/client/index.ts +19 -8
- 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 +99 -0
- package/src/core/consent-config.ts +27 -0
- package/src/core/consent.ts +164 -10
- package/src/core/cookie.ts +29 -0
- package/src/core/destination.ts +10 -8
- package/src/core/event-catalog.ts +28 -15
- package/src/core/event-id.ts +1 -2
- package/src/core/index.ts +19 -3
- package/src/core/tracked-event.ts +22 -7
- package/src/css/consent.css +119 -0
- package/src/destinations/google-analytics.ts +196 -133
- package/src/destinations/google-consent.ts +164 -0
- package/src/destinations/index.ts +14 -15
- package/src/destinations/shared.ts +45 -0
- package/src/destinations/vercel-analytics.ts +23 -24
- package/src/import-protection.ts +20 -0
- package/src/index.ts +46 -8
- package/src/react/consent-banner.tsx +308 -111
- package/src/react/gtag-consent-bootstrap.tsx +48 -0
- package/src/react/index.ts +34 -2
- 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 +76 -0
- package/src/server/index.ts +15 -3
- package/src/server/initial-consent.ts +48 -0
- package/src/server/region.ts +22 -5
- package/src/tanstack-start/index.ts +83 -0
- 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/destinations/ga4-measurement-protocol.d.mts +0 -54
- package/dist/destinations/ga4-measurement-protocol.mjs +0 -89
- package/dist/destinations/http-destination.d.mts +0 -20
- package/dist/destinations/http-destination.mjs +0 -25
- package/dist/server/create-server-tracker.d.mts +0 -42
- package/dist/server/create-server-tracker.mjs +0 -67
- 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/destinations/ga4-measurement-protocol.ts +0 -166
- package/src/destinations/http-destination.ts +0 -33
- package/src/server/create-server-tracker.ts +0 -128
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
/* -------------------------------------------------------------------------
|
|
2
|
+
* Optional consent UI theme
|
|
3
|
+
*
|
|
4
|
+
* Plain CSS over the components' data-slot attributes — no Tailwind, no
|
|
5
|
+
* design-system dependency. Import it for a sensible default look:
|
|
6
|
+
*
|
|
7
|
+
* @import "@codefast/tracking/css/consent.css";
|
|
8
|
+
*
|
|
9
|
+
* Every color routes through a `--consent-*` custom property with a
|
|
10
|
+
* `light-dark()` fallback, so a host app can retheme by defining those
|
|
11
|
+
* properties (or skip this file entirely and style the slots itself).
|
|
12
|
+
* ------------------------------------------------------------------------- */
|
|
13
|
+
|
|
14
|
+
[data-slot="consent-banner"] {
|
|
15
|
+
position: fixed;
|
|
16
|
+
inset-inline: 1rem;
|
|
17
|
+
bottom: 1rem;
|
|
18
|
+
z-index: 50;
|
|
19
|
+
margin-inline: auto;
|
|
20
|
+
max-width: 24rem;
|
|
21
|
+
padding: 1.25rem;
|
|
22
|
+
border: 1px solid var(--consent-border, light-dark(rgb(0 0 0 / 12%), rgb(255 255 255 / 14%)));
|
|
23
|
+
border-radius: 1rem;
|
|
24
|
+
background: var(--consent-surface, light-dark(#fff, #1c1c1e));
|
|
25
|
+
color: var(--consent-fg, light-dark(#1c1c1e, #f2f2f7));
|
|
26
|
+
box-shadow: 0 12px 32px rgb(0 0 0 / 18%);
|
|
27
|
+
font-size: 0.875rem;
|
|
28
|
+
line-height: 1.5;
|
|
29
|
+
animation: consent-banner-in 220ms ease-out;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
@media (min-width: 640px) {
|
|
33
|
+
[data-slot="consent-banner"] {
|
|
34
|
+
inset-inline: auto 1rem;
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
@keyframes consent-banner-in {
|
|
39
|
+
from {
|
|
40
|
+
opacity: 0;
|
|
41
|
+
transform: translateY(1rem);
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
@media (prefers-reduced-motion: reduce) {
|
|
46
|
+
[data-slot="consent-banner"] {
|
|
47
|
+
animation: none;
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
[data-slot="consent-title"] {
|
|
52
|
+
margin: 0 0 0.375rem;
|
|
53
|
+
font-size: 0.875rem;
|
|
54
|
+
font-weight: 600;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
[data-slot="consent-description"] {
|
|
58
|
+
margin: 0 0 1rem;
|
|
59
|
+
color: var(--consent-muted, light-dark(rgb(28 28 30 / 65%), rgb(242 242 247 / 65%)));
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
[data-slot="consent-description"] a {
|
|
63
|
+
color: inherit;
|
|
64
|
+
text-decoration: underline;
|
|
65
|
+
text-underline-offset: 0.2em;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
[data-slot="consent-preferences"] {
|
|
69
|
+
display: flex;
|
|
70
|
+
flex-direction: column;
|
|
71
|
+
gap: 0.5rem;
|
|
72
|
+
margin-bottom: 1rem;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
[data-slot="consent-category"] {
|
|
76
|
+
display: flex;
|
|
77
|
+
gap: 0.5rem;
|
|
78
|
+
align-items: baseline;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
[data-slot="consent-actions"] {
|
|
82
|
+
display: flex;
|
|
83
|
+
gap: 0.5rem;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
[data-slot="consent-action"] {
|
|
87
|
+
flex: 1;
|
|
88
|
+
padding: 0.5rem 0.75rem;
|
|
89
|
+
border: 1px solid var(--consent-border, light-dark(rgb(0 0 0 / 12%), rgb(255 255 255 / 14%)));
|
|
90
|
+
border-radius: 0.5rem;
|
|
91
|
+
background: transparent;
|
|
92
|
+
color: inherit;
|
|
93
|
+
font: inherit;
|
|
94
|
+
font-weight: 500;
|
|
95
|
+
cursor: pointer;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/* The affirmative actions carry the accent; Reject stays equally prominent, just outlined. */
|
|
99
|
+
[data-slot="consent-action"][data-action="accept"],
|
|
100
|
+
[data-slot="consent-action"][data-action="save"] {
|
|
101
|
+
border-color: transparent;
|
|
102
|
+
background: var(--consent-accent, light-dark(#1c1c1e, #f2f2f7));
|
|
103
|
+
color: var(--consent-accent-fg, light-dark(#fff, #1c1c1e));
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
[data-slot="consent-toggle"] {
|
|
107
|
+
position: fixed;
|
|
108
|
+
inset-inline-start: 1rem;
|
|
109
|
+
bottom: 1rem;
|
|
110
|
+
z-index: 50;
|
|
111
|
+
padding: 0.375rem 0.75rem;
|
|
112
|
+
border: 1px solid var(--consent-border, light-dark(rgb(0 0 0 / 12%), rgb(255 255 255 / 14%)));
|
|
113
|
+
border-radius: 9999px;
|
|
114
|
+
background: var(--consent-surface, light-dark(#fff, #1c1c1e));
|
|
115
|
+
color: var(--consent-muted, light-dark(rgb(28 28 30 / 65%), rgb(242 242 247 / 65%)));
|
|
116
|
+
font: inherit;
|
|
117
|
+
font-size: 0.75rem;
|
|
118
|
+
cursor: pointer;
|
|
119
|
+
}
|
|
@@ -1,27 +1,33 @@
|
|
|
1
1
|
import type { ConsentDecision } from "#/core/consent";
|
|
2
|
+
import type { ConsentConfig } from "#/core/consent-config";
|
|
2
3
|
import type { Destination } from "#/core/destination";
|
|
4
|
+
import type { GoogleConsentParams } from "#/destinations/google-consent";
|
|
5
|
+
import {
|
|
6
|
+
buildGoogleConsentBootstrapPreamble,
|
|
7
|
+
DEFAULT_DATA_LAYER_NAME,
|
|
8
|
+
ensureDataLayer,
|
|
9
|
+
toGoogleConsentParams,
|
|
10
|
+
warnUnlessGa4EventName,
|
|
11
|
+
} from "#/destinations/google-consent";
|
|
12
|
+
import type { FlatPropertyValue } from "#/destinations/shared";
|
|
13
|
+
import { flattenEventProps } from "#/destinations/shared";
|
|
3
14
|
|
|
4
|
-
|
|
15
|
+
const GTAG_SCRIPT_BASE_URL = "https://www.googletagmanager.com/gtag/js";
|
|
5
16
|
|
|
6
|
-
type
|
|
7
|
-
|
|
8
|
-
interface GoogleConsentParams {
|
|
9
|
-
ad_personalization: GoogleConsentState;
|
|
10
|
-
ad_storage: GoogleConsentState;
|
|
11
|
-
ad_user_data: GoogleConsentState;
|
|
12
|
-
analytics_storage: GoogleConsentState;
|
|
13
|
-
region?: ReadonlyArray<string>;
|
|
14
|
-
wait_for_update?: number;
|
|
15
|
-
}
|
|
17
|
+
type GtagPropertyValue = FlatPropertyValue;
|
|
16
18
|
|
|
17
19
|
/**
|
|
18
20
|
* All signatures share one `gtag` global, so they must live in a single overloaded type —
|
|
19
21
|
* two separate `declare global` augmentations with different signatures for the same
|
|
20
22
|
* property is a TS error, not a merge.
|
|
23
|
+
*
|
|
24
|
+
* @since 1.0.0-canary.6
|
|
21
25
|
*/
|
|
22
|
-
type GtagFunction = {
|
|
26
|
+
export type GtagFunction = {
|
|
27
|
+
(command: "config", targetId: string, params?: Record<string, GtagPropertyValue>): void;
|
|
23
28
|
(command: "consent", action: "default" | "update", params: GoogleConsentParams): void;
|
|
24
29
|
(command: "event", eventName: string, params?: Record<string, GtagPropertyValue>): void;
|
|
30
|
+
(command: "js", startDate: Date): void;
|
|
25
31
|
(command: "set", params: Record<string, GtagPropertyValue>): void;
|
|
26
32
|
(command: "set", key: string, value: boolean): void;
|
|
27
33
|
};
|
|
@@ -33,149 +39,238 @@ declare global {
|
|
|
33
39
|
}
|
|
34
40
|
}
|
|
35
41
|
|
|
42
|
+
function gtagScriptSrc(gaMeasurementId: string, dataLayerName: string): string {
|
|
43
|
+
const url = new URL(GTAG_SCRIPT_BASE_URL);
|
|
44
|
+
|
|
45
|
+
url.searchParams.set("id", gaMeasurementId);
|
|
46
|
+
|
|
47
|
+
if (dataLayerName !== DEFAULT_DATA_LAYER_NAME) {
|
|
48
|
+
// gtag.js's `l` param names the queue array — must match the stub that pushes into it.
|
|
49
|
+
url.searchParams.set("l", dataLayerName);
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
return url.toString();
|
|
53
|
+
}
|
|
54
|
+
|
|
36
55
|
/**
|
|
37
|
-
*
|
|
38
|
-
* drives `analytics_storage`; `ads` drives all three ads signals together — a banner
|
|
39
|
-
* that got ads consent got it for storage, sharing, and personalization alike.
|
|
56
|
+
* @since 1.0.0-canary.6
|
|
40
57
|
*/
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
ad_user_data: ads,
|
|
48
|
-
analytics_storage: decision.analytics ? "granted" : "denied",
|
|
49
|
-
};
|
|
58
|
+
export interface EnsureGtagOptions {
|
|
59
|
+
/**
|
|
60
|
+
* Name of the queue array on `window`. Defaults to `"dataLayer"`. Must match across
|
|
61
|
+
* `ensureGtag` / `loadGtagScript` / `buildGtagConsentBootstrapScript` for one page.
|
|
62
|
+
*/
|
|
63
|
+
dataLayerName?: string | undefined;
|
|
50
64
|
}
|
|
51
65
|
|
|
52
66
|
/**
|
|
53
67
|
* Ensures the standard gtag.js queueing stub exists so consent commands can be issued
|
|
54
68
|
* before the tag itself loads — gtag.js replays the queue in order once it boots.
|
|
69
|
+
*
|
|
70
|
+
* @since 1.0.0-canary.6
|
|
55
71
|
*/
|
|
56
|
-
function ensureGtag(): GtagFunction | undefined {
|
|
72
|
+
export function ensureGtag(options: EnsureGtagOptions = {}): GtagFunction | undefined {
|
|
57
73
|
if (typeof window === "undefined") {
|
|
58
74
|
return undefined;
|
|
59
75
|
}
|
|
60
76
|
|
|
61
|
-
|
|
77
|
+
const dataLayerName = options.dataLayerName ?? DEFAULT_DATA_LAYER_NAME;
|
|
78
|
+
|
|
79
|
+
ensureDataLayer(dataLayerName);
|
|
62
80
|
|
|
63
|
-
//
|
|
64
|
-
//
|
|
81
|
+
// First stub wins — recreating would orphan commands already queued on another layer.
|
|
82
|
+
// Callers must pass the same dataLayerName for every helper on the page.
|
|
65
83
|
window.gtag ??= function gtag() {
|
|
66
|
-
|
|
84
|
+
ensureDataLayer(dataLayerName)?.push(arguments);
|
|
67
85
|
} as GtagFunction;
|
|
68
86
|
|
|
69
87
|
return window.gtag;
|
|
70
88
|
}
|
|
71
89
|
|
|
72
90
|
/**
|
|
73
|
-
* @since 0.
|
|
91
|
+
* @since 1.0.0-canary.6
|
|
74
92
|
*/
|
|
75
|
-
export interface
|
|
76
|
-
/**
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
93
|
+
export interface LoadGtagScriptOptions {
|
|
94
|
+
/**
|
|
95
|
+
* Name of the queue array on `window`. Defaults to `"dataLayer"` — must match the
|
|
96
|
+
* bootstrap / `ensureGtag` call that already applied Consent Mode.
|
|
97
|
+
*/
|
|
98
|
+
dataLayerName?: string | undefined;
|
|
99
|
+
/** Forwarded as `gtag('config', id, { debug_mode: true })` for GA4 DebugView. */
|
|
100
|
+
debugMode?: boolean | undefined;
|
|
101
|
+
/** Google Analytics 4 Measurement ID (e.g. `"G-XXXXXXX"`). */
|
|
102
|
+
gaMeasurementId: string;
|
|
103
|
+
/**
|
|
104
|
+
* CSP nonce applied to the injected gtag.js `<script>` element. The app must also put
|
|
105
|
+
* the same nonce on any inline bootstrap `<script>` that runs `buildGtagConsentBootstrapScript`.
|
|
106
|
+
*/
|
|
107
|
+
nonce?: string | undefined;
|
|
80
108
|
}
|
|
81
109
|
|
|
82
110
|
/**
|
|
83
|
-
*
|
|
84
|
-
*
|
|
85
|
-
*
|
|
111
|
+
* Loads gtag.js on demand — idempotent (a second call is a no-op) and reuses any
|
|
112
|
+
* existing `dataLayer`/`gtag` stub instead of clobbering it. Queues `js`/`config` before
|
|
113
|
+
* appending the script tag, so gtag.js replays them under the caller's already-applied
|
|
114
|
+
* consent state once it boots. Prefer `buildGtagConsentBootstrapScript` for page load
|
|
115
|
+
* (advanced Consent Mode always injects the tag after the default); use this when the
|
|
116
|
+
* bootstrap did not run, or as an idempotent safety net after a runtime grant.
|
|
86
117
|
*
|
|
87
|
-
* @since 0.
|
|
118
|
+
* @since 1.0.0-canary.6
|
|
88
119
|
*/
|
|
89
|
-
export function
|
|
90
|
-
|
|
120
|
+
export function loadGtagScript(options: LoadGtagScriptOptions): void {
|
|
121
|
+
if (typeof document === "undefined" || document.querySelector(`script[src^="${GTAG_SCRIPT_BASE_URL}"]`) !== null) {
|
|
122
|
+
return;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
const dataLayerName = options.dataLayerName ?? DEFAULT_DATA_LAYER_NAME;
|
|
126
|
+
const gtag = ensureGtag({ dataLayerName });
|
|
127
|
+
|
|
128
|
+
if (!gtag) {
|
|
129
|
+
return;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
gtag("js", new Date());
|
|
91
133
|
|
|
92
|
-
if (options.
|
|
93
|
-
|
|
134
|
+
if (options.debugMode === true) {
|
|
135
|
+
gtag("config", options.gaMeasurementId, { debug_mode: true });
|
|
136
|
+
} else {
|
|
137
|
+
gtag("config", options.gaMeasurementId);
|
|
94
138
|
}
|
|
95
139
|
|
|
96
|
-
|
|
97
|
-
|
|
140
|
+
const script = document.createElement("script");
|
|
141
|
+
|
|
142
|
+
script.async = true;
|
|
143
|
+
script.src = gtagScriptSrc(options.gaMeasurementId, dataLayerName);
|
|
144
|
+
|
|
145
|
+
if (options.nonce !== undefined) {
|
|
146
|
+
script.nonce = options.nonce;
|
|
98
147
|
}
|
|
99
148
|
|
|
100
|
-
|
|
149
|
+
document.head.append(script);
|
|
101
150
|
}
|
|
102
151
|
|
|
103
152
|
/**
|
|
104
|
-
* Google
|
|
105
|
-
*
|
|
106
|
-
*
|
|
153
|
+
* Expires Google's `_ga` / `_ga_*` cookies on `path=/` and the current host's parent
|
|
154
|
+
* domain. Consent Mode stops using them once denied but never removes them — call from
|
|
155
|
+
* a consent-withdrawal handler so a revoke does not leave identifier cookies behind.
|
|
107
156
|
*
|
|
108
|
-
* @since 0.
|
|
157
|
+
* @since 1.0.0-canary.6
|
|
109
158
|
*/
|
|
110
|
-
export function
|
|
111
|
-
|
|
159
|
+
export function clearGoogleAnalyticsCookies(): void {
|
|
160
|
+
if (typeof document === "undefined") {
|
|
161
|
+
return;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
const { hostname } = globalThis.location;
|
|
165
|
+
|
|
166
|
+
for (const cookie of document.cookie.split("; ")) {
|
|
167
|
+
const name = cookie.split("=")[0];
|
|
168
|
+
|
|
169
|
+
if (name !== undefined && (name === "_ga" || name.startsWith("_ga_"))) {
|
|
170
|
+
// GA sets its cookies on the broadest domain it can reach — expire both variants.
|
|
171
|
+
document.cookie = `${name}=; path=/; max-age=0`;
|
|
172
|
+
document.cookie = `${name}=; path=/; max-age=0; domain=.${hostname}`;
|
|
173
|
+
}
|
|
174
|
+
}
|
|
112
175
|
}
|
|
113
176
|
|
|
114
177
|
/**
|
|
115
|
-
* Consent Mode's
|
|
116
|
-
*
|
|
117
|
-
* the
|
|
178
|
+
* Google Consent Mode v2's "update" signal — call whenever the visitor's effective
|
|
179
|
+
* consent changes (a banner decision, or one synced from another tab), so already-loaded
|
|
180
|
+
* GA4/Ads tags pick up the change without a page reload.
|
|
118
181
|
*
|
|
119
182
|
* @since 0.5.0-canary.4
|
|
120
183
|
*/
|
|
121
|
-
export function
|
|
122
|
-
ensureGtag()?.("
|
|
184
|
+
export function updateGoogleConsent(decision: ConsentDecision, options: EnsureGtagOptions = {}): void {
|
|
185
|
+
ensureGtag(options)?.("consent", "update", toGoogleConsentParams(decision));
|
|
123
186
|
}
|
|
124
187
|
|
|
125
188
|
/**
|
|
126
|
-
*
|
|
127
|
-
* storage is denied, preserving conversion attribution without cookies.
|
|
128
|
-
*
|
|
129
|
-
* @since 0.5.0-canary.4
|
|
189
|
+
* @since 1.0.0-canary.6
|
|
130
190
|
*/
|
|
131
|
-
export
|
|
132
|
-
|
|
191
|
+
export interface GtagConsentBootstrapOptions {
|
|
192
|
+
/** The same object `useConsent` receives — the bootstrap reads its `storageKey` and `policyVersion`. */
|
|
193
|
+
config: ConsentConfig;
|
|
194
|
+
/**
|
|
195
|
+
* Name of the queue array on `window`. Defaults to `"dataLayer"`. Must match
|
|
196
|
+
* `loadGtagScript` / `ensureGtag` if those run later on the same page.
|
|
197
|
+
*/
|
|
198
|
+
dataLayerName?: string | undefined;
|
|
199
|
+
/**
|
|
200
|
+
* Consent to apply when nothing valid is stored yet. Embedded as a literal — bake the
|
|
201
|
+
* strictest default on cached/shared HTML; upgrade after hydration via the private
|
|
202
|
+
* server-fn lane + `updateGoogleConsent`.
|
|
203
|
+
*/
|
|
204
|
+
defaultConsent: ConsentDecision;
|
|
205
|
+
/** Forwarded as `gtag('config', id, { debug_mode: true })` after the consent default. */
|
|
206
|
+
debugMode?: boolean | undefined;
|
|
207
|
+
/** Google Analytics 4 Measurement ID (e.g. `"G-XXXXXXX"`). */
|
|
208
|
+
gaMeasurementId: string;
|
|
209
|
+
/**
|
|
210
|
+
* CSP nonce written onto the *injected* gtag.js `<script>` element inside the generated
|
|
211
|
+
* source. The host `<script dangerouslySetInnerHTML={…}>` that embeds this string must
|
|
212
|
+
* receive the same nonce from the app (this helper only returns JS text, not a React node).
|
|
213
|
+
*/
|
|
214
|
+
nonce?: string | undefined;
|
|
133
215
|
}
|
|
134
216
|
|
|
135
217
|
/**
|
|
136
|
-
*
|
|
137
|
-
*
|
|
218
|
+
* Builds the literal JS source for a `<script dangerouslySetInnerHTML>` mounted in
|
|
219
|
+
* `<head>`, before hydration: applies Consent Mode v2's default signal from the visitor's
|
|
220
|
+
* stored decision (falling back to literal `defaultConsent` when none is stored yet),
|
|
221
|
+
* then always loads gtag.js (advanced Consent Mode) so cookieless pings / modeling can
|
|
222
|
+
* run even when storage is denied. A runtime decision change needs `updateGoogleConsent`
|
|
223
|
+
* so the already-loaded tag picks up the grant/deny — this only covers the page-load
|
|
224
|
+
* default + script injection.
|
|
225
|
+
*
|
|
226
|
+
* @since 1.0.0-canary.6
|
|
138
227
|
*/
|
|
139
|
-
function
|
|
140
|
-
const
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
228
|
+
export function buildGtagConsentBootstrapScript(options: GtagConsentBootstrapOptions): string {
|
|
229
|
+
const {
|
|
230
|
+
config,
|
|
231
|
+
dataLayerName = DEFAULT_DATA_LAYER_NAME,
|
|
232
|
+
defaultConsent,
|
|
233
|
+
debugMode,
|
|
234
|
+
gaMeasurementId,
|
|
235
|
+
nonce,
|
|
236
|
+
} = options;
|
|
237
|
+
|
|
238
|
+
const gtagScriptUrl = gtagScriptSrc(gaMeasurementId, dataLayerName);
|
|
239
|
+
const configArgs =
|
|
240
|
+
debugMode === true ? `${JSON.stringify(gaMeasurementId)}, { debug_mode: true }` : JSON.stringify(gaMeasurementId);
|
|
241
|
+
const nonceAssignment = nonce === undefined ? "" : `gtagScript.nonce = ${JSON.stringify(nonce)};`;
|
|
242
|
+
const preamble = buildGoogleConsentBootstrapPreamble({
|
|
243
|
+
consentStorageKey: config.storageKey,
|
|
244
|
+
dataLayerName,
|
|
245
|
+
defaultConsent,
|
|
246
|
+
policyVersion: config.policyVersion,
|
|
247
|
+
});
|
|
248
|
+
|
|
249
|
+
// Advanced Consent Mode: consent default first, then always load the tag (even when denied).
|
|
250
|
+
return `${preamble}
|
|
251
|
+
gtag("js", new Date());
|
|
252
|
+
gtag("config", ${configArgs});
|
|
253
|
+
var gtagScript = document.createElement("script");
|
|
254
|
+
gtagScript.async = true;
|
|
255
|
+
gtagScript.src = ${JSON.stringify(gtagScriptUrl)};
|
|
256
|
+
${nonceAssignment}
|
|
257
|
+
document.head.appendChild(gtagScript);
|
|
258
|
+
`;
|
|
151
259
|
}
|
|
152
260
|
|
|
153
|
-
// GA4 rejects event names that don't start with a letter or exceed 40 chars — a `$`-prefixed
|
|
154
|
-
// or otherwise invalid name would be dropped at processing without any signal to the dev.
|
|
155
|
-
const GA4_EVENT_NAME_PATTERN = /^[A-Za-z][\w]{0,39}$/;
|
|
156
|
-
|
|
157
261
|
/**
|
|
158
262
|
* @since 0.5.0-canary.4
|
|
159
263
|
*/
|
|
160
264
|
export interface GoogleAnalyticsDestinationOptions {
|
|
161
|
-
name?: string;
|
|
162
|
-
/**
|
|
163
|
-
* Forward `$page_viewed` as GA4's `page_view`. Off by default: `gtag('config', ...)`
|
|
164
|
-
* sends the initial page_view and GA4's Enhanced Measurement (on by default in admin)
|
|
165
|
-
* tracks SPA history changes, so forwarding here would double-count. Enable only after
|
|
166
|
-
* setting `send_page_view: false` on config and disabling Enhanced Measurement's
|
|
167
|
-
* history-based page views.
|
|
168
|
-
*/
|
|
169
|
-
trackPageViews?: boolean;
|
|
265
|
+
name?: string | undefined;
|
|
170
266
|
}
|
|
171
267
|
|
|
172
268
|
/**
|
|
173
|
-
* Forwards events to `window.gtag
|
|
174
|
-
*
|
|
175
|
-
*
|
|
176
|
-
*
|
|
177
|
-
*
|
|
178
|
-
* so queueing in front of it only delays events and replays stale ones next session.
|
|
269
|
+
* Forwards catalog events to `window.gtag` as GA4 custom events. Page views are not this
|
|
270
|
+
* destination's job: `gtag('config', ...)` sends the initial page_view and GA4's Enhanced
|
|
271
|
+
* Measurement tracks SPA history changes. Requires the gtag.js snippet plus
|
|
272
|
+
* `gtag('config', measurementId)` mounted once by the app (see the consent bootstrap) —
|
|
273
|
+
* gtag.js owns its own batching and unload delivery.
|
|
179
274
|
*
|
|
180
275
|
* @since 0.5.0-canary.4
|
|
181
276
|
*/
|
|
@@ -183,51 +278,19 @@ export function createGoogleAnalyticsDestination(options: GoogleAnalyticsDestina
|
|
|
183
278
|
const name = options.name ?? "google-analytics";
|
|
184
279
|
|
|
185
280
|
return {
|
|
186
|
-
delivery: "immediate",
|
|
187
281
|
name,
|
|
188
|
-
|
|
282
|
+
// Synchronous today, but declared async so a throw here rejects the returned Promise
|
|
283
|
+
// instead of escaping as a synchronous throw — matches Destination.send's contract.
|
|
284
|
+
async send(event) {
|
|
189
285
|
if (typeof window === "undefined" || typeof window.gtag !== "function") {
|
|
190
286
|
return;
|
|
191
287
|
}
|
|
192
288
|
|
|
193
|
-
if (event.name
|
|
194
|
-
// GA4 has no identify event — user_id is set once and rides along on later hits.
|
|
195
|
-
if (event.userId !== undefined) {
|
|
196
|
-
window.gtag("set", { user_id: event.userId });
|
|
197
|
-
}
|
|
198
|
-
|
|
199
|
-
return;
|
|
200
|
-
}
|
|
201
|
-
|
|
202
|
-
if (event.name === "$page_viewed") {
|
|
203
|
-
if (options.trackPageViews === true) {
|
|
204
|
-
// gtag.js attaches page_location/page_title from the live document itself, so
|
|
205
|
-
// only the caller's extra props are forwarded.
|
|
206
|
-
const { href: _href, name: _name, ...extras } = event.props;
|
|
207
|
-
|
|
208
|
-
window.gtag("event", "page_view", toGtagParams(extras));
|
|
209
|
-
}
|
|
210
|
-
|
|
211
|
-
return;
|
|
212
|
-
}
|
|
213
|
-
|
|
214
|
-
if (event.name === "$group") {
|
|
215
|
-
const { groupId, ...traits } = event.props;
|
|
216
|
-
|
|
217
|
-
window.gtag("event", "join_group", toGtagParams({ group_id: groupId, ...traits }));
|
|
218
|
-
|
|
219
|
-
return;
|
|
220
|
-
}
|
|
221
|
-
|
|
222
|
-
if (!GA4_EVENT_NAME_PATTERN.test(event.name)) {
|
|
223
|
-
console.warn(
|
|
224
|
-
`[tracking] "${name}" dropped event "${event.name}" — GA4 event names must start with a letter and contain only letters, digits, or underscores (max 40 chars)`,
|
|
225
|
-
);
|
|
226
|
-
|
|
289
|
+
if (!warnUnlessGa4EventName(name, event.name)) {
|
|
227
290
|
return;
|
|
228
291
|
}
|
|
229
292
|
|
|
230
|
-
window.gtag("event", event.name,
|
|
293
|
+
window.gtag("event", event.name, flattenEventProps(event.properties));
|
|
231
294
|
},
|
|
232
295
|
};
|
|
233
296
|
}
|