@codefast/tracking 0.7.1 → 0.7.2
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 +13 -0
- package/README.md +235 -105
- package/dist/adapters/tanstack-start.d.ts +1 -2
- package/dist/adapters/tanstack-start.js +1 -2
- package/dist/client/ad-framework-consent.d.ts +1 -2
- package/dist/client/ad-framework-consent.js +1 -2
- package/dist/client/browser-cookie.d.ts +1 -2
- package/dist/client/browser-cookie.js +1 -2
- package/dist/client/consent-runtime.d.ts +1 -2
- package/dist/client/consent-runtime.js +1 -2
- package/dist/client/consent-storage.d.ts +1 -2
- package/dist/client/consent-storage.js +1 -2
- package/dist/client/consent-withdrawal.d.ts +1 -2
- package/dist/client/consent-withdrawal.js +1 -2
- package/dist/client/cookie-anonymous-id.d.ts +1 -2
- package/dist/client/cookie-anonymous-id.js +1 -2
- package/dist/client/create-client-tracker.d.ts +1 -2
- package/dist/client/create-client-tracker.js +1 -2
- package/dist/client/gpc.d.ts +1 -2
- package/dist/client/gpc.js +1 -2
- package/dist/client/initial-consent-store.d.ts +1 -2
- package/dist/client/initial-consent-store.js +1 -2
- package/dist/client/is-analytics-allowed.d.ts +1 -2
- package/dist/client/is-analytics-allowed.js +1 -2
- package/dist/client/server-persisted-anonymous-id.d.ts +1 -2
- package/dist/client/server-persisted-anonymous-id.js +1 -2
- package/dist/core/consent-config.d.ts +1 -2
- package/dist/core/consent-config.js +1 -2
- package/dist/core/consent-receipt.d.ts +1 -2
- package/dist/core/consent-receipt.js +1 -2
- package/dist/core/consent.d.ts +1 -2
- package/dist/core/consent.js +1 -2
- package/dist/core/cookie.d.ts +1 -2
- package/dist/core/cookie.js +1 -2
- package/dist/core/destination.d.ts +1 -2
- package/dist/core/destination.js +1 -2
- package/dist/core/event-catalog.d.ts +1 -2
- package/dist/core/event-catalog.js +1 -2
- package/dist/core/event-id.d.ts +1 -2
- package/dist/core/event-id.js +1 -2
- package/dist/core/tracked-event.d.ts +1 -2
- package/dist/core/tracked-event.js +1 -2
- package/dist/destinations/ad-consent.d.ts +1 -2
- package/dist/destinations/ad-consent.js +1 -2
- package/dist/destinations/google-analytics.d.ts +1 -2
- package/dist/destinations/google-analytics.js +1 -2
- package/dist/destinations/google-consent.d.ts +1 -2
- package/dist/destinations/google-consent.js +1 -2
- package/dist/destinations/meta.d.ts +1 -2
- package/dist/destinations/meta.js +1 -2
- package/dist/destinations/microsoft-uet.d.ts +1 -2
- package/dist/destinations/microsoft-uet.js +1 -2
- package/dist/destinations/shared.d.ts +1 -2
- package/dist/destinations/shared.js +1 -2
- package/dist/destinations/tiktok.d.ts +1 -2
- package/dist/destinations/tiktok.js +1 -2
- package/dist/destinations/vercel-analytics.d.ts +1 -2
- package/dist/destinations/vercel-analytics.js +1 -2
- package/dist/index.d.ts +1 -2
- package/dist/index.js +1 -2
- package/dist/react/consent-banner.d.ts +1 -2
- package/dist/react/consent-banner.js +1 -2
- package/dist/react/gtag-consent-bootstrap.d.ts +1 -2
- package/dist/react/gtag-consent-bootstrap.js +1 -2
- package/dist/react/use-consent.d.ts +1 -2
- package/dist/react/use-consent.js +1 -2
- package/dist/react/use-google-consent-sync.d.ts +1 -2
- package/dist/react/use-google-consent-sync.js +1 -2
- package/dist/react/use-initial-consent.d.ts +1 -2
- package/dist/react/use-initial-consent.js +1 -2
- package/dist/server/anonymous-id-cookie.d.ts +1 -2
- package/dist/server/anonymous-id-cookie.js +1 -2
- package/dist/server/consent-receipt-store.d.ts +1 -2
- package/dist/server/consent-receipt-store.js +1 -2
- package/dist/server/consent-receipt.d.ts +1 -2
- package/dist/server/consent-receipt.js +1 -2
- package/dist/server/initial-consent.d.ts +1 -2
- package/dist/server/initial-consent.js +1 -2
- package/dist/server/measurement-protocol.d.ts +1 -2
- package/dist/server/measurement-protocol.js +1 -2
- package/dist/server/region.d.ts +1 -2
- package/dist/server/region.js +1 -2
- package/dist/server/user-deletion.d.ts +1 -2
- package/dist/server/user-deletion.js +1 -2
- package/dist/tooling/import-protection.d.ts +1 -2
- package/dist/tooling/import-protection.js +1 -2
- package/package.json +10 -61
- package/dist/adapters/tanstack-start.d.ts.map +0 -1
- package/dist/adapters/tanstack-start.js.map +0 -1
- package/dist/client/ad-framework-consent.d.ts.map +0 -1
- package/dist/client/ad-framework-consent.js.map +0 -1
- package/dist/client/browser-cookie.d.ts.map +0 -1
- package/dist/client/browser-cookie.js.map +0 -1
- package/dist/client/consent-runtime.d.ts.map +0 -1
- package/dist/client/consent-runtime.js.map +0 -1
- package/dist/client/consent-storage.d.ts.map +0 -1
- package/dist/client/consent-storage.js.map +0 -1
- package/dist/client/consent-withdrawal.d.ts.map +0 -1
- package/dist/client/consent-withdrawal.js.map +0 -1
- package/dist/client/cookie-anonymous-id.d.ts.map +0 -1
- package/dist/client/cookie-anonymous-id.js.map +0 -1
- package/dist/client/create-client-tracker.d.ts.map +0 -1
- package/dist/client/create-client-tracker.js.map +0 -1
- package/dist/client/gpc.d.ts.map +0 -1
- package/dist/client/gpc.js.map +0 -1
- package/dist/client/initial-consent-store.d.ts.map +0 -1
- package/dist/client/initial-consent-store.js.map +0 -1
- package/dist/client/is-analytics-allowed.d.ts.map +0 -1
- package/dist/client/is-analytics-allowed.js.map +0 -1
- package/dist/client/server-persisted-anonymous-id.d.ts.map +0 -1
- package/dist/client/server-persisted-anonymous-id.js.map +0 -1
- package/dist/core/consent-config.d.ts.map +0 -1
- package/dist/core/consent-config.js.map +0 -1
- package/dist/core/consent-receipt.d.ts.map +0 -1
- package/dist/core/consent-receipt.js.map +0 -1
- package/dist/core/consent.d.ts.map +0 -1
- package/dist/core/consent.js.map +0 -1
- package/dist/core/cookie.d.ts.map +0 -1
- package/dist/core/cookie.js.map +0 -1
- package/dist/core/destination.d.ts.map +0 -1
- package/dist/core/destination.js.map +0 -1
- package/dist/core/event-catalog.d.ts.map +0 -1
- package/dist/core/event-catalog.js.map +0 -1
- package/dist/core/event-id.d.ts.map +0 -1
- package/dist/core/event-id.js.map +0 -1
- package/dist/core/tracked-event.d.ts.map +0 -1
- package/dist/core/tracked-event.js.map +0 -1
- package/dist/destinations/ad-consent.d.ts.map +0 -1
- package/dist/destinations/ad-consent.js.map +0 -1
- package/dist/destinations/google-analytics.d.ts.map +0 -1
- package/dist/destinations/google-analytics.js.map +0 -1
- package/dist/destinations/google-consent.d.ts.map +0 -1
- package/dist/destinations/google-consent.js.map +0 -1
- package/dist/destinations/meta.d.ts.map +0 -1
- package/dist/destinations/meta.js.map +0 -1
- package/dist/destinations/microsoft-uet.d.ts.map +0 -1
- package/dist/destinations/microsoft-uet.js.map +0 -1
- package/dist/destinations/shared.d.ts.map +0 -1
- package/dist/destinations/shared.js.map +0 -1
- package/dist/destinations/tiktok.d.ts.map +0 -1
- package/dist/destinations/tiktok.js.map +0 -1
- package/dist/destinations/vercel-analytics.d.ts.map +0 -1
- package/dist/destinations/vercel-analytics.js.map +0 -1
- package/dist/index.d.ts.map +0 -1
- package/dist/index.js.map +0 -1
- package/dist/react/consent-banner.d.ts.map +0 -1
- package/dist/react/consent-banner.js.map +0 -1
- package/dist/react/gtag-consent-bootstrap.d.ts.map +0 -1
- package/dist/react/gtag-consent-bootstrap.js.map +0 -1
- package/dist/react/use-consent.d.ts.map +0 -1
- package/dist/react/use-consent.js.map +0 -1
- package/dist/react/use-google-consent-sync.d.ts.map +0 -1
- package/dist/react/use-google-consent-sync.js.map +0 -1
- package/dist/react/use-initial-consent.d.ts.map +0 -1
- package/dist/react/use-initial-consent.js.map +0 -1
- package/dist/server/anonymous-id-cookie.d.ts.map +0 -1
- package/dist/server/anonymous-id-cookie.js.map +0 -1
- package/dist/server/consent-receipt-store.d.ts.map +0 -1
- package/dist/server/consent-receipt-store.js.map +0 -1
- package/dist/server/consent-receipt.d.ts.map +0 -1
- package/dist/server/consent-receipt.js.map +0 -1
- package/dist/server/initial-consent.d.ts.map +0 -1
- package/dist/server/initial-consent.js.map +0 -1
- package/dist/server/measurement-protocol.d.ts.map +0 -1
- package/dist/server/measurement-protocol.js.map +0 -1
- package/dist/server/region.d.ts.map +0 -1
- package/dist/server/region.js.map +0 -1
- package/dist/server/user-deletion.d.ts.map +0 -1
- package/dist/server/user-deletion.js.map +0 -1
- package/dist/tooling/import-protection.d.ts.map +0 -1
- package/dist/tooling/import-protection.js.map +0 -1
- package/src/adapters/tanstack-start.ts +0 -139
- package/src/client/ad-framework-consent.ts +0 -88
- package/src/client/browser-cookie.ts +0 -16
- package/src/client/consent-runtime.ts +0 -82
- package/src/client/consent-storage.ts +0 -125
- package/src/client/consent-withdrawal.ts +0 -34
- package/src/client/cookie-anonymous-id.ts +0 -116
- package/src/client/create-client-tracker.ts +0 -174
- package/src/client/gpc.ts +0 -15
- package/src/client/initial-consent-store.ts +0 -220
- package/src/client/is-analytics-allowed.ts +0 -45
- package/src/client/server-persisted-anonymous-id.ts +0 -104
- package/src/core/consent-config.ts +0 -27
- package/src/core/consent-receipt.ts +0 -115
- package/src/core/consent.ts +0 -298
- package/src/core/cookie.ts +0 -29
- package/src/core/destination.ts +0 -29
- package/src/core/event-catalog.ts +0 -54
- package/src/core/event-id.ts +0 -8
- package/src/core/tracked-event.ts +0 -14
- package/src/css/consent.css +0 -119
- package/src/destinations/ad-consent.ts +0 -29
- package/src/destinations/google-analytics.ts +0 -304
- package/src/destinations/google-consent.ts +0 -166
- package/src/destinations/meta.ts +0 -98
- package/src/destinations/microsoft-uet.ts +0 -88
- package/src/destinations/shared.ts +0 -51
- package/src/destinations/tiktok.ts +0 -87
- package/src/destinations/vercel-analytics.ts +0 -41
- package/src/index.ts +0 -171
- package/src/react/consent-banner.tsx +0 -386
- package/src/react/gtag-consent-bootstrap.tsx +0 -50
- package/src/react/use-consent.ts +0 -123
- package/src/react/use-google-consent-sync.ts +0 -40
- package/src/react/use-initial-consent.ts +0 -22
- package/src/server/anonymous-id-cookie.ts +0 -105
- package/src/server/consent-receipt-store.ts +0 -79
- package/src/server/consent-receipt.ts +0 -89
- package/src/server/initial-consent.ts +0 -48
- package/src/server/measurement-protocol.ts +0 -116
- package/src/server/region.ts +0 -77
- package/src/server/user-deletion.ts +0 -97
- package/src/tooling/import-protection.ts +0 -22
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,18 @@
|
|
|
1
1
|
# @codefast/tracking
|
|
2
2
|
|
|
3
|
+
## 0.7.2
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- [#791](https://github.com/codefastlabs/codefast/pull/791) [`37a212b`](https://github.com/codefastlabs/codefast/commit/37a212b4d805588413159e11e872b98db82326bf) Thanks [@thevuong](https://github.com/thevuong)! - Point the README's license badge and "License" section at the package's own `LICENSE` file instead of the monorepo root.
|
|
8
|
+
|
|
9
|
+
- [#796](https://github.com/codefastlabs/codefast/pull/796) [`ba04d27`](https://github.com/codefastlabs/codefast/commit/ba04d2703c59a1677f52e6a9fffd0ec202328218) Thanks [@thevuong](https://github.com/thevuong)! - Rewrite the README around one structure — what the package is, installation and requirements, a complete quick start,
|
|
10
|
+
the concepts in learning order, then the documents and the license — with every API claim checked against the current
|
|
11
|
+
code and no figures that go stale.
|
|
12
|
+
|
|
13
|
+
- [#784](https://github.com/codefastlabs/codefast/pull/784) [`ad2f93a`](https://github.com/codefastlabs/codefast/commit/ad2f93a688e99c3ed8be6ceeae9d6cdd6be861bc) Thanks [@thevuong](https://github.com/thevuong)! - Ship the MIT `LICENSE` file in the published package. `files` already listed it, but the file was missing from the
|
|
14
|
+
package directory, so the tarball had none.
|
|
15
|
+
|
|
3
16
|
## 0.7.1
|
|
4
17
|
|
|
5
18
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -1,25 +1,31 @@
|
|
|
1
1
|
# @codefast/tracking
|
|
2
2
|
|
|
3
|
-
Consent-gated, type-safe event tracking for TanStack Start apps.
|
|
3
|
+
Consent-gated, type-safe event tracking for TanStack Start apps that ship to a CDN-cached (ISR) deployment.
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/@codefast/tracking)
|
|
6
|
-
[](
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
6
|
+
[](./LICENSE)
|
|
7
|
+
|
|
8
|
+
## Overview
|
|
9
|
+
|
|
10
|
+
`@codefast/tracking` is consent-gated, type-safe event tracking for TanStack Start apps deployed to a CDN cache (ISR).
|
|
11
|
+
You define your events over a Standard Schema catalog, and `track()` infers each event's name and properties, validates
|
|
12
|
+
them at runtime, and forwards them to your destinations — but only when consent allows.
|
|
13
|
+
|
|
14
|
+
Because ISR HTML is shared across visitors, the package bakes the strictest consent default into the cached render, then
|
|
15
|
+
resolves the region-correct default per visitor over a private server-function lane.
|
|
16
|
+
|
|
17
|
+
- **One catalog, typed end to end.** The app defines its events over any [Standard Schema](https://standardschema.dev)
|
|
18
|
+
library (zod, `zod/mini`, valibot, and so on). `track()` infers the event name and its properties from the catalog and
|
|
19
|
+
validates them at runtime, and the client bundle pays only for the schema library the app already ships.
|
|
20
|
+
- **One consent config, every surface.** `ConsentConfig` holds the storage key, the policy version, and the requested
|
|
21
|
+
purposes. The React hooks, the tracker gate, and the pre-hydration Google tag bootstrap all take the same object, so
|
|
22
|
+
nothing drifts.
|
|
23
|
+
- **ISR-safe by design.** Shared HTML bakes the strictest consent default; the region-correct default arrives per
|
|
24
|
+
visitor over a private server-function lane.
|
|
25
|
+
- **Per-category decisions.** Consent is `{ ads, analytics }`, mirroring Google Consent Mode v2, with region-resolved
|
|
26
|
+
opt-in or opt-out modes, and Global Privacy Control honored as an ads opt-out.
|
|
27
|
+
- **Destinations own their transport.** gtag.js and Vercel Analytics batch in-page, so `track()` is fire-and-forget, and
|
|
28
|
+
a failing destination never breaks the interaction.
|
|
23
29
|
|
|
24
30
|
## Installation
|
|
25
31
|
|
|
@@ -27,10 +33,17 @@ history has them if a real need returns.
|
|
|
27
33
|
pnpm add @codefast/tracking
|
|
28
34
|
```
|
|
29
35
|
|
|
30
|
-
|
|
31
|
-
|
|
36
|
+
`@codefast/tracking` requires Node.js 24 or later. Its one runtime dependency is `@standard-schema/spec`. Every peer is
|
|
37
|
+
optional, needed only by the surface that uses it: `react` and `react-dom` (19 or later) for the `react/*` subpaths,
|
|
38
|
+
`@tanstack/react-start` (1.168 or later) for `adapters/tanstack-start`, and `@vercel/analytics` for
|
|
39
|
+
`destinations/vercel-analytics`.
|
|
40
|
+
|
|
41
|
+
The package is published on 0.x and versioned on its own track: breaking changes ship as minor versions, so pin the
|
|
42
|
+
minor version when you need stability.
|
|
32
43
|
|
|
33
|
-
## Quick
|
|
44
|
+
## Quick start
|
|
45
|
+
|
|
46
|
+
Three modules: the consent contract, the live consent runtime derived from it, and the catalog plus tracker.
|
|
34
47
|
|
|
35
48
|
```ts
|
|
36
49
|
// consent.ts — the one consent contract every surface shares
|
|
@@ -48,7 +61,7 @@ export const consentConfig = defineConsentConfig({
|
|
|
48
61
|
import { createConsentRuntime } from "@codefast/tracking/client/consent-runtime";
|
|
49
62
|
|
|
50
63
|
import { consentConfig } from "./consent";
|
|
51
|
-
import { resolveVisitorConsent } from "./resolve-visitor-consent"; // server
|
|
64
|
+
import { resolveVisitorConsent } from "./resolve-visitor-consent"; // server function, see "The ISR lane"
|
|
52
65
|
|
|
53
66
|
export const consentRuntime = createConsentRuntime({
|
|
54
67
|
config: consentConfig,
|
|
@@ -72,10 +85,10 @@ export const catalog = defineEventCatalog({
|
|
|
72
85
|
});
|
|
73
86
|
|
|
74
87
|
export const tracker = createClientTracker({
|
|
75
|
-
anonymousId: () => "...", // see
|
|
88
|
+
anonymousId: () => "...", // see "Durable anonymous id"
|
|
76
89
|
catalog,
|
|
77
90
|
destinations: [
|
|
78
|
-
// Vercel is cookieless and receives no identifier
|
|
91
|
+
// Vercel is cookieless and receives no identifier, so it may keep counting before consent.
|
|
79
92
|
createVercelAnalyticsDestination({ consentRequirement: "exempt" }),
|
|
80
93
|
createGoogleAnalyticsDestination(),
|
|
81
94
|
],
|
|
@@ -85,92 +98,200 @@ export const tracker = createClientTracker({
|
|
|
85
98
|
tracker.track("copy_code", { name: "button" }); // typed + runtime-validated
|
|
86
99
|
```
|
|
87
100
|
|
|
88
|
-
|
|
89
|
-
|
|
101
|
+
`anonymousId` is a callback, not a value: the tracker calls it per allowed event, so the id is only minted once an event
|
|
102
|
+
is actually permitted to send. `isAnalyticsAllowed` is consulted before every event; while it returns `false`, only
|
|
103
|
+
`consentRequirement: "exempt"` destinations still receive events, stripped of identifiers. Pass `isExemptionAllowed` to
|
|
104
|
+
gate even that lane per region, and `onDeliveryError` to meter a destination that throws or rejects.
|
|
90
105
|
|
|
91
106
|
## Event catalog
|
|
92
107
|
|
|
93
|
-
The package ships no events and no schema library
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
108
|
+
The package ships no events and no schema library. Every app builds its own catalog with `defineEventCatalog` over the
|
|
109
|
+
Standard Schema validator it already uses. `track()` infers both the event name and its properties from the catalog,
|
|
110
|
+
then validates the properties at runtime and hands destinations the parsed output (unknown keys stripped, transforms
|
|
111
|
+
applied). A validation failure throws at the call site. Schemas that validate asynchronously are rejected, because
|
|
112
|
+
tracking sits on synchronous call paths.
|
|
97
113
|
|
|
98
114
|
## Subpaths
|
|
99
115
|
|
|
100
|
-
The root `@codefast/tracking` is the **client entry
|
|
101
|
-
consent model
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
`
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
Every built module is also its own subpath (
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
`
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
`
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
116
|
+
The root `@codefast/tracking` is the **client entry**. It re-exports the isomorphic core (catalog types, `Destination`,
|
|
117
|
+
the consent model and `ConsentConfig`) plus the whole browser-side surface: `createClientTracker`,
|
|
118
|
+
`createConsentRuntime`, the `useConsent`/`ConsentBanner`/`GtagConsentBootstrap` React bindings, and the client-lane
|
|
119
|
+
destinations (Google Analytics, Meta, TikTok, Microsoft UET). Server-only lanes are never re-exported from the root.
|
|
120
|
+
|
|
121
|
+
| Subpath | Lane | Contents |
|
|
122
|
+
| -------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------- |
|
|
123
|
+
| `@codefast/tracking` | client | Core + tracker + consent runtime + React bindings + gtag/ad-network destinations |
|
|
124
|
+
| `@codefast/tracking/destinations/vercel-analytics` | client | Its own subpath so the `@vercel/analytics` peer is only pulled in when used |
|
|
125
|
+
| `@codefast/tracking/core/*` | isomorphic | `consent`, `consent-config`, `consent-receipt`, `cookie`, `destination`, `event-catalog`, `event-id` |
|
|
126
|
+
| `@codefast/tracking/server/*` | server-only | `initial-consent`, `region`, `anonymous-id-cookie`, `consent-receipt`, `consent-receipt-store`, ... |
|
|
127
|
+
| `@codefast/tracking/adapters/tanstack-start` | server-only | Request/response glue over `@tanstack/react-start/server` |
|
|
128
|
+
| `@codefast/tracking/tooling/import-protection` | build | `SERVER_ONLY_SUBPATHS`, the deny-list for client bundles |
|
|
129
|
+
| `@codefast/tracking/css/consent.css` | client | Optional plain-CSS theme for the consent banner |
|
|
130
|
+
|
|
131
|
+
Every built module is also its own subpath (for example `@codefast/tracking/client/gpc`) for granular imports. Server
|
|
132
|
+
code imports the core it needs from `@codefast/tracking/core/*`, never from the client root. There is no server-side
|
|
133
|
+
tracker: destinations batch in-page, and the server half of the package is consent resolution plus cookie persistence.
|
|
134
|
+
|
|
135
|
+
## Consent
|
|
136
|
+
|
|
137
|
+
`ConsentDecision` is per purpose (`{ ads, analytics }`). The region resolves the mode: the EU (plus the UK, Iceland,
|
|
138
|
+
Liechtenstein, and Norway) and Vietnam are **opt-in**; the US and unrecognized countries are **opt-out**. Under opt-out,
|
|
139
|
+
a Global Privacy Control signal forces `ads` denied and leaves first-party analytics alone. Stored records carry a
|
|
140
|
+
`policyVersion`; a malformed record, or one saved under another version, counts as no decision and re-prompts.
|
|
141
|
+
|
|
142
|
+
```tsx
|
|
143
|
+
import { useConsent } from "@codefast/tracking/react/use-consent";
|
|
144
|
+
import { useInitialConsent } from "@codefast/tracking/react/use-initial-consent";
|
|
145
|
+
|
|
146
|
+
import { consentConfig } from "./consent";
|
|
147
|
+
import { consentRuntime } from "./consent-runtime";
|
|
148
|
+
|
|
149
|
+
export function useAppConsent() {
|
|
150
|
+
// Strictest default until the server lane answers — see "The ISR lane".
|
|
151
|
+
const { initialConsent, isResolved } = useInitialConsent(consentRuntime.initialConsentStore);
|
|
152
|
+
const consent = useConsent({
|
|
153
|
+
config: consentConfig,
|
|
154
|
+
mode: initialConsent.mode,
|
|
155
|
+
storage: consentRuntime.storage, // one shared instance — must be a stable reference
|
|
156
|
+
});
|
|
157
|
+
|
|
158
|
+
return { consent, isResolved };
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
- `useConsent({ config, mode, storage, hasGlobalPrivacyControlSignal?, onDecision? })` bridges the stored decision to
|
|
163
|
+
React through `useSyncExternalStore`. It returns `decision`, `effectiveConsent`, `isAnalyticsAllowed`,
|
|
164
|
+
`isPromptNeeded`, and the `grantAll`/`denyAll`/`saveDecision` actions. A decision saved in another tab syncs through
|
|
165
|
+
the storage subscription.
|
|
166
|
+
- `ConsentBanner` is headless and composable: `ConsentBannerTitle`, `ConsentBannerDescription`, `ConsentBannerActions`,
|
|
167
|
+
`ConsentBannerAccept`, `ConsentBannerReject`, `ConsentBannerCustomize`, `ConsentBannerPreferences`,
|
|
168
|
+
`ConsentBannerCategory`, and `ConsentBannerSave`. The root takes `consent` (the `useConsent` result) and an optional
|
|
169
|
+
`open` override, renders nothing unless `consent.isPromptNeeded`, and flips `data-state` between `prompt` and
|
|
170
|
+
`preferences`. Style the `data-slot` attributes yourself or import `@codefast/tracking/css/consent.css`.
|
|
171
|
+
- `ConsentToggle` is the always-visible control opt-out regions need. By default it flips only `ads`; pass
|
|
172
|
+
`toggledCategories={["analytics"]}` (or both) for a broader opt-out.
|
|
173
|
+
- `createConsentWithdrawalHandler({ clearAnonymousId?, clearGoogleAnalyticsCookies? })` returns an `onDecision` handler
|
|
174
|
+
that clears first-party identifiers when analytics is denied.
|
|
175
|
+
|
|
176
|
+
## The ISR lane
|
|
177
|
+
|
|
178
|
+
CDN-cached HTML is shared across visitors, so no render may read geo. Bake `STRICTEST_INITIAL_CONSENT` into the shared
|
|
179
|
+
render (and into `GtagConsentBootstrap`), then resolve the region-correct default per visitor after hydration.
|
|
180
|
+
|
|
181
|
+
```ts
|
|
182
|
+
// initial-consent-from-request.server.ts — server-only module
|
|
183
|
+
import { resolveInitialConsentFromRequest } from "@codefast/tracking/adapters/tanstack-start";
|
|
184
|
+
|
|
185
|
+
import { consentConfig } from "./consent";
|
|
186
|
+
|
|
187
|
+
export function initialConsentFromRequest() {
|
|
188
|
+
return resolveInitialConsentFromRequest({ requestedCategories: consentConfig.requestedCategories });
|
|
189
|
+
}
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
```ts
|
|
193
|
+
// resolve-visitor-consent.ts — the server function the client calls
|
|
194
|
+
import { createServerFn } from "@tanstack/react-start";
|
|
195
|
+
|
|
196
|
+
import { initialConsentFromRequest } from "./initial-consent-from-request.server";
|
|
197
|
+
|
|
198
|
+
export const resolveVisitorConsent = createServerFn({ method: "GET" }).handler(() => initialConsentFromRequest());
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
`resolveInitialConsentFromRequest` reads the country header (`x-vercel-ip-country` by default; override with
|
|
202
|
+
`countryHeaderName`) and `sec-gpc`, stamps `cache-control: private, no-store`, and fails closed to the strictest default
|
|
203
|
+
when the header is missing — an unknown visitor is never treated as a known non-EU visitor.
|
|
204
|
+
|
|
205
|
+
`createConsentRuntime` owns the client half: the strictest default until the server answers, a single in-flight request,
|
|
206
|
+
a per-session cache under `initialConsentSessionStorageKey`, and a fail-closed but retryable error path. Call
|
|
207
|
+
`consentRuntime.ensureInitialConsentResolved()` at router creation (window-guarded) so the round trip overlaps
|
|
208
|
+
hydration, then read the result reactively with `useInitialConsent(consentRuntime.initialConsentStore)`, as in the
|
|
209
|
+
Consent section: `initialConsent.mode` feeds `useConsent`, and `isResolved` gates region-dependent UI so an opt-in
|
|
210
|
+
banner never flashes at an opt-out visitor. The hook also kicks resolution on mount, so the early call is an
|
|
211
|
+
optimization, not a requirement.
|
|
212
|
+
|
|
213
|
+
## Durable anonymous id
|
|
214
|
+
|
|
215
|
+
The client mints, the server persists. `createServerPersistedAnonymousId` mints a UUID cookie lazily — only once an
|
|
216
|
+
event is allowed to send — and asks the server to re-issue it via `Set-Cookie`, which is what lets the id outlive the
|
|
217
|
+
cap browsers put on script-written cookies. The server half is one line per endpoint.
|
|
218
|
+
|
|
219
|
+
```ts
|
|
220
|
+
// anonymous-id.ts
|
|
221
|
+
import {
|
|
222
|
+
clearAnonymousIdResponseCookie,
|
|
223
|
+
setAnonymousIdResponseCookie,
|
|
224
|
+
} from "@codefast/tracking/adapters/tanstack-start";
|
|
225
|
+
import { createServerFn } from "@tanstack/react-start";
|
|
226
|
+
|
|
227
|
+
export const ANONYMOUS_ID_COOKIE_NAME = "my-app-anon-id";
|
|
228
|
+
|
|
229
|
+
export const persistAnonymousIdCookie = createServerFn({ method: "POST" })
|
|
230
|
+
.validator((data: { id: string }) => data)
|
|
231
|
+
.handler(({ data }) => {
|
|
232
|
+
setAnonymousIdResponseCookie({ cookieName: ANONYMOUS_ID_COOKIE_NAME, id: data.id });
|
|
233
|
+
});
|
|
234
|
+
|
|
235
|
+
export const clearAnonymousIdCookie = createServerFn({ method: "POST" }).handler(() => {
|
|
236
|
+
clearAnonymousIdResponseCookie(ANONYMOUS_ID_COOKIE_NAME);
|
|
237
|
+
});
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
```ts
|
|
241
|
+
import { createServerPersistedAnonymousId } from "@codefast/tracking/client/server-persisted-anonymous-id";
|
|
242
|
+
|
|
243
|
+
import { ANONYMOUS_ID_COOKIE_NAME, clearAnonymousIdCookie, persistAnonymousIdCookie } from "./anonymous-id";
|
|
244
|
+
|
|
245
|
+
export const anonymousId = createServerPersistedAnonymousId({
|
|
246
|
+
clearOnServer: () => clearAnonymousIdCookie(),
|
|
247
|
+
cookieName: ANONYMOUS_ID_COOKIE_NAME,
|
|
248
|
+
persist: (id) => persistAnonymousIdCookie({ data: { id } }),
|
|
249
|
+
});
|
|
250
|
+
|
|
251
|
+
// createClientTracker({ anonymousId: anonymousId.getOrCreate, ... })
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
`setAnonymousIdResponseCookie` throws unless the id is exactly UUID-shaped, so a public server function can never echo
|
|
255
|
+
attacker input into a response header. Wire `anonymousId.clear` into `createConsentWithdrawalHandler` so a withdrawal
|
|
256
|
+
expires the cookie on both sides.
|
|
257
|
+
|
|
258
|
+
## Google tag
|
|
259
|
+
|
|
260
|
+
`GtagConsentBootstrap` renders the pre-hydration inline script for advanced Consent Mode: it applies the Consent Mode v2
|
|
261
|
+
`default` signal (a stored decision wins over the baked `defaultConsent`), then always loads gtag.js so cookieless pings
|
|
262
|
+
and consent modeling can run even when storage is denied.
|
|
263
|
+
|
|
264
|
+
```tsx
|
|
265
|
+
import { STRICTEST_INITIAL_CONSENT } from "@codefast/tracking";
|
|
266
|
+
import { GtagConsentBootstrap } from "@codefast/tracking/react/gtag-consent-bootstrap";
|
|
267
|
+
|
|
268
|
+
import { consentConfig } from "./consent";
|
|
269
|
+
|
|
270
|
+
export function GoogleTag() {
|
|
271
|
+
return (
|
|
272
|
+
<GtagConsentBootstrap
|
|
273
|
+
config={consentConfig}
|
|
274
|
+
defaultConsent={STRICTEST_INITIAL_CONSENT.defaultConsent}
|
|
275
|
+
gaMeasurementId="G-XXXXXXX"
|
|
276
|
+
/>
|
|
277
|
+
);
|
|
278
|
+
}
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
Optional props: `dataLayerName`, `debugMode`, and a CSP `nonce` that is stamped on both the host script and the injected
|
|
282
|
+
gtag.js tag. Page views are gtag's own job (`config` plus Enhanced Measurement); `createGoogleAnalyticsDestination` only
|
|
283
|
+
forwards catalog events. Runtime decision changes go through `useGoogleConsentSync(consent, { loadGtagScript? })`, which
|
|
284
|
+
emits `update` whenever a stored decision exists (including cross-tab saves), or through `updateGoogleConsent` directly.
|
|
166
285
|
|
|
167
286
|
## Keeping server-only subpaths out of client bundles
|
|
168
287
|
|
|
169
|
-
|
|
170
|
-
|
|
288
|
+
`server/*` and `adapters/*` must never enter a client bundle. `SERVER_ONLY_SUBPATHS` is the package's own deny-list as
|
|
289
|
+
picomatch patterns; spread it into TanStack Start's import protection so the list versions with the package instead of
|
|
290
|
+
going stale in your config.
|
|
171
291
|
|
|
172
292
|
```ts
|
|
173
293
|
import { SERVER_ONLY_SUBPATHS } from "@codefast/tracking/tooling/import-protection";
|
|
294
|
+
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
|
|
174
295
|
|
|
175
296
|
tanstackStart({
|
|
176
297
|
importProtection: {
|
|
@@ -179,15 +300,24 @@ tanstackStart({
|
|
|
179
300
|
});
|
|
180
301
|
```
|
|
181
302
|
|
|
182
|
-
A violation is mocked with a console diagnostic in dev and fails the build in prod, with a trace of the offending import
|
|
183
|
-
chain.
|
|
184
|
-
|
|
185
303
|
## Reference consumer
|
|
186
304
|
|
|
187
|
-
[`apps/ui
|
|
188
|
-
|
|
189
|
-
|
|
305
|
+
[`apps/ui/src/features/tracking`](../../apps/ui/src/features/tracking/) wires everything above on a real ISR-deployed
|
|
306
|
+
TanStack Start site: the consent config and runtime, the banner and the persistent toggle, the gtag bootstrap, the
|
|
307
|
+
durable anonymous id, and the private server-function consent lane.
|
|
308
|
+
|
|
309
|
+
## Documentation
|
|
310
|
+
|
|
311
|
+
- [codefastlabs.com/docs/tracking](https://codefastlabs.com/docs/tracking) — the rendered docs.
|
|
312
|
+
- [`spec/`](./spec/README.md) — the behavioural contract as language-neutral documents, one per concern (event model,
|
|
313
|
+
consent, identity, tracker, destinations, server lane, security, plus the commercial-scope extensions), each ending in
|
|
314
|
+
conformance vectors.
|
|
315
|
+
- [`CHANGELOG.md`](./CHANGELOG.md) — release notes per version.
|
|
316
|
+
|
|
317
|
+
## Contributing
|
|
318
|
+
|
|
319
|
+
See the repository [contributing guide](../../CONTRIBUTING.md) for the toolchain, test taxonomy, and release flow.
|
|
190
320
|
|
|
191
321
|
## License
|
|
192
322
|
|
|
193
|
-
[MIT](
|
|
323
|
+
Released under the [MIT License](./LICENSE).
|
|
@@ -80,5 +80,4 @@ export interface RecordConsentReceiptFromRequestOptions {
|
|
|
80
80
|
*
|
|
81
81
|
* @since 0.5.0-canary.6
|
|
82
82
|
*/
|
|
83
|
-
export declare function recordConsentReceiptFromRequest(options: RecordConsentReceiptFromRequestOptions): Promise<ConsentReceiptAck>;
|
|
84
|
-
//# sourceMappingURL=tanstack-start.d.ts.map
|
|
83
|
+
export declare function recordConsentReceiptFromRequest(options: RecordConsentReceiptFromRequestOptions): Promise<ConsentReceiptAck>;
|
|
@@ -70,5 +70,4 @@ export async function recordConsentReceiptFromRequest(options) {
|
|
|
70
70
|
const receipt = buildConsentReceipt({ input: options.input, rawIp, sign: options.sign });
|
|
71
71
|
await options.store.append(receipt);
|
|
72
72
|
return { receiptId: receipt.receiptId, timestamp: receipt.timestamp };
|
|
73
|
-
}
|
|
74
|
-
//# sourceMappingURL=tanstack-start.js.map
|
|
73
|
+
}
|
|
@@ -5,5 +5,4 @@
|
|
|
5
5
|
*
|
|
6
6
|
* @since 0.5.0-canary.6
|
|
7
7
|
*/
|
|
8
|
-
export declare function writeBrowserCookie(cookieName: string, value: string, maxAgeSeconds: number): void;
|
|
9
|
-
//# sourceMappingURL=browser-cookie.d.ts.map
|
|
8
|
+
export declare function writeBrowserCookie(cookieName: string, value: string, maxAgeSeconds: number): void;
|
|
@@ -11,5 +11,4 @@ export function writeBrowserCookie(cookieName, value, maxAgeSeconds) {
|
|
|
11
11
|
}
|
|
12
12
|
const secure = globalThis.location.protocol === "https:" ? "; secure" : "";
|
|
13
13
|
document.cookie = `${cookieName}=${value}; path=/; max-age=${String(maxAgeSeconds)}; samesite=lax${secure}`;
|
|
14
|
-
}
|
|
15
|
-
//# sourceMappingURL=browser-cookie.js.map
|
|
14
|
+
}
|
|
@@ -51,5 +51,4 @@ export interface ConsentRuntime {
|
|
|
51
51
|
*
|
|
52
52
|
* @since 0.5.0-canary.6
|
|
53
53
|
*/
|
|
54
|
-
export declare function createConsentRuntime(options: ConsentRuntimeOptions): ConsentRuntime;
|
|
55
|
-
//# sourceMappingURL=consent-runtime.d.ts.map
|
|
54
|
+
export declare function createConsentRuntime(options: ConsentRuntimeOptions): ConsentRuntime;
|
|
@@ -17,5 +17,4 @@ import type { ConsentStorage } from "#/core/consent";
|
|
|
17
17
|
*
|
|
18
18
|
* @since 0.5.0-canary.4
|
|
19
19
|
*/
|
|
20
|
-
export declare function createLocalStorageConsentStorage(storageKey: string): ConsentStorage;
|
|
21
|
-
//# sourceMappingURL=consent-storage.d.ts.map
|
|
20
|
+
export declare function createLocalStorageConsentStorage(storageKey: string): ConsentStorage;
|
|
@@ -16,5 +16,4 @@ export interface ConsentWithdrawalHandlerOptions {
|
|
|
16
16
|
*
|
|
17
17
|
* @since 0.5.0-canary.6
|
|
18
18
|
*/
|
|
19
|
-
export declare function createConsentWithdrawalHandler(options: ConsentWithdrawalHandlerOptions): (decision: ConsentDecision) => void;
|
|
20
|
-
//# sourceMappingURL=consent-withdrawal.d.ts.map
|
|
19
|
+
export declare function createConsentWithdrawalHandler(options: ConsentWithdrawalHandlerOptions): (decision: ConsentDecision) => void;
|
|
@@ -41,5 +41,4 @@ export interface CookieAnonymousId {
|
|
|
41
41
|
*
|
|
42
42
|
* @since 0.5.0-canary.6
|
|
43
43
|
*/
|
|
44
|
-
export declare function createCookieAnonymousId(options: CookieAnonymousIdOptions): CookieAnonymousId;
|
|
45
|
-
//# sourceMappingURL=cookie-anonymous-id.d.ts.map
|
|
44
|
+
export declare function createCookieAnonymousId(options: CookieAnonymousIdOptions): CookieAnonymousId;
|
|
@@ -62,5 +62,4 @@ export interface ClientTracker<Catalog extends EventCatalog> {
|
|
|
62
62
|
*
|
|
63
63
|
* @since 0.5.0-canary.4
|
|
64
64
|
*/
|
|
65
|
-
export declare function createClientTracker<Catalog extends EventCatalog>(options: ClientTrackerOptions<Catalog>): ClientTracker<Catalog>;
|
|
66
|
-
//# sourceMappingURL=create-client-tracker.d.ts.map
|
|
65
|
+
export declare function createClientTracker<Catalog extends EventCatalog>(options: ClientTrackerOptions<Catalog>): ClientTracker<Catalog>;
|
package/dist/client/gpc.d.ts
CHANGED
package/dist/client/gpc.js
CHANGED
|
@@ -61,5 +61,4 @@ export interface InitialConsentStore {
|
|
|
61
61
|
*
|
|
62
62
|
* @since 0.5.0-canary.6
|
|
63
63
|
*/
|
|
64
|
-
export declare function createInitialConsentStore(options: InitialConsentStoreOptions): InitialConsentStore;
|
|
65
|
-
//# sourceMappingURL=initial-consent-store.d.ts.map
|
|
64
|
+
export declare function createInitialConsentStore(options: InitialConsentStoreOptions): InitialConsentStore;
|
|
@@ -24,5 +24,4 @@ export interface IsAnalyticsAllowedOptions {
|
|
|
24
24
|
*
|
|
25
25
|
* @since 0.5.0-canary.6
|
|
26
26
|
*/
|
|
27
|
-
export declare function createIsAnalyticsAllowed(options: IsAnalyticsAllowedOptions): () => boolean;
|
|
28
|
-
//# sourceMappingURL=is-analytics-allowed.d.ts.map
|
|
27
|
+
export declare function createIsAnalyticsAllowed(options: IsAnalyticsAllowedOptions): () => boolean;
|