@aranova/tracking-next 0.14.2 → 0.16.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +67 -50
- package/dist/index.d.mts +219 -99
- package/dist/index.d.ts +219 -99
- package/dist/index.js +490 -155
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +484 -155
- package/dist/index.mjs.map +1 -1
- package/dist/middleware.js +88 -135
- package/dist/middleware.js.map +1 -1
- package/dist/middleware.mjs +88 -135
- package/dist/middleware.mjs.map +1 -1
- package/dist/{phone-utils-CcU5mwzc.d.mts → phone-utils-DlAQK-gU.d.mts} +127 -6
- package/dist/{phone-utils-CcU5mwzc.d.ts → phone-utils-DlAQK-gU.d.ts} +127 -6
- package/dist/phone.d.mts +1 -1
- package/dist/phone.d.ts +1 -1
- package/dist/phone.js +88 -135
- package/dist/phone.js.map +1 -1
- package/dist/phone.mjs +88 -135
- package/dist/phone.mjs.map +1 -1
- package/dist/sales.js +33 -29
- package/dist/sales.js.map +1 -1
- package/dist/sales.mjs +33 -29
- package/dist/sales.mjs.map +1 -1
- package/dist/server.d.mts +1 -1
- package/dist/server.d.ts +1 -1
- package/dist/server.js +88 -135
- package/dist/server.js.map +1 -1
- package/dist/server.mjs +88 -135
- package/dist/server.mjs.map +1 -1
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import {
|
|
2
|
-
export { D as DEFAULT_PHONE_COUNTRY, J as JsonValue,
|
|
1
|
+
import { T as TrackingParams, a as TrackingInstallSurface, b as TrackingEnvironment, c as TrackingClientContext, d as TrackingEventCreatePayload, e as TrackingSessionUpsertPayload, F as FormSubmitConfig, f as FormSubmitMetadata, C as ConsentState, g as ConsentChoiceState, h as ConsentSource, G as GtagEnvironmentMap, M as MetaPixelEnvironmentMap, P as PhoneConfig, i as ParsedPhone, j as PhoneDisplayFormat } from './phone-utils-DlAQK-gU.js';
|
|
2
|
+
export { k as ConsentChoice, D as DEFAULT_DECLINE_TTL_DAYS, l as DEFAULT_PHONE_COUNTRY, J as JsonValue, S as SetConsentOptions, m as TrackedField, n as TrackingInitConfig, o as formSubmitConfigSchema, p as formSubmitMetadataSchema, q as formatPhone, r as formatPhoneAsTyped, s as getConsentChoice, t as getConsentState, u as jsonValueSchema, v as onConsentChange, w as optIn, x as optOut, y as parsePhone, z as phoneField, A as resetConsent, B as setConsentState, E as toE164 } from './phone-utils-DlAQK-gU.js';
|
|
3
3
|
import { C as ConversionConfig } from './sales-Bq7H-Vym.js';
|
|
4
4
|
export { A as AranovaApiError, B as BusinessConfig, a as BusinessConfigFeatures, b as BusinessConfigService, c as CompareTo, d as ConversionConfigStore, e as CurrencyRevenue, f as CustomerCurrencyDelta, g as CustomerCurrencyTotal, h as CustomerGetOptions, i as CustomerGetResult, j as CustomerKpis, k as CustomerKpisDeltas, l as CustomerKpisPrevious, m as CustomerListPage, n as CustomerListQuery, o as CustomerProfile, p as CustomerSegment, q as CustomerSegmentCount, r as CustomerSortField, s as CustomerSummary, t as CustomerSummaryQuery, D as DistinctCustomersByCurrency, G as Granularity, N as NAMED_RANGES, u as NamedRange, P as PublicServiceItem, S as SUPPORTED_CURRENCIES, v as Sale, w as SaleCursorPage, x as SaleFilters, y as SaleInput, z as SaleItem, E as SaleItemInput, F as SaleKeysetSortField, H as SaleListPage, I as SaleListQuery, J as SaleListQueryV2, K as SaleService, L as SaleServiceInput, M as SaleSortField, O as SaleSortOrder, Q as SaleSummary, R as SaleSummaryPrevious, T as SaleSummaryQuery, U as SaleSummaryQueryV2, V as SaleSummaryV2, W as SaleUpdateInput, X as SalesBusinessClient, Y as SalesCategoryBreakdown, Z as SalesClient, _ as SalesClientConfig, $ as SalesCustomersClient, a0 as SalesServiceBreakdown, a1 as SalesTransportConfig, a2 as SalesTrendPoint, a3 as SummaryCurrencyDelta, a4 as SummaryDeltas, a5 as SummaryWindow, a6 as SupportedCurrency, a7 as TRACKING_RANGES, a8 as TrackingOverviewRange, a9 as createSalesClient, aa as fetchServices, ab as formatDateInTz, ac as formatMoney, ad as fromMinor, ae as resolveConversionConfig, af as saleCreateSchema, ag as saleItemSchema, ah as saleServiceSchema, ai as saleUpdateSchema, aj as salesRequest, ak as toMinor } from './sales-Bq7H-Vym.js';
|
|
5
5
|
import { z } from 'zod';
|
|
@@ -11,37 +11,17 @@ import { CountryCode } from 'libphonenumber-js';
|
|
|
11
11
|
export { CountryCode } from 'libphonenumber-js';
|
|
12
12
|
|
|
13
13
|
/**
|
|
14
|
-
*
|
|
15
|
-
*/
|
|
16
|
-
type GtagConsentValue = "granted" | "denied";
|
|
17
|
-
/**
|
|
18
|
-
* Read the persisted visitor consent state from localStorage.
|
|
19
|
-
*
|
|
20
|
-
* Returns `pending` when called during SSR or before the visitor has made a
|
|
21
|
-
* choice.
|
|
22
|
-
*/
|
|
23
|
-
declare function getConsentState(): ConsentState;
|
|
24
|
-
/**
|
|
25
|
-
* Persist a visitor consent choice and update Google Consent Mode when gtag is
|
|
26
|
-
* loaded.
|
|
14
|
+
* Attribution query/cookie keys captured by the SDK.
|
|
27
15
|
*/
|
|
28
|
-
declare
|
|
16
|
+
declare const TRACKING_PARAM_KEYS: readonly ["gclid", "fbclid", "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"];
|
|
17
|
+
type TrackingParamKey = (typeof TRACKING_PARAM_KEYS)[number];
|
|
29
18
|
/**
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
* Power a "Cookie preferences" link in a footer so visitors can change their
|
|
33
|
-
* mind without losing access to your site:
|
|
34
|
-
*
|
|
35
|
-
* ```tsx
|
|
36
|
-
* const { reset } = useConsent();
|
|
37
|
-
* <button onClick={reset}>Cookie preferences</button>
|
|
38
|
-
* ```
|
|
19
|
+
* Capture tracking params from a URL, persist them to first-party cookies, and
|
|
20
|
+
* return the current cookie-backed attribution state.
|
|
39
21
|
*
|
|
40
|
-
*
|
|
41
|
-
* visitor hasn't chosen anything yet. The next `setConsentState()` call will
|
|
42
|
-
* sync gtag once they re-choose.
|
|
22
|
+
* Defaults to `window.location.href` in the browser.
|
|
43
23
|
*/
|
|
44
|
-
declare function
|
|
24
|
+
declare function captureTrackingParamsFromLocation(url?: string, maxAgeSeconds?: number): TrackingParams;
|
|
45
25
|
|
|
46
26
|
interface TrackingContextInput {
|
|
47
27
|
packageName?: string | null;
|
|
@@ -63,6 +43,12 @@ interface TrackingSessionInput {
|
|
|
63
43
|
firstPage?: string | null;
|
|
64
44
|
sessionId: string;
|
|
65
45
|
visitorId?: string | null;
|
|
46
|
+
/**
|
|
47
|
+
* Landing attribution override (ADR-016). When omitted, the session's
|
|
48
|
+
* persisted landing record is used (captured from the current URL if the
|
|
49
|
+
* session has none yet).
|
|
50
|
+
*/
|
|
51
|
+
landingParams?: Partial<Record<TrackingParamKey, string>>;
|
|
66
52
|
}
|
|
67
53
|
/**
|
|
68
54
|
* Build runtime context attached to tracking sessions and events.
|
|
@@ -94,6 +80,8 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
|
|
|
94
80
|
}>;
|
|
95
81
|
section: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
96
82
|
destination_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
83
|
+
href: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
84
|
+
element: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
97
85
|
}, "strict", z.ZodTypeAny, {
|
|
98
86
|
page: {
|
|
99
87
|
path: string;
|
|
@@ -101,6 +89,8 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
|
|
|
101
89
|
cta_name: string;
|
|
102
90
|
section?: string | null | undefined;
|
|
103
91
|
destination_url?: string | null | undefined;
|
|
92
|
+
href?: string | null | undefined;
|
|
93
|
+
element?: string | null | undefined;
|
|
104
94
|
}, {
|
|
105
95
|
page: {
|
|
106
96
|
path: string;
|
|
@@ -108,14 +98,34 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
|
|
|
108
98
|
cta_name: string;
|
|
109
99
|
section?: string | null | undefined;
|
|
110
100
|
destination_url?: string | null | undefined;
|
|
101
|
+
href?: string | null | undefined;
|
|
102
|
+
element?: string | null | undefined;
|
|
111
103
|
}>;
|
|
112
104
|
type CtaClickMetadata = z.infer<typeof ctaClickMetadataSchema>;
|
|
113
105
|
/**
|
|
114
106
|
* Registration config for `cta_click`.
|
|
115
107
|
*
|
|
116
|
-
*
|
|
108
|
+
* The event stays manually fireable; `autoCapture` additionally attaches a
|
|
109
|
+
* delegated click listener that fires it for any element matching `selector`
|
|
110
|
+
* (default `[data-aranova-cta]`) — tag your CTAs, get analytics for free.
|
|
117
111
|
*/
|
|
118
|
-
declare const ctaClickConfigSchema: z.ZodObject<{
|
|
112
|
+
declare const ctaClickConfigSchema: z.ZodObject<{
|
|
113
|
+
autoCapture: z.ZodOptional<z.ZodObject<{
|
|
114
|
+
selector: z.ZodOptional<z.ZodString>;
|
|
115
|
+
}, "strict", z.ZodTypeAny, {
|
|
116
|
+
selector?: string | undefined;
|
|
117
|
+
}, {
|
|
118
|
+
selector?: string | undefined;
|
|
119
|
+
}>>;
|
|
120
|
+
}, "strict", z.ZodTypeAny, {
|
|
121
|
+
autoCapture?: {
|
|
122
|
+
selector?: string | undefined;
|
|
123
|
+
} | undefined;
|
|
124
|
+
}, {
|
|
125
|
+
autoCapture?: {
|
|
126
|
+
selector?: string | undefined;
|
|
127
|
+
} | undefined;
|
|
128
|
+
}>;
|
|
119
129
|
type CtaClickConfig = z.infer<typeof ctaClickConfigSchema>;
|
|
120
130
|
|
|
121
131
|
/**
|
|
@@ -279,6 +289,49 @@ declare const multiPageSessionConfigSchema: z.ZodObject<{
|
|
|
279
289
|
}>;
|
|
280
290
|
type MultiPageSessionConfig = z.infer<typeof multiPageSessionConfigSchema>;
|
|
281
291
|
|
|
292
|
+
/**
|
|
293
|
+
* Metadata for the automatic `page_exit` event.
|
|
294
|
+
*
|
|
295
|
+
* Fired when the user leaves a page (SPA navigation away, tab hidden, or
|
|
296
|
+
* pagehide). `dwell_ms` is the ACTIVE (visible) time spent on the page segment
|
|
297
|
+
* being closed — hidden time never counts, matching `time_on_site` semantics.
|
|
298
|
+
* A page revisited after being hidden emits another `page_exit` for the next
|
|
299
|
+
* visible segment, so summing `dwell_ms` per page/session yields total active
|
|
300
|
+
* dwell without double counting.
|
|
301
|
+
*/
|
|
302
|
+
declare const pageExitMetadataSchema: z.ZodObject<{
|
|
303
|
+
dwell_ms: z.ZodNumber;
|
|
304
|
+
max_scroll_percent: z.ZodNullable<z.ZodNumber>;
|
|
305
|
+
page: z.ZodObject<{
|
|
306
|
+
path: z.ZodString;
|
|
307
|
+
}, "strict", z.ZodTypeAny, {
|
|
308
|
+
path: string;
|
|
309
|
+
}, {
|
|
310
|
+
path: string;
|
|
311
|
+
}>;
|
|
312
|
+
}, "strict", z.ZodTypeAny, {
|
|
313
|
+
page: {
|
|
314
|
+
path: string;
|
|
315
|
+
};
|
|
316
|
+
dwell_ms: number;
|
|
317
|
+
max_scroll_percent: number | null;
|
|
318
|
+
}, {
|
|
319
|
+
page: {
|
|
320
|
+
path: string;
|
|
321
|
+
};
|
|
322
|
+
dwell_ms: number;
|
|
323
|
+
max_scroll_percent: number | null;
|
|
324
|
+
}>;
|
|
325
|
+
type PageExitMetadata = z.infer<typeof pageExitMetadataSchema>;
|
|
326
|
+
/**
|
|
327
|
+
* Registration config for automatic `page_exit`.
|
|
328
|
+
*
|
|
329
|
+
* SDK-internal: attached unconditionally (like `sdk_heartbeat`), so there are
|
|
330
|
+
* no registration options.
|
|
331
|
+
*/
|
|
332
|
+
declare const pageExitConfigSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
|
|
333
|
+
type PageExitConfig = z.infer<typeof pageExitConfigSchema>;
|
|
334
|
+
|
|
282
335
|
/**
|
|
283
336
|
* Metadata for the automatic `page_view` event.
|
|
284
337
|
*
|
|
@@ -810,6 +863,33 @@ declare const EVENT_REGISTRY: {
|
|
|
810
863
|
}>;
|
|
811
864
|
readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
|
|
812
865
|
};
|
|
866
|
+
readonly page_exit: {
|
|
867
|
+
readonly kind: "automatic";
|
|
868
|
+
readonly metadataSchema: z.ZodObject<{
|
|
869
|
+
dwell_ms: z.ZodNumber;
|
|
870
|
+
max_scroll_percent: z.ZodNullable<z.ZodNumber>;
|
|
871
|
+
page: z.ZodObject<{
|
|
872
|
+
path: z.ZodString;
|
|
873
|
+
}, "strict", z.ZodTypeAny, {
|
|
874
|
+
path: string;
|
|
875
|
+
}, {
|
|
876
|
+
path: string;
|
|
877
|
+
}>;
|
|
878
|
+
}, "strict", z.ZodTypeAny, {
|
|
879
|
+
page: {
|
|
880
|
+
path: string;
|
|
881
|
+
};
|
|
882
|
+
dwell_ms: number;
|
|
883
|
+
max_scroll_percent: number | null;
|
|
884
|
+
}, {
|
|
885
|
+
page: {
|
|
886
|
+
path: string;
|
|
887
|
+
};
|
|
888
|
+
dwell_ms: number;
|
|
889
|
+
max_scroll_percent: number | null;
|
|
890
|
+
}>;
|
|
891
|
+
readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
|
|
892
|
+
};
|
|
813
893
|
readonly form_submit: {
|
|
814
894
|
readonly kind: "manual";
|
|
815
895
|
readonly metadataSchema: z.ZodObject<{
|
|
@@ -929,6 +1009,8 @@ declare const EVENT_REGISTRY: {
|
|
|
929
1009
|
}>;
|
|
930
1010
|
section: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
931
1011
|
destination_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
1012
|
+
href: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
1013
|
+
element: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
932
1014
|
}, "strict", z.ZodTypeAny, {
|
|
933
1015
|
page: {
|
|
934
1016
|
path: string;
|
|
@@ -936,6 +1018,8 @@ declare const EVENT_REGISTRY: {
|
|
|
936
1018
|
cta_name: string;
|
|
937
1019
|
section?: string | null | undefined;
|
|
938
1020
|
destination_url?: string | null | undefined;
|
|
1021
|
+
href?: string | null | undefined;
|
|
1022
|
+
element?: string | null | undefined;
|
|
939
1023
|
}, {
|
|
940
1024
|
page: {
|
|
941
1025
|
path: string;
|
|
@@ -943,8 +1027,26 @@ declare const EVENT_REGISTRY: {
|
|
|
943
1027
|
cta_name: string;
|
|
944
1028
|
section?: string | null | undefined;
|
|
945
1029
|
destination_url?: string | null | undefined;
|
|
1030
|
+
href?: string | null | undefined;
|
|
1031
|
+
element?: string | null | undefined;
|
|
1032
|
+
}>;
|
|
1033
|
+
readonly configSchema: z.ZodObject<{
|
|
1034
|
+
autoCapture: z.ZodOptional<z.ZodObject<{
|
|
1035
|
+
selector: z.ZodOptional<z.ZodString>;
|
|
1036
|
+
}, "strict", z.ZodTypeAny, {
|
|
1037
|
+
selector?: string | undefined;
|
|
1038
|
+
}, {
|
|
1039
|
+
selector?: string | undefined;
|
|
1040
|
+
}>>;
|
|
1041
|
+
}, "strict", z.ZodTypeAny, {
|
|
1042
|
+
autoCapture?: {
|
|
1043
|
+
selector?: string | undefined;
|
|
1044
|
+
} | undefined;
|
|
1045
|
+
}, {
|
|
1046
|
+
autoCapture?: {
|
|
1047
|
+
selector?: string | undefined;
|
|
1048
|
+
} | undefined;
|
|
946
1049
|
}>;
|
|
947
|
-
readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
|
|
948
1050
|
};
|
|
949
1051
|
};
|
|
950
1052
|
/**
|
|
@@ -973,6 +1075,7 @@ type MetadataByName = {
|
|
|
973
1075
|
multi_page_session: MultiPageSessionMetadata;
|
|
974
1076
|
form_start: FormStartMetadata;
|
|
975
1077
|
sdk_heartbeat: SdkHeartbeatMetadata;
|
|
1078
|
+
page_exit: PageExitMetadata;
|
|
976
1079
|
form_submit: FormSubmitMetadata;
|
|
977
1080
|
phone_click: PhoneClickMetadata;
|
|
978
1081
|
cta_click: CtaClickMetadata;
|
|
@@ -985,6 +1088,7 @@ type ConfigByName = {
|
|
|
985
1088
|
multi_page_session: MultiPageSessionConfig;
|
|
986
1089
|
form_start: FormStartConfig;
|
|
987
1090
|
sdk_heartbeat: SdkHeartbeatConfig;
|
|
1091
|
+
page_exit: PageExitConfig;
|
|
988
1092
|
form_submit: FormSubmitConfig;
|
|
989
1093
|
phone_click: PhoneClickConfig;
|
|
990
1094
|
cta_click: CtaClickConfig;
|
|
@@ -1099,8 +1203,14 @@ interface TrackEventInput {
|
|
|
1099
1203
|
interface TrackingClient {
|
|
1100
1204
|
/** Enqueue an event for batched delivery. */
|
|
1101
1205
|
trackEvent: (input: TrackEventInput) => void;
|
|
1102
|
-
/** Flush queued events immediately. */
|
|
1206
|
+
/** Flush queued events immediately (fetch, non-keepalive). */
|
|
1103
1207
|
flush: () => Promise<void>;
|
|
1208
|
+
/**
|
|
1209
|
+
* Flush queued events through the keepalive transport so the request
|
|
1210
|
+
* survives document unload. Use from `pagehide`/`visibilitychange:hidden`
|
|
1211
|
+
* handlers — a plain `flush()` there is aborted by the browser on unload.
|
|
1212
|
+
*/
|
|
1213
|
+
flushBeacon: () => void;
|
|
1104
1214
|
/** Return the current rolling session id. */
|
|
1105
1215
|
getSessionId: () => string;
|
|
1106
1216
|
/** Return the persistent visitor id. */
|
|
@@ -1109,18 +1219,6 @@ interface TrackingClient {
|
|
|
1109
1219
|
destroy: () => void;
|
|
1110
1220
|
}
|
|
1111
1221
|
|
|
1112
|
-
/**
|
|
1113
|
-
* Attribution query/cookie keys captured by the SDK.
|
|
1114
|
-
*/
|
|
1115
|
-
declare const TRACKING_PARAM_KEYS: readonly ["gclid", "fbclid", "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"];
|
|
1116
|
-
/**
|
|
1117
|
-
* Capture tracking params from a URL, persist them to first-party cookies, and
|
|
1118
|
-
* return the current cookie-backed attribution state.
|
|
1119
|
-
*
|
|
1120
|
-
* Defaults to `window.location.href` in the browser.
|
|
1121
|
-
*/
|
|
1122
|
-
declare function captureTrackingParamsFromLocation(url?: string, maxAgeSeconds?: number): TrackingParams;
|
|
1123
|
-
|
|
1124
1222
|
interface TypedTrackEventOptions {
|
|
1125
1223
|
/**
|
|
1126
1224
|
* Override the page URL associated with this event.
|
|
@@ -1166,37 +1264,14 @@ interface TypedTrackingClient<TRegistry extends TriggerRegistryConfig> {
|
|
|
1166
1264
|
}
|
|
1167
1265
|
|
|
1168
1266
|
/**
|
|
1169
|
-
*
|
|
1170
|
-
*
|
|
1171
|
-
* Renders only while consent is `pending`; collapses to `null` once the
|
|
1172
|
-
* visitor has chosen.
|
|
1173
|
-
*
|
|
1174
|
-
* **Styling is intentionally self-contained** — inline styles, zero CSS
|
|
1175
|
-
* dependencies, no Tailwind required at the consumer. The Tailwind-based
|
|
1176
|
-
* banner shipped before 0.9.1 rendered as transparent in any consumer that
|
|
1177
|
-
* didn't configure their content array to scan
|
|
1178
|
-
* `node_modules/@aranova/tracking-next/dist/**`; this version sidesteps that
|
|
1179
|
-
* class of bug entirely.
|
|
1180
|
-
*
|
|
1181
|
-
* For a fully bespoke banner, skip this component and use {@link useConsent}
|
|
1182
|
-
* directly to drive your own UI.
|
|
1183
|
-
*
|
|
1184
|
-
* @example
|
|
1185
|
-
* // Drop-in default
|
|
1186
|
-
* <ConsentBanner />
|
|
1267
|
+
* Legacy opt-in-era consent banner.
|
|
1187
1268
|
*
|
|
1188
|
-
* @
|
|
1189
|
-
*
|
|
1190
|
-
*
|
|
1191
|
-
*
|
|
1192
|
-
*
|
|
1193
|
-
*
|
|
1194
|
-
* policyHref="/privacy"
|
|
1195
|
-
* policyLabel="Privacy policy"
|
|
1196
|
-
* theme="dark"
|
|
1197
|
-
* onAccept={() => track('consent_accepted')}
|
|
1198
|
-
* onDecline={() => track('consent_declined')}
|
|
1199
|
-
* />
|
|
1269
|
+
* @deprecated PERMANENTLY INERT since consent v2 (opt-out model): it renders
|
|
1270
|
+
* only while consent is `pending`, and the effective state is never `pending`
|
|
1271
|
+
* anymore, so this component always returns `null`. Tracking is on by default;
|
|
1272
|
+
* replace the banner with a footer "cookie preferences" control built on
|
|
1273
|
+
* {@link useCookiePreferences} (see the package README). Kept exported so
|
|
1274
|
+
* existing integrations keep compiling; scheduled for removal.
|
|
1200
1275
|
*/
|
|
1201
1276
|
interface ConsentBannerProps {
|
|
1202
1277
|
/** Body text. Defaults to the standard cookies-for-ad-performance message. */
|
|
@@ -1228,6 +1303,12 @@ interface ConsentBannerProps {
|
|
|
1228
1303
|
/** Inline style overrides applied to the outer wrapper after the defaults. */
|
|
1229
1304
|
style?: CSSProperties;
|
|
1230
1305
|
}
|
|
1306
|
+
/**
|
|
1307
|
+
* @deprecated Permanently inert since consent v2 — always renders `null`
|
|
1308
|
+
* because the effective consent state is never `pending`. Use a footer
|
|
1309
|
+
* control built on {@link useCookiePreferences} instead. See
|
|
1310
|
+
* {@link ConsentBannerProps} for details.
|
|
1311
|
+
*/
|
|
1231
1312
|
declare function ConsentBanner({ message, title, acceptLabel, declineLabel, policyHref, policyLabel, onAccept, onDecline, position, theme, className, style, }?: ConsentBannerProps): ReactNode;
|
|
1232
1313
|
|
|
1233
1314
|
/**
|
|
@@ -1242,38 +1323,69 @@ declare function useGclid(): string | null;
|
|
|
1242
1323
|
* Values are loaded after mount, so the initial render returns all `null`s.
|
|
1243
1324
|
*/
|
|
1244
1325
|
declare function useTrackingParams(): TrackingParams;
|
|
1326
|
+
/** Options for {@link useCookiePreferences}. */
|
|
1327
|
+
interface UseCookiePreferencesOptions {
|
|
1328
|
+
/** Days an explicit decline is honored. Defaults to 90. */
|
|
1329
|
+
declineTtlDays?: number;
|
|
1330
|
+
}
|
|
1245
1331
|
/**
|
|
1246
|
-
*
|
|
1247
|
-
*
|
|
1248
|
-
*
|
|
1249
|
-
* Prefer {@link useConsent} for new code — it returns the same state plus
|
|
1250
|
-
* the `accept` / `decline` / `reset` actions a custom consent UI needs.
|
|
1251
|
-
* `useConsentState` is kept as a convenience for callers that only need to
|
|
1252
|
-
* read.
|
|
1332
|
+
* The headless cookie-preferences surface returned by
|
|
1333
|
+
* {@link useCookiePreferences}.
|
|
1253
1334
|
*/
|
|
1254
|
-
|
|
1335
|
+
interface UseCookiePreferencesResult {
|
|
1336
|
+
/** Effective consent — `granted` unless an unexpired explicit decline exists. */
|
|
1337
|
+
state: ConsentChoiceState;
|
|
1338
|
+
/** `default` = no valid explicit choice stored; `explicit` = visitor chose. */
|
|
1339
|
+
source: ConsentSource;
|
|
1340
|
+
/** True when the visitor has made no (valid, unexpired) explicit choice. */
|
|
1341
|
+
isDefault: boolean;
|
|
1342
|
+
isGranted: boolean;
|
|
1343
|
+
isDenied: boolean;
|
|
1344
|
+
/** ISO timestamp of the explicit choice; null for the default state. */
|
|
1345
|
+
updatedAt: string | null;
|
|
1346
|
+
/** ISO expiry of an unexpired decline; null otherwise. */
|
|
1347
|
+
expiresAt: string | null;
|
|
1348
|
+
/** Explicitly opt out of ad tracking (honored for 90 days by default). */
|
|
1349
|
+
optOut: () => void;
|
|
1350
|
+
/** Explicitly opt in (never expires). */
|
|
1351
|
+
optIn: () => void;
|
|
1352
|
+
/** Clear the explicit choice — back to default-granted. */
|
|
1353
|
+
reset: () => void;
|
|
1354
|
+
}
|
|
1255
1355
|
/**
|
|
1256
|
-
*
|
|
1356
|
+
* Headless cookie-preferences hook for the opt-out consent model (consent v2).
|
|
1257
1357
|
*
|
|
1258
|
-
*
|
|
1259
|
-
*
|
|
1358
|
+
* Tracking is ON by default; this hook is how each client site wires its own
|
|
1359
|
+
* footer "Cookie preferences" control (button, dialog, toggle — the packages
|
|
1360
|
+
* ship no consent UI). State stays in sync with actions from other components
|
|
1361
|
+
* in the same tab (via `onConsentChange`) and other tabs (via `storage`
|
|
1362
|
+
* events).
|
|
1260
1363
|
*
|
|
1261
1364
|
* ```tsx
|
|
1262
|
-
*
|
|
1263
|
-
*
|
|
1264
|
-
*
|
|
1265
|
-
*
|
|
1365
|
+
* function CookiePreferences() {
|
|
1366
|
+
* const { isDenied, optOut, optIn } = useCookiePreferences();
|
|
1367
|
+
* return isDenied ? (
|
|
1368
|
+
* <button onClick={optIn}>Enable ad measurement</button>
|
|
1369
|
+
* ) : (
|
|
1370
|
+
* <button onClick={optOut}>Opt out of ad measurement</button>
|
|
1371
|
+
* );
|
|
1266
1372
|
* }
|
|
1267
|
-
* return (
|
|
1268
|
-
* <MyBannerStyling>
|
|
1269
|
-
* <button onClick={decline}>No thanks</button>
|
|
1270
|
-
* <button onClick={accept}>Sure</button>
|
|
1271
|
-
* </MyBannerStyling>
|
|
1272
|
-
* );
|
|
1273
1373
|
* ```
|
|
1374
|
+
*/
|
|
1375
|
+
declare function useCookiePreferences(options?: UseCookiePreferencesOptions): UseCookiePreferencesResult;
|
|
1376
|
+
/**
|
|
1377
|
+
* Read the current visitor consent state.
|
|
1274
1378
|
*
|
|
1275
|
-
*
|
|
1276
|
-
*
|
|
1379
|
+
* @deprecated Since consent v2 (opt-out model) the state is never `pending`.
|
|
1380
|
+
* Use {@link useCookiePreferences} — it exposes the effective state plus
|
|
1381
|
+
* `source` so you can tell a default grant from an explicit one.
|
|
1382
|
+
*/
|
|
1383
|
+
declare function useConsentState(): ConsentState;
|
|
1384
|
+
/**
|
|
1385
|
+
* Result shape of the deprecated {@link useConsent} hook.
|
|
1386
|
+
*
|
|
1387
|
+
* @deprecated Use {@link UseCookiePreferencesResult} via
|
|
1388
|
+
* {@link useCookiePreferences}. `isPending` is always `false` since consent v2.
|
|
1277
1389
|
*/
|
|
1278
1390
|
interface UseConsentResult {
|
|
1279
1391
|
state: ConsentState;
|
|
@@ -1284,6 +1396,14 @@ interface UseConsentResult {
|
|
|
1284
1396
|
decline: () => void;
|
|
1285
1397
|
reset: () => void;
|
|
1286
1398
|
}
|
|
1399
|
+
/**
|
|
1400
|
+
* Legacy opt-in-era consent hook.
|
|
1401
|
+
*
|
|
1402
|
+
* @deprecated Since consent v2 tracking defaults ON (opt-out model): the state
|
|
1403
|
+
* is never `pending`, so banner UIs gated on `isPending` never render. Use
|
|
1404
|
+
* {@link useCookiePreferences} for footer "cookie preferences" controls.
|
|
1405
|
+
* `accept` / `decline` still work and map to `optIn` / `optOut`.
|
|
1406
|
+
*/
|
|
1287
1407
|
declare function useConsent(): UseConsentResult;
|
|
1288
1408
|
|
|
1289
1409
|
/**
|
|
@@ -1470,4 +1590,4 @@ interface PhoneFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "t
|
|
|
1470
1590
|
*/
|
|
1471
1591
|
declare const PhoneField: react.ForwardRefExoticComponent<PhoneFieldProps & react.RefAttributes<HTMLInputElement>>;
|
|
1472
1592
|
|
|
1473
|
-
export { ALL_AUTOMATIC_EVENT_NAMES, ALL_MANUAL_EVENT_NAMES, AdPlatformTracking, type AdPlatformTrackingProps, type AutomaticEventName, ConsentBanner, type ConsentBannerProps, ConsentState, ConversionConfig, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, EVENT_REGISTRY, type EventConfig, type EventKind, type EventMetadata, type EventName, type FormStartConfig, type FormStartMetadata, FormSubmitConfig, FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, GtagEnvironmentMap, type ManualEventName, MetaPixelEnvironmentMap, type MultiPageSessionConfig, type MultiPageSessionMetadata, type PageViewConfig, type PageViewMetadata, ParsedPhone, type PhoneClickConfig, type PhoneClickMetadata, PhoneConfig, PhoneDisplayFormat, PhoneField, type PhoneFieldApi, type PhoneFieldProps, type PhoneInputProps, type RegisteredAutomaticEvents, type RegisteredManualEvents, SPECIFIC_PAGE_NAMES, type ScrollDepthConfig, type ScrollDepthMetadata, type SdkHeartbeatConfig, type SdkHeartbeatMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackableEvent, type TrackingClient, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, type TrackingProviderProps, TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, type UseConsentResult, type UsePhoneFieldOptions, captureTrackingParamsFromLocation, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, ctaClickConfigSchema, ctaClickMetadataSchema, formStartConfigSchema, formStartMetadataSchema,
|
|
1593
|
+
export { ALL_AUTOMATIC_EVENT_NAMES, ALL_MANUAL_EVENT_NAMES, AdPlatformTracking, type AdPlatformTrackingProps, type AutomaticEventName, ConsentBanner, type ConsentBannerProps, ConsentChoiceState, ConsentSource, ConsentState, ConversionConfig, type CreateTrackingOptions, type CreateTrackingResult, type CtaClickConfig, type CtaClickMetadata, EVENT_REGISTRY, type EventConfig, type EventKind, type EventMetadata, type EventName, type FormStartConfig, type FormStartMetadata, FormSubmitConfig, FormSubmitMetadata, GoogleAdsTracking, type GoogleAdsTrackingProps, GtagEnvironmentMap, type ManualEventName, MetaPixelEnvironmentMap, type MultiPageSessionConfig, type MultiPageSessionMetadata, type PageExitConfig, type PageExitMetadata, type PageViewConfig, type PageViewMetadata, ParsedPhone, type PhoneClickConfig, type PhoneClickMetadata, PhoneConfig, PhoneDisplayFormat, PhoneField, type PhoneFieldApi, type PhoneFieldProps, type PhoneInputProps, type RegisteredAutomaticEvents, type RegisteredManualEvents, SPECIFIC_PAGE_NAMES, type ScrollDepthConfig, type ScrollDepthMetadata, type SdkHeartbeatConfig, type SdkHeartbeatMetadata, type SpecificPageName, type SpecificPageVisitConfig, type SpecificPageVisitMetadata, TRACKING_PARAM_KEYS, type TimeOnSiteConfig, type TimeOnSiteMetadata, type TrackableEvent, type TrackingClient, TrackingClientContext, TrackingEventCreatePayload, TrackingInstallSurface, TrackingParams, type TrackingProviderProps, TrackingSessionUpsertPayload, type TriggerRegistryConfig, type TypedTrackEventOptions, type TypedTrackingClient, type UseConsentResult, type UseCookiePreferencesOptions, type UseCookiePreferencesResult, type UsePhoneFieldOptions, captureTrackingParamsFromLocation, createTracking, createTrackingClientContext, createTrackingEventCreatePayload, createTrackingSessionUpsertPayload, ctaClickConfigSchema, ctaClickMetadataSchema, formStartConfigSchema, formStartMetadataSchema, getEventDefinition, multiPageSessionConfigSchema, multiPageSessionMetadataSchema, pageExitConfigSchema, pageExitMetadataSchema, pageViewConfigSchema, pageViewMetadataSchema, phoneClickConfigSchema, phoneClickMetadataSchema, scrollDepthConfigSchema, scrollDepthMetadataSchema, sdkHeartbeatConfigSchema, sdkHeartbeatMetadataSchema, sdkHeartbeatTriggersSchema, specificPageNameSchema, specificPageVisitConfigSchema, specificPageVisitMetadataSchema, timeOnSiteConfigSchema, timeOnSiteMetadataSchema, useConsent, useConsentState, useCookiePreferences, useGclid, usePhoneConfig, usePhoneField, useTrackingParams };
|