@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 CHANGED
@@ -56,7 +56,7 @@ Wrap the root layout.
56
56
 
57
57
  ```tsx
58
58
  // app/layout.tsx
59
- import { ConsentBanner, GoogleAdsTracking } from "@aranova/tracking-next";
59
+ import { GoogleAdsTracking } from "@aranova/tracking-next";
60
60
  import { TrackingProvider } from "@/lib/tracking";
61
61
 
62
62
  export default function RootLayout({ children }: { children: React.ReactNode }) {
@@ -68,16 +68,17 @@ export default function RootLayout({ children }: { children: React.ReactNode })
68
68
  )}
69
69
  </head>
70
70
  <body>
71
- <TrackingProvider>
72
- {children}
73
- <ConsentBanner />
74
- </TrackingProvider>
71
+ <TrackingProvider>{children}</TrackingProvider>
75
72
  </body>
76
73
  </html>
77
74
  );
78
75
  }
79
76
  ```
80
77
 
78
+ Tracking is on by default (consent v2, opt-out model) — no banner. Add a footer
79
+ "cookie preferences" control built on `useCookiePreferences()` (see **Consent** below)
80
+ and disclose the tracking + opt-out in the site's privacy policy.
81
+
81
82
  ### Multiple gtag IDs
82
83
 
83
84
  Pass `gtagIds` (instead of `gtagId`) to install several Google Ads tags at once — e.g. a real
@@ -139,6 +140,49 @@ export function LeadForm() {
139
140
 
140
141
  `fields[].value` can be any JSON value: string, number, boolean, null, array, or object. Only send reviewed, allowlisted, non-sensitive values; do not send names, emails, phone numbers entered by the visitor, addresses, payment data, medical details, passwords, file contents, or free-text messages.
141
142
 
143
+ ### CTA clicks — manual or auto-capture
144
+
145
+ Fire `cta_click` yourself for full control over the name:
146
+
147
+ ```tsx
148
+ tracking.trackEvent("cta_click", {
149
+ cta_name: "Book appointment",
150
+ section: "hero",
151
+ destination_url: "/booking",
152
+ page: { path: window.location.pathname },
153
+ });
154
+ ```
155
+
156
+ Or opt into **auto-capture** and skip per-button code. Add `autoCapture` to the
157
+ `cta_click` registration — this attaches a single delegated click listener:
158
+
159
+ ```tsx
160
+ manual: {
161
+ cta_click: { autoCapture: {} }, // default selector: [data-aranova-cta]
162
+ // or target existing classes: { autoCapture: { selector: "a.cta, .btn-primary" } }
163
+ },
164
+ ```
165
+
166
+ Then tag your CTAs in markup — no imports, no handlers:
167
+
168
+ ```tsx
169
+ <a href="/booking" data-aranova-cta="Book now" data-aranova-section="hero">Book now</a>
170
+ <button data-aranova-cta="Get a quote">Get a quote</button>
171
+ ```
172
+
173
+ `cta_name` resolves to the `data-aranova-cta` value, else the element's trimmed text
174
+ (capped 120 chars), else `tag#id`. `section` comes from an optional `data-aranova-section`;
175
+ `href`/`destination_url` and a short `element` descriptor are captured automatically. Point
176
+ the selector at real CTAs (an explicit attribute is the safe default) — every matching click
177
+ is counted, including ones that later `stopPropagation`.
178
+
179
+ ### Automatic dwell + exit (`page_exit`)
180
+
181
+ `page_exit` is captured automatically — no registration. On route change, tab hide, and page
182
+ unload it records the **active** (visible) time spent on the page plus the max scroll depth
183
+ reached, delivered via a keepalive beacon so the final page still counts. This powers per-page
184
+ dwell and drop-off in the dashboard Analytics tab; there is nothing to configure.
185
+
142
186
  ## Phone Fields
143
187
 
144
188
  Bundled `libphonenumber-js`: parse/format utils + a React input. Display is configurable; the
@@ -266,65 +310,38 @@ sales.trackConversion("phone_click"); // fires a manual event-goal only (no sale
266
310
 
267
311
  Firing is consent-gated, de-duped by `transaction_id`, and no-ops server-side. The config bucket needs an R2 CORS policy — see [conversion-config-schema.md](https://github.com/AranovaIO/aranova_internal/blob/master/docs/tracking-package/conversion-config-schema.md).
268
312
 
269
- ## Consent UI
270
-
271
- The bundled `<ConsentBanner />` renders a non-blocking bottom-docked banner while consent is `pending`, persists the visitor's choice to `localStorage`, and propagates it to Google Consent Mode v2 when gtag is loaded. **Inline-styled** — no Tailwind or CSS imports required at the consumer.
272
-
273
- ```tsx
274
- import { ConsentBanner } from "@aranova/tracking-next";
313
+ ## Consent (v2 — opt-out model)
275
314
 
276
- // Drop-in (already wired in the root layout example above)
277
- <ConsentBanner />;
278
- ```
315
+ Tracking is **on by default**: the consent-default `<Script>` injected by `GoogleAdsTracking` / `AdPlatformTracking` resolves the visitor's effective consent synchronously from `localStorage` before gtag.js loads — granted unless an explicit, unexpired decline is stored. A decline is honored for **90 days**; a grant never expires. There is no `pending` state and the package ships **no consent UI** — each site provides its own footer "cookie preferences" control and discloses tracking in its privacy policy (that notice is what makes the opt-out model defensible).
279
316
 
280
- All props are optional:
281
-
282
- ```tsx
283
- <ConsentBanner
284
- title="Cookies"
285
- message="We use cookies to track ad performance."
286
- acceptLabel="Sure"
287
- declineLabel="No thanks"
288
- policyHref="/privacy"
289
- policyLabel="Privacy policy" // default: "Learn more"
290
- onAccept={() => track("consent_accepted")}
291
- onDecline={() => track("consent_declined")}
292
- position="bottom" // or "top"
293
- theme="light" // "light" | "dark" | "auto"
294
- className="my-extra-classes"
295
- style={{ background: "#fafafa" }} // wins over the theme defaults
296
- />
297
- ```
298
-
299
- ### Fully custom UI — `useConsent()`
300
-
301
- For a bespoke banner, skip the component and drive your own UI with the headless hook:
317
+ ### Footer control — `useCookiePreferences()`
302
318
 
303
319
  ```tsx
304
320
  "use client";
305
- import { useConsent } from "@aranova/tracking-next";
321
+ import { useCookiePreferences } from "@aranova/tracking-next";
306
322
 
307
- function CookieBar() {
308
- const { state, accept, decline, reset, isPending } = useConsent();
323
+ function CookiePreferences() {
324
+ const { isDenied, optOut, optIn } = useCookiePreferences();
309
325
 
310
- if (!isPending) {
311
- // Footer link: re-open the banner if they change their mind.
312
- return <button onClick={reset}>Cookie preferences</button>;
313
- }
314
- return (
315
- <MyBespokeBanner>
316
- <button onClick={decline}>No thanks</button>
317
- <button onClick={accept}>Sure</button>
318
- </MyBespokeBanner>
326
+ return isDenied ? (
327
+ <button onClick={optIn}>Enable ad measurement</button>
328
+ ) : (
329
+ <button onClick={optOut}>Opt out of ad measurement</button>
319
330
  );
320
331
  }
321
332
  ```
322
333
 
323
- The hook handles localStorage persistence, gtag sync, and cross-tab propagation — same machinery the default banner uses. `resetConsent()` is also exported as a standalone for non-component contexts (server actions that revalidate after an account change, etc.).
334
+ The hook returns the effective `state` (`"granted" | "denied"`), its `source` (`"default"` = no explicit choice, `"explicit"`), boolean helpers (`isDefault` / `isGranted` / `isDenied`), the choice's `updatedAt` / `expiresAt`, and the `optOut()` / `optIn()` / `reset()` actions. It stays in sync with other components in the same tab (via `onConsentChange`) and other tabs (via `storage` events). Plain-function equivalents (`optOut`, `optIn`, `resetConsent`, `getConsentChoice`, `onConsentChange`) are exported for non-component contexts.
335
+
336
+ ### Deprecated opt-in flow
337
+
338
+ `<ConsentBanner />`, `useConsent()`, and `useConsentState()` are `@deprecated` and scheduled for removal. The banner is **permanently inert** (it rendered only while consent was `pending`, which no longer occurs); `useConsent()` still works as a shim (`isPending` is always `false`; `accept`/`decline` map to `optIn`/`optOut`). The old `consent-restore` scripts are gone — the consent-default script already applies the effective state.
339
+
340
+ **Migrating from the banner flow:** delete `<ConsentBanner />`, add a footer control built on `useCookiePreferences`, and mention the tracking + opt-out in your privacy policy. Existing visitors' stored grants stay granted; stored declines stay denied for 90 days from their first visit after the upgrade.
324
341
 
325
342
  ## Exports
326
343
 
327
- - Root package: `createTracking`, `TrackingProvider`, `useTracking`, `GoogleAdsTracking`, `ConsentBanner` (+ `ConsentBannerProps`), consent hooks/helpers, attribution hooks, event types; `createSalesClient()` (isomorphic — public key writes; secret key reads/CRUD, `summary`, `customers.*`, `business.config`) + `toMinor`/`fromMinor`/`formatMoney`/`formatDateInTz`; phone (`parsePhone`/`toE164`/`formatPhone`/`phoneField`, `usePhoneField`, `PhoneField`)
344
+ - Root package: `createTracking`, `TrackingProvider`, `useTracking`, `GoogleAdsTracking`, consent v2 (`useCookiePreferences`, `optIn`, `optOut`, `resetConsent`, `getConsentChoice`, `onConsentChange`) + deprecated shims (`ConsentBanner`, `useConsent`, `useConsentState`), attribution hooks, event types; `createSalesClient()` (isomorphic — public key writes; secret key reads/CRUD, `summary`, `customers.*`, `business.config`) + `toMinor`/`fromMinor`/`formatMoney`/`formatDateInTz`; phone (`parsePhone`/`toE164`/`formatPhone`/`phoneField`, `usePhoneField`, `PhoneField`)
328
345
  - `@aranova/tracking-next/sales`: **React-free** server-safe SDK — `createSalesClient`, money/date helpers, and all sale/customer/config types. Use this in Server Components, route handlers, and Node servers; the root entry re-exports the same symbols for back-compat.
329
346
  - `@aranova/tracking-next/middleware`: `createTrackingMiddleware()`
330
347
  - `@aranova/tracking-next/server`: `getTrackingParamsServer()`
package/dist/index.d.mts CHANGED
@@ -1,5 +1,5 @@
1
- import { C as ConsentState, a as TrackingInstallSurface, b as TrackingEnvironment, c as TrackingClientContext, T as TrackingParams, d as TrackingEventCreatePayload, e as TrackingSessionUpsertPayload, F as FormSubmitConfig, f as FormSubmitMetadata, G as GtagEnvironmentMap, M as MetaPixelEnvironmentMap, P as PhoneConfig, g as ParsedPhone, h as PhoneDisplayFormat } from './phone-utils-CcU5mwzc.mjs';
2
- export { D as DEFAULT_PHONE_COUNTRY, J as JsonValue, i as TrackedField, j as TrackingInitConfig, k as formSubmitConfigSchema, l as formSubmitMetadataSchema, m as formatPhone, n as formatPhoneAsTyped, o as jsonValueSchema, p as parsePhone, q as phoneField, t as toE164 } from './phone-utils-CcU5mwzc.mjs';
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.mjs';
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.mjs';
3
3
  import { C as ConversionConfig } from './sales-Bq7H-Vym.mjs';
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.mjs';
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
- * Google Consent Mode value sent to `gtag('consent', 'update', ...)`.
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 function setConsentState(state: GtagConsentValue): void;
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
- * Clear the stored consent choice so the banner re-appears on next render.
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
- * Does NOT push an `update` to gtag — there's nothing to update because the
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 resetConsent(): void;
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
- * This event is manual-only and currently has no registration options.
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<{}, "strict", z.ZodTypeAny, {}, {}>;
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
- * Default non-blocking consent banner.
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
- * @example
1189
- * // Customized
1190
- * <ConsentBanner
1191
- * message="We use cookies to learn which ads drive bookings."
1192
- * acceptLabel="Sounds good"
1193
- * declineLabel="No thanks"
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
- * Read the current visitor consent state and update when another tab changes
1247
- * the stored value.
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
- declare function useConsentState(): ConsentState;
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
- * The headless consent surface — state + actions in one hook.
1356
+ * Headless cookie-preferences hook for the opt-out consent model (consent v2).
1257
1357
  *
1258
- * Build a fully-custom banner without losing the gtag-sync, localStorage
1259
- * persistence, or cross-tab propagation:
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
- * const { state, accept, decline, reset, isPending } = useConsent();
1263
- *
1264
- * if (!isPending) {
1265
- * return <button onClick={reset}>Cookie preferences</button>;
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
- * The boolean helpers (`isPending` / `isGranted` / `isDenied`) are equivalent
1276
- * to comparing `state` directly — they're there for readability at call sites.
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, getConsentState, getEventDefinition, multiPageSessionConfigSchema, multiPageSessionMetadataSchema, pageViewConfigSchema, pageViewMetadataSchema, phoneClickConfigSchema, phoneClickMetadataSchema, resetConsent, scrollDepthConfigSchema, scrollDepthMetadataSchema, sdkHeartbeatConfigSchema, sdkHeartbeatMetadataSchema, sdkHeartbeatTriggersSchema, setConsentState, specificPageNameSchema, specificPageVisitConfigSchema, specificPageVisitMetadataSchema, timeOnSiteConfigSchema, timeOnSiteMetadataSchema, useConsent, useConsentState, useGclid, usePhoneConfig, usePhoneField, useTrackingParams };
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 };