@codefast/tracking 0.5.0-canary.5 → 1.0.0-canary.7
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 +220 -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 +203 -108
- 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,46 @@
|
|
|
1
|
+
import type { ConsentCategory, InitialConsent } from "#/core/consent";
|
|
2
|
+
import { resolveConsentMode, resolveDefaultConsent, STRICTEST_INITIAL_CONSENT } from "#/core/consent";
|
|
3
|
+
import { resolveRegionFromCountryCode } from "#/server/region";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* @since 1.0.0-canary.6
|
|
7
|
+
*/
|
|
8
|
+
export interface InitialConsentOptions {
|
|
9
|
+
/** ISO 3166-1 alpha-2 from the geo header; missing → the strictest opt-in default. */
|
|
10
|
+
countryCode: string | undefined;
|
|
11
|
+
/** Honored as an ads-only opt-out on the default decision. */
|
|
12
|
+
hasGlobalPrivacyControlSignal?: boolean | undefined;
|
|
13
|
+
/** Categories the app's prompt asks about — opt-out regions grant exactly these by default. */
|
|
14
|
+
requestedCategories: ReadonlyArray<ConsentCategory>;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Pure region → mode → default-consent resolution for server functions (or a fail-closed
|
|
19
|
+
* bake when country is unknown). Named with the `resolve*` family it composes.
|
|
20
|
+
*
|
|
21
|
+
* @remarks
|
|
22
|
+
* A missing country code means an unknown visitor (a prerender crawl, a host without a
|
|
23
|
+
* geo header) — not a known non-EU visitor — so it fails closed to
|
|
24
|
+
* {@link STRICTEST_INITIAL_CONSENT} instead of `"other"`'s opt-out. Conflating the two
|
|
25
|
+
* would grant analytics by default to every visitor, EU included, on a geo-less host.
|
|
26
|
+
*
|
|
27
|
+
* @since 1.0.0-canary.6
|
|
28
|
+
*/
|
|
29
|
+
export function resolveInitialConsent(options: InitialConsentOptions): InitialConsent {
|
|
30
|
+
if (!options.countryCode) {
|
|
31
|
+
return STRICTEST_INITIAL_CONSENT;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
const region = resolveRegionFromCountryCode(options.countryCode);
|
|
35
|
+
const mode = resolveConsentMode(region);
|
|
36
|
+
|
|
37
|
+
return {
|
|
38
|
+
defaultConsent: resolveDefaultConsent({
|
|
39
|
+
hasGlobalPrivacyControlSignal: options.hasGlobalPrivacyControlSignal ?? false,
|
|
40
|
+
mode,
|
|
41
|
+
requestedCategories: options.requestedCategories,
|
|
42
|
+
}),
|
|
43
|
+
mode,
|
|
44
|
+
region,
|
|
45
|
+
};
|
|
46
|
+
}
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
import type { ConsentDecision } from "#/core/consent";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* A GA4 event for the Measurement Protocol. `params` are flat scalars — GA4 rejects nested values and booleans.
|
|
5
|
+
*
|
|
6
|
+
* @since 1.0.0-canary.7
|
|
7
|
+
*/
|
|
8
|
+
export interface MeasurementProtocolEvent {
|
|
9
|
+
name: string;
|
|
10
|
+
params?: Record<string, number | string> | undefined;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* The GA4 MP `consent` object — the two ad-consent signals the payload accepts.
|
|
15
|
+
*
|
|
16
|
+
* @since 1.0.0-canary.7
|
|
17
|
+
*/
|
|
18
|
+
export interface MeasurementProtocolConsent {
|
|
19
|
+
ad_personalization: "DENIED" | "GRANTED";
|
|
20
|
+
ad_user_data: "DENIED" | "GRANTED";
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Maps the package `ConsentDecision` to GA4 MP consent signals — `ads` drives both ad fields.
|
|
25
|
+
*
|
|
26
|
+
* @since 1.0.0-canary.7
|
|
27
|
+
*/
|
|
28
|
+
export function toMeasurementProtocolConsent(decision: ConsentDecision): MeasurementProtocolConsent {
|
|
29
|
+
const state = decision.ads ? "GRANTED" : "DENIED";
|
|
30
|
+
|
|
31
|
+
return { ad_personalization: state, ad_user_data: state };
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* Extracts the GA4 `client_id` from a `_ga` cookie value, e.g.
|
|
36
|
+
* `GA1.1.1809596761.1693829043` → `1809596761.1693829043` (everything past the
|
|
37
|
+
* `GA1.<version>.` prefix). The `_ga` layout is community-established, not part of the
|
|
38
|
+
* Measurement Protocol reference, so anything that doesn't parse returns `undefined` rather
|
|
39
|
+
* than sending a malformed id.
|
|
40
|
+
*
|
|
41
|
+
* @since 1.0.0-canary.7
|
|
42
|
+
*/
|
|
43
|
+
export function extractGaClientId(gaCookieValue: string | undefined): string | undefined {
|
|
44
|
+
if (!gaCookieValue) {
|
|
45
|
+
return undefined;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
const segments = gaCookieValue.split(".");
|
|
49
|
+
|
|
50
|
+
if (segments.length < 4 || segments[0] !== "GA1") {
|
|
51
|
+
return undefined;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
return segments.slice(2).join(".");
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* The one network primitive the sender needs — injected so the package ships no HTTP client.
|
|
59
|
+
*
|
|
60
|
+
* @since 1.0.0-canary.7
|
|
61
|
+
*/
|
|
62
|
+
export type MeasurementProtocolTransport = (request: { body: string; url: string }) => Promise<void>;
|
|
63
|
+
|
|
64
|
+
/** Default GA4 collection origin; use `https://region1.google-analytics.com` for EU data residency. */
|
|
65
|
+
const DEFAULT_ENDPOINT_ORIGIN = "https://www.google-analytics.com";
|
|
66
|
+
|
|
67
|
+
async function defaultTransport(request: { body: string; url: string }): Promise<void> {
|
|
68
|
+
const response = await fetch(request.url, {
|
|
69
|
+
body: request.body,
|
|
70
|
+
headers: { "content-type": "application/json" },
|
|
71
|
+
method: "POST",
|
|
72
|
+
});
|
|
73
|
+
|
|
74
|
+
// MP returns 2xx with no useful body; a non-2xx is a config error worth surfacing.
|
|
75
|
+
if (!response.ok) {
|
|
76
|
+
throw new Error(`Measurement Protocol responded ${String(response.status)}`);
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* @since 1.0.0-canary.7
|
|
82
|
+
*/
|
|
83
|
+
export interface SendMeasurementProtocolEventsOptions {
|
|
84
|
+
/** GA4 **API Secret** — read server-side from config, never a client-exposed var. */
|
|
85
|
+
apiSecret: string;
|
|
86
|
+
/** The visitor's GA4 client id (see {@link extractGaClientId}). */
|
|
87
|
+
clientId: string;
|
|
88
|
+
consent?: MeasurementProtocolConsent | undefined;
|
|
89
|
+
endpointOrigin?: string | undefined;
|
|
90
|
+
events: ReadonlyArray<MeasurementProtocolEvent>;
|
|
91
|
+
measurementId: string;
|
|
92
|
+
transport?: MeasurementProtocolTransport | undefined;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* POSTs one or more events to the GA4 Measurement Protocol for a known `client_id` — the
|
|
97
|
+
* server-side counterpart to gtag.js. The caller owns credentials (never bake them) and the
|
|
98
|
+
* consent gate: send only for a server-owned event the visitor's consent permits.
|
|
99
|
+
*
|
|
100
|
+
* @see https://developers.google.com/analytics/devguides/collection/protocol/ga4/sending-events
|
|
101
|
+
*
|
|
102
|
+
* @since 1.0.0-canary.7
|
|
103
|
+
*/
|
|
104
|
+
export async function sendMeasurementProtocolEvents(options: SendMeasurementProtocolEventsOptions): Promise<void> {
|
|
105
|
+
const origin = options.endpointOrigin ?? DEFAULT_ENDPOINT_ORIGIN;
|
|
106
|
+
const url = `${origin}/mp/collect?measurement_id=${encodeURIComponent(options.measurementId)}&api_secret=${encodeURIComponent(options.apiSecret)}`;
|
|
107
|
+
const body = JSON.stringify({
|
|
108
|
+
client_id: options.clientId,
|
|
109
|
+
events: options.events,
|
|
110
|
+
...(options.consent ? { consent: options.consent } : {}),
|
|
111
|
+
});
|
|
112
|
+
|
|
113
|
+
await (options.transport ?? defaultTransport)({ body, url });
|
|
114
|
+
}
|
package/src/server/region.ts
CHANGED
|
@@ -1,6 +1,11 @@
|
|
|
1
1
|
import type { ConsentRegion } from "#/core/consent";
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
/**
|
|
4
|
+
* EU member states — GDPR opt-in via `resolveConsentMode("eu")`.
|
|
5
|
+
*
|
|
6
|
+
* @since 1.0.0-canary.6
|
|
7
|
+
*/
|
|
8
|
+
export const EU_COUNTRY_CODES: ReadonlySet<string> = new Set([
|
|
4
9
|
"AT",
|
|
5
10
|
"BE",
|
|
6
11
|
"BG",
|
|
@@ -31,9 +36,21 @@ const EU_COUNTRY_CODES = new Set([
|
|
|
31
36
|
]);
|
|
32
37
|
|
|
33
38
|
/**
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
39
|
+
* UK GDPR (post-Brexit) and EEA/EFTA states that apply GDPR-equivalent rules — mapped to
|
|
40
|
+
* the same `"eu"` consent region so they get opt-in, not the `"other"` opt-out default.
|
|
41
|
+
*
|
|
42
|
+
* Restricted edge runtimes that cannot import this package should duplicate these codes
|
|
43
|
+
* and keep a sync test against this export.
|
|
44
|
+
*
|
|
45
|
+
* @since 1.0.0-canary.6
|
|
46
|
+
*/
|
|
47
|
+
export const OPT_IN_EQUIVALENT_COUNTRY_CODES: ReadonlySet<string> = new Set(["GB", "IS", "LI", "NO"]);
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Unrecognized codes fall back to "other", which `resolveConsentMode` treats as
|
|
51
|
+
* opt-out — safe only because opt-in regions (EU/VN plus UK/EEA/EFTA above) are matched
|
|
52
|
+
* explicitly. A *missing* code also maps to "other" here, but `resolveInitialConsent`
|
|
53
|
+
* intercepts that case first and fails closed — unknown is not known-elsewhere.
|
|
37
54
|
*
|
|
38
55
|
* @since 0.5.0-canary.4
|
|
39
56
|
*/
|
|
@@ -44,7 +61,7 @@ export function resolveRegionFromCountryCode(countryCode: string | undefined): C
|
|
|
44
61
|
|
|
45
62
|
const normalized = countryCode.toUpperCase();
|
|
46
63
|
|
|
47
|
-
if (EU_COUNTRY_CODES.has(normalized)) {
|
|
64
|
+
if (EU_COUNTRY_CODES.has(normalized) || OPT_IN_EQUIVALENT_COUNTRY_CODES.has(normalized)) {
|
|
48
65
|
return "eu";
|
|
49
66
|
}
|
|
50
67
|
|
|
@@ -58,13 +75,3 @@ export function resolveRegionFromCountryCode(countryCode: string | undefined): C
|
|
|
58
75
|
|
|
59
76
|
return "other";
|
|
60
77
|
}
|
|
61
|
-
|
|
62
|
-
/**
|
|
63
|
-
* Reads the hosting platform's geo header (e.g. Vercel's `x-vercel-ip-country`) — pass
|
|
64
|
-
* the incoming request's `Headers` from server-function/middleware context.
|
|
65
|
-
*
|
|
66
|
-
* @since 0.5.0-canary.4
|
|
67
|
-
*/
|
|
68
|
-
export function resolveRegion(headers: Headers, headerName = "x-vercel-ip-country"): ConsentRegion {
|
|
69
|
-
return resolveRegionFromCountryCode(headers.get(headerName) ?? undefined);
|
|
70
|
-
}
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* DSR delegation for GA4 (spec-data-subject-rights §3): the platform ships its own
|
|
3
|
+
* per-visitor deletion, so the system **delegates** rather than reimplementing a deletion
|
|
4
|
+
* store. Targets the current **Analytics Admin API** `properties.submitUserDeletion` — the
|
|
5
|
+
* legacy v3 `userDeletionRequests:upsert` was sunset with Universal Analytics, so the spec's
|
|
6
|
+
* DSR-V3 `{ id: { type: "CLIENT_ID", userId } }` shape is stale; the current request keys the
|
|
7
|
+
* subject with a flat `clientId` (a oneof with `userId`/`appInstanceId`/`userProvidedData`).
|
|
8
|
+
*
|
|
9
|
+
* @see https://developers.google.com/analytics/devguides/config/userdeletion/migration
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
const ADMIN_API_ORIGIN = "https://analyticsadmin.googleapis.com";
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* @since 1.0.0-canary.7
|
|
16
|
+
*/
|
|
17
|
+
export interface Ga4UserDeletionRequest {
|
|
18
|
+
body: { clientId: string };
|
|
19
|
+
url: string;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Builds the Admin API `submitUserDeletion` request that erases one GA4 subject by
|
|
24
|
+
* `clientId` (the `_ga`-cookie id — see `extractGaClientId`). Pure and network-free so the
|
|
25
|
+
* request shape can be snapshotted/verified; pair it with {@link submitGa4UserDeletion} or
|
|
26
|
+
* any authenticated transport.
|
|
27
|
+
*
|
|
28
|
+
* @param options - `propertyId` is the numeric GA4 property (no `properties/` prefix).
|
|
29
|
+
*
|
|
30
|
+
* @since 1.0.0-canary.7
|
|
31
|
+
*/
|
|
32
|
+
export function buildGa4UserDeletionRequest(options: { clientId: string; propertyId: string }): Ga4UserDeletionRequest {
|
|
33
|
+
return {
|
|
34
|
+
body: { clientId: options.clientId },
|
|
35
|
+
url: `${ADMIN_API_ORIGIN}/v1alpha/properties/${options.propertyId}:submitUserDeletion`,
|
|
36
|
+
};
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* The one network primitive the sender needs — injected so the package ships no HTTP client.
|
|
41
|
+
*
|
|
42
|
+
* @since 1.0.0-canary.7
|
|
43
|
+
*/
|
|
44
|
+
export type Ga4UserDeletionTransport = (request: {
|
|
45
|
+
body: string;
|
|
46
|
+
headers: Record<string, string>;
|
|
47
|
+
url: string;
|
|
48
|
+
}) => Promise<void>;
|
|
49
|
+
|
|
50
|
+
async function defaultTransport(request: {
|
|
51
|
+
body: string;
|
|
52
|
+
headers: Record<string, string>;
|
|
53
|
+
url: string;
|
|
54
|
+
}): Promise<void> {
|
|
55
|
+
const response = await fetch(request.url, { body: request.body, headers: request.headers, method: "POST" });
|
|
56
|
+
|
|
57
|
+
if (!response.ok) {
|
|
58
|
+
throw new Error(`GA4 user deletion responded ${String(response.status)}`);
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* @since 1.0.0-canary.7
|
|
64
|
+
*/
|
|
65
|
+
export interface SubmitGa4UserDeletionOptions {
|
|
66
|
+
/** A bearer token for the `https://www.googleapis.com/auth/analytics.edit` scope — the caller owns OAuth. */
|
|
67
|
+
accessToken: string;
|
|
68
|
+
clientId: string;
|
|
69
|
+
propertyId: string;
|
|
70
|
+
transport?: Ga4UserDeletionTransport | undefined;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Submits a GA4 user-deletion request for one `clientId`. Authorization is the caller's:
|
|
75
|
+
* pass a bearer token minted from a service account (never baked into the package). The
|
|
76
|
+
* deletion removes the subject from the Individual User report within ~72h and purges at the
|
|
77
|
+
* next run; it does **not** reach previously-aggregated reports or BigQuery exports
|
|
78
|
+
* (spec-data-subject-rights §3).
|
|
79
|
+
*
|
|
80
|
+
* @since 1.0.0-canary.7
|
|
81
|
+
*/
|
|
82
|
+
export async function submitGa4UserDeletion(options: SubmitGa4UserDeletionOptions): Promise<void> {
|
|
83
|
+
const request = buildGa4UserDeletionRequest({ clientId: options.clientId, propertyId: options.propertyId });
|
|
84
|
+
|
|
85
|
+
await (options.transport ?? defaultTransport)({
|
|
86
|
+
body: JSON.stringify(request.body),
|
|
87
|
+
headers: {
|
|
88
|
+
authorization: `Bearer ${options.accessToken}`,
|
|
89
|
+
"content-type": "application/json",
|
|
90
|
+
},
|
|
91
|
+
url: request.url,
|
|
92
|
+
});
|
|
93
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `@codefast/tracking` subpaths every client bundle must deny (picomatch patterns) —
|
|
3
|
+
* framework-neutral data each build tool maps to its own guard: TanStack Start's
|
|
4
|
+
* `importProtection.client.specifiers`, Next's `server-only`, Remix's `.server` convention.
|
|
5
|
+
* Ships and versions with the package instead of going stale in each consumer's config.
|
|
6
|
+
* Nothing in this package imports it — its consumers are app build configs (see apps/ui
|
|
7
|
+
* vite.config.ts).
|
|
8
|
+
*
|
|
9
|
+
* @example
|
|
10
|
+
* ```ts
|
|
11
|
+
* tanstackStart({
|
|
12
|
+
* importProtection: { client: { specifiers: [...SERVER_ONLY_SUBPATHS] } },
|
|
13
|
+
* });
|
|
14
|
+
* ```
|
|
15
|
+
*
|
|
16
|
+
* @since 1.0.0-canary.6
|
|
17
|
+
*/
|
|
18
|
+
export const SERVER_ONLY_SUBPATHS: ReadonlyArray<string> = [
|
|
19
|
+
"@codefast/tracking/server",
|
|
20
|
+
"@codefast/tracking/server/**",
|
|
21
|
+
"@codefast/tracking/adapters/**",
|
|
22
|
+
];
|
|
@@ -1,63 +0,0 @@
|
|
|
1
|
-
//#region src/client/consent-storage.ts
|
|
2
|
-
/**
|
|
3
|
-
* `localStorage`-backed consent storage. Corrupt state, a private-mode/quota error, or no
|
|
4
|
-
* `window` (SSR) degrades to an in-memory record — the visitor's decision still applies
|
|
5
|
-
* for the session instead of re-prompting in a loop. `subscribe` fires for same-tab
|
|
6
|
-
* writes and, via the `storage` event, for decisions made in other tabs.
|
|
7
|
-
*
|
|
8
|
-
* @remarks
|
|
9
|
-
* The record persists as plain `JSON.stringify(ConsentRecord)` — a stable contract, so
|
|
10
|
-
* pre-hydration inline scripts (e.g. a Consent Mode default bootstrap) can read the
|
|
11
|
-
* decision synchronously before any tag fires.
|
|
12
|
-
*
|
|
13
|
-
* @since 0.5.0-canary.4
|
|
14
|
-
*/
|
|
15
|
-
function createLocalStorageConsentStorage(storageKey) {
|
|
16
|
-
const listeners = /* @__PURE__ */ new Set();
|
|
17
|
-
let memoryRecord;
|
|
18
|
-
function notify() {
|
|
19
|
-
for (const listener of listeners) listener();
|
|
20
|
-
}
|
|
21
|
-
return {
|
|
22
|
-
clear() {
|
|
23
|
-
if (typeof globalThis.window === "undefined") return;
|
|
24
|
-
memoryRecord = void 0;
|
|
25
|
-
try {
|
|
26
|
-
globalThis.window.localStorage.removeItem(storageKey);
|
|
27
|
-
} catch {}
|
|
28
|
-
notify();
|
|
29
|
-
},
|
|
30
|
-
load() {
|
|
31
|
-
if (typeof globalThis.window === "undefined") return;
|
|
32
|
-
try {
|
|
33
|
-
const raw = globalThis.window.localStorage.getItem(storageKey);
|
|
34
|
-
return raw ? JSON.parse(raw) : memoryRecord;
|
|
35
|
-
} catch {
|
|
36
|
-
return memoryRecord;
|
|
37
|
-
}
|
|
38
|
-
},
|
|
39
|
-
save(record) {
|
|
40
|
-
if (typeof globalThis.window === "undefined") return;
|
|
41
|
-
try {
|
|
42
|
-
globalThis.window.localStorage.setItem(storageKey, JSON.stringify(record));
|
|
43
|
-
memoryRecord = void 0;
|
|
44
|
-
} catch {
|
|
45
|
-
memoryRecord = record;
|
|
46
|
-
}
|
|
47
|
-
notify();
|
|
48
|
-
},
|
|
49
|
-
subscribe(listener) {
|
|
50
|
-
listeners.add(listener);
|
|
51
|
-
function handleStorageEvent(event) {
|
|
52
|
-
if (event.key === null || event.key === storageKey) listener();
|
|
53
|
-
}
|
|
54
|
-
if (typeof globalThis.window !== "undefined") globalThis.window.addEventListener("storage", handleStorageEvent);
|
|
55
|
-
return () => {
|
|
56
|
-
listeners.delete(listener);
|
|
57
|
-
if (typeof globalThis.window !== "undefined") globalThis.window.removeEventListener("storage", handleStorageEvent);
|
|
58
|
-
};
|
|
59
|
-
}
|
|
60
|
-
};
|
|
61
|
-
}
|
|
62
|
-
//#endregion
|
|
63
|
-
export { createLocalStorageConsentStorage };
|
|
@@ -1,37 +0,0 @@
|
|
|
1
|
-
import { Destination } from "../core/destination.mjs";
|
|
2
|
-
import { EventQueueStorage } from "./queue.mjs";
|
|
3
|
-
import { EventCatalog, EventsOf } from "../core/event-catalog.mjs";
|
|
4
|
-
import { z } from "zod";
|
|
5
|
-
|
|
6
|
-
//#region src/client/create-client-tracker.d.ts
|
|
7
|
-
/**
|
|
8
|
-
* @since 0.5.0-canary.4
|
|
9
|
-
*/
|
|
10
|
-
interface ClientTrackerOptions<Catalog extends EventCatalog> {
|
|
11
|
-
anonymousId: string;
|
|
12
|
-
catalog: Catalog;
|
|
13
|
-
destinations: Array<Destination>;
|
|
14
|
-
maxQueueSize?: number;
|
|
15
|
-
maxRetries?: number;
|
|
16
|
-
storage: EventQueueStorage;
|
|
17
|
-
}
|
|
18
|
-
/**
|
|
19
|
-
* @since 0.5.0-canary.4
|
|
20
|
-
*/
|
|
21
|
-
interface ClientTracker<Catalog extends EventCatalog> {
|
|
22
|
-
/** Drops every pending event without sending it — call this when consent is revoked. */
|
|
23
|
-
clear: () => void;
|
|
24
|
-
flush: () => Promise<void>;
|
|
25
|
-
/** Synchronous, best-effort flush via `navigator.sendBeacon` — for page unload only. */
|
|
26
|
-
flushWithBeacon: (endpoint: string) => void;
|
|
27
|
-
group: (groupId: string, traits?: Record<string, unknown>) => void;
|
|
28
|
-
identify: (userId: string, traits?: Record<string, unknown>) => void;
|
|
29
|
-
page: (name?: string, props?: Record<string, unknown>) => void;
|
|
30
|
-
track: <Name extends keyof EventsOf<Catalog, "client">>(name: Name, props: z.infer<EventsOf<Catalog, "client">[Name]["schema"]>) => void;
|
|
31
|
-
}
|
|
32
|
-
/**
|
|
33
|
-
* @since 0.5.0-canary.4
|
|
34
|
-
*/
|
|
35
|
-
declare function createClientTracker<Catalog extends EventCatalog>(options: ClientTrackerOptions<Catalog>): ClientTracker<Catalog>;
|
|
36
|
-
//#endregion
|
|
37
|
-
export { ClientTracker, ClientTrackerOptions, createClientTracker };
|
|
@@ -1,66 +0,0 @@
|
|
|
1
|
-
import { generateEventId } from "../core/event-id.mjs";
|
|
2
|
-
import { EventQueue } from "./queue.mjs";
|
|
3
|
-
//#region src/client/create-client-tracker.ts
|
|
4
|
-
/**
|
|
5
|
-
* @since 0.5.0-canary.4
|
|
6
|
-
*/
|
|
7
|
-
function createClientTracker(options) {
|
|
8
|
-
const immediateDestinations = options.destinations.filter((destination) => destination.delivery === "immediate");
|
|
9
|
-
const queue = new EventQueue({
|
|
10
|
-
destinations: options.destinations.filter((destination) => destination.delivery !== "immediate"),
|
|
11
|
-
maxQueueSize: options.maxQueueSize,
|
|
12
|
-
maxRetries: options.maxRetries,
|
|
13
|
-
storage: options.storage
|
|
14
|
-
});
|
|
15
|
-
let userId;
|
|
16
|
-
function enqueue(name, props) {
|
|
17
|
-
const envelope = {
|
|
18
|
-
anonymousId: options.anonymousId,
|
|
19
|
-
eventId: generateEventId(),
|
|
20
|
-
name,
|
|
21
|
-
owner: "client",
|
|
22
|
-
props,
|
|
23
|
-
timestamp: Date.now(),
|
|
24
|
-
...userId === void 0 ? {} : { userId }
|
|
25
|
-
};
|
|
26
|
-
for (const destination of immediateDestinations) try {
|
|
27
|
-
Promise.resolve(destination.send(envelope)).catch(() => {});
|
|
28
|
-
} catch {}
|
|
29
|
-
queue.enqueue(envelope);
|
|
30
|
-
}
|
|
31
|
-
return {
|
|
32
|
-
clear: () => {
|
|
33
|
-
queue.clear();
|
|
34
|
-
},
|
|
35
|
-
flush: () => queue.flush(),
|
|
36
|
-
flushWithBeacon(endpoint) {
|
|
37
|
-
const events = queue.drain();
|
|
38
|
-
if (events.length === 0) return;
|
|
39
|
-
if (!navigator.sendBeacon(endpoint, JSON.stringify(events))) for (const event of events) queue.enqueue(event);
|
|
40
|
-
},
|
|
41
|
-
group(groupId, traits = {}) {
|
|
42
|
-
enqueue("$group", {
|
|
43
|
-
groupId,
|
|
44
|
-
...traits
|
|
45
|
-
});
|
|
46
|
-
},
|
|
47
|
-
identify(id, traits = {}) {
|
|
48
|
-
userId = id;
|
|
49
|
-
enqueue("$identify", traits);
|
|
50
|
-
},
|
|
51
|
-
page(name, props = {}) {
|
|
52
|
-
enqueue("$page_viewed", name === void 0 ? props : {
|
|
53
|
-
name,
|
|
54
|
-
...props
|
|
55
|
-
});
|
|
56
|
-
},
|
|
57
|
-
track(name, props) {
|
|
58
|
-
const definition = options.catalog[name];
|
|
59
|
-
if (!definition || definition.owner !== "client") throw new Error(`Unknown client-owned event: ${String(name)}`);
|
|
60
|
-
definition.schema.parse(props);
|
|
61
|
-
enqueue(name, props);
|
|
62
|
-
}
|
|
63
|
-
};
|
|
64
|
-
}
|
|
65
|
-
//#endregion
|
|
66
|
-
export { createClientTracker };
|
package/dist/client/gpc.d.mts
DELETED
|
@@ -1,10 +0,0 @@
|
|
|
1
|
-
//#region src/client/gpc.d.ts
|
|
2
|
-
/**
|
|
3
|
-
* Global Privacy Control isn't in lib.dom yet, hence the local interface extension.
|
|
4
|
-
* CCPA/CPRA requires honoring this as an opt-out signal even under the opt-out default.
|
|
5
|
-
*
|
|
6
|
-
* @since 0.5.0-canary.4
|
|
7
|
-
*/
|
|
8
|
-
declare function hasGlobalPrivacyControlSignal(): boolean;
|
|
9
|
-
//#endregion
|
|
10
|
-
export { hasGlobalPrivacyControlSignal };
|
package/dist/client/gpc.mjs
DELETED
|
@@ -1,12 +0,0 @@
|
|
|
1
|
-
//#region src/client/gpc.ts
|
|
2
|
-
/**
|
|
3
|
-
* Global Privacy Control isn't in lib.dom yet, hence the local interface extension.
|
|
4
|
-
* CCPA/CPRA requires honoring this as an opt-out signal even under the opt-out default.
|
|
5
|
-
*
|
|
6
|
-
* @since 0.5.0-canary.4
|
|
7
|
-
*/
|
|
8
|
-
function hasGlobalPrivacyControlSignal() {
|
|
9
|
-
return navigator.globalPrivacyControl === true;
|
|
10
|
-
}
|
|
11
|
-
//#endregion
|
|
12
|
-
export { hasGlobalPrivacyControlSignal };
|
package/dist/client/index.d.mts
DELETED
|
@@ -1,8 +0,0 @@
|
|
|
1
|
-
import { createLocalStorageConsentStorage } from "./consent-storage.mjs";
|
|
2
|
-
import { EventQueue, EventQueueOptions, EventQueueStorage } from "./queue.mjs";
|
|
3
|
-
import { ClientTracker, ClientTrackerOptions, createClientTracker } from "./create-client-tracker.mjs";
|
|
4
|
-
import { hasGlobalPrivacyControlSignal } from "./gpc.mjs";
|
|
5
|
-
import { ClientLifecycleOptions, attachClientLifecycle } from "./lifecycle.mjs";
|
|
6
|
-
import { createLocalStorageQueueStorage } from "./local-storage.mjs";
|
|
7
|
-
import { RouterLike, attachRouterPageTracking } from "./router.mjs";
|
|
8
|
-
export { type ClientLifecycleOptions, type ClientTracker, type ClientTrackerOptions, EventQueue, type EventQueueOptions, type EventQueueStorage, type RouterLike, attachClientLifecycle, attachRouterPageTracking, createClientTracker, createLocalStorageConsentStorage, createLocalStorageQueueStorage, hasGlobalPrivacyControlSignal };
|
package/dist/client/index.mjs
DELETED
|
@@ -1,8 +0,0 @@
|
|
|
1
|
-
import { createLocalStorageConsentStorage } from "./consent-storage.mjs";
|
|
2
|
-
import { EventQueue } from "./queue.mjs";
|
|
3
|
-
import { createClientTracker } from "./create-client-tracker.mjs";
|
|
4
|
-
import { hasGlobalPrivacyControlSignal } from "./gpc.mjs";
|
|
5
|
-
import { attachClientLifecycle } from "./lifecycle.mjs";
|
|
6
|
-
import { createLocalStorageQueueStorage } from "./local-storage.mjs";
|
|
7
|
-
import { attachRouterPageTracking } from "./router.mjs";
|
|
8
|
-
export { EventQueue, attachClientLifecycle, attachRouterPageTracking, createClientTracker, createLocalStorageConsentStorage, createLocalStorageQueueStorage, hasGlobalPrivacyControlSignal };
|
|
@@ -1,23 +0,0 @@
|
|
|
1
|
-
import { EventCatalog } from "../core/event-catalog.mjs";
|
|
2
|
-
import { ClientTracker } from "./create-client-tracker.mjs";
|
|
3
|
-
|
|
4
|
-
//#region src/client/lifecycle.d.ts
|
|
5
|
-
/**
|
|
6
|
-
* @since 0.5.0-canary.4
|
|
7
|
-
*/
|
|
8
|
-
interface ClientLifecycleOptions {
|
|
9
|
-
/** `sendBeacon` target used on unload — omit to skip the unload flush entirely. */
|
|
10
|
-
beaconEndpoint?: string;
|
|
11
|
-
flushIntervalMs?: number;
|
|
12
|
-
}
|
|
13
|
-
/**
|
|
14
|
-
* Wires the two flush triggers the queue itself can't own (batch-size is handled inside
|
|
15
|
-
* `EventQueue`): a periodic interval flush, and a best-effort `sendBeacon` flush on
|
|
16
|
-
* unload — `fetch` isn't reliable once the page starts unloading, `sendBeacon` is.
|
|
17
|
-
* Returns a cleanup function to remove all listeners/timers.
|
|
18
|
-
*
|
|
19
|
-
* @since 0.5.0-canary.4
|
|
20
|
-
*/
|
|
21
|
-
declare function attachClientLifecycle<Catalog extends EventCatalog>(tracker: Pick<ClientTracker<Catalog>, "flush" | "flushWithBeacon">, options?: ClientLifecycleOptions): () => void;
|
|
22
|
-
//#endregion
|
|
23
|
-
export { ClientLifecycleOptions, attachClientLifecycle };
|
|
@@ -1,30 +0,0 @@
|
|
|
1
|
-
//#region src/client/lifecycle.ts
|
|
2
|
-
/**
|
|
3
|
-
* Wires the two flush triggers the queue itself can't own (batch-size is handled inside
|
|
4
|
-
* `EventQueue`): a periodic interval flush, and a best-effort `sendBeacon` flush on
|
|
5
|
-
* unload — `fetch` isn't reliable once the page starts unloading, `sendBeacon` is.
|
|
6
|
-
* Returns a cleanup function to remove all listeners/timers.
|
|
7
|
-
*
|
|
8
|
-
* @since 0.5.0-canary.4
|
|
9
|
-
*/
|
|
10
|
-
function attachClientLifecycle(tracker, options = {}) {
|
|
11
|
-
const flushIntervalMs = options.flushIntervalMs ?? 1e4;
|
|
12
|
-
const intervalId = setInterval(() => {
|
|
13
|
-
tracker.flush();
|
|
14
|
-
}, flushIntervalMs);
|
|
15
|
-
function flushOnUnload() {
|
|
16
|
-
if (options.beaconEndpoint !== void 0) tracker.flushWithBeacon(options.beaconEndpoint);
|
|
17
|
-
}
|
|
18
|
-
function handleVisibilityChange() {
|
|
19
|
-
if (document.visibilityState === "hidden") flushOnUnload();
|
|
20
|
-
}
|
|
21
|
-
document.addEventListener("visibilitychange", handleVisibilityChange);
|
|
22
|
-
window.addEventListener("pagehide", flushOnUnload);
|
|
23
|
-
return () => {
|
|
24
|
-
clearInterval(intervalId);
|
|
25
|
-
document.removeEventListener("visibilitychange", handleVisibilityChange);
|
|
26
|
-
window.removeEventListener("pagehide", flushOnUnload);
|
|
27
|
-
};
|
|
28
|
-
}
|
|
29
|
-
//#endregion
|
|
30
|
-
export { attachClientLifecycle };
|
|
@@ -1,13 +0,0 @@
|
|
|
1
|
-
import { EventQueueStorage } from "./queue.mjs";
|
|
2
|
-
|
|
3
|
-
//#region src/client/local-storage.d.ts
|
|
4
|
-
/**
|
|
5
|
-
* `localStorage`-backed queue storage — corrupt/missing state, a private-mode/quota
|
|
6
|
-
* error, or no `window` (SSR) are all treated as empty rather than thrown, since a lost
|
|
7
|
-
* offline queue is preferable to a crashing app.
|
|
8
|
-
*
|
|
9
|
-
* @since 0.5.0-canary.4
|
|
10
|
-
*/
|
|
11
|
-
declare function createLocalStorageQueueStorage(storageKey: string): EventQueueStorage;
|
|
12
|
-
//#endregion
|
|
13
|
-
export { createLocalStorageQueueStorage };
|
|
@@ -1,31 +0,0 @@
|
|
|
1
|
-
//#region src/client/local-storage.ts
|
|
2
|
-
/**
|
|
3
|
-
* `localStorage`-backed queue storage — corrupt/missing state, a private-mode/quota
|
|
4
|
-
* error, or no `window` (SSR) are all treated as empty rather than thrown, since a lost
|
|
5
|
-
* offline queue is preferable to a crashing app.
|
|
6
|
-
*
|
|
7
|
-
* @since 0.5.0-canary.4
|
|
8
|
-
*/
|
|
9
|
-
function createLocalStorageQueueStorage(storageKey) {
|
|
10
|
-
return {
|
|
11
|
-
load() {
|
|
12
|
-
if (typeof globalThis.window === "undefined") return [];
|
|
13
|
-
try {
|
|
14
|
-
const raw = globalThis.window.localStorage.getItem(storageKey);
|
|
15
|
-
if (!raw) return [];
|
|
16
|
-
const parsed = JSON.parse(raw);
|
|
17
|
-
return Array.isArray(parsed) ? parsed : [];
|
|
18
|
-
} catch {
|
|
19
|
-
return [];
|
|
20
|
-
}
|
|
21
|
-
},
|
|
22
|
-
save(events) {
|
|
23
|
-
if (typeof globalThis.window === "undefined") return;
|
|
24
|
-
try {
|
|
25
|
-
globalThis.window.localStorage.setItem(storageKey, JSON.stringify(events));
|
|
26
|
-
} catch {}
|
|
27
|
-
}
|
|
28
|
-
};
|
|
29
|
-
}
|
|
30
|
-
//#endregion
|
|
31
|
-
export { createLocalStorageQueueStorage };
|