@aranova/tracking-next 0.17.2 → 0.18.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.
Files changed (28) hide show
  1. package/README.md +49 -23
  2. package/dist/index.d.mts +175 -12
  3. package/dist/index.d.ts +175 -12
  4. package/dist/index.js +610 -88
  5. package/dist/index.js.map +1 -1
  6. package/dist/index.mjs +584 -65
  7. package/dist/index.mjs.map +1 -1
  8. package/dist/middleware.js +90 -0
  9. package/dist/middleware.js.map +1 -1
  10. package/dist/middleware.mjs +90 -0
  11. package/dist/middleware.mjs.map +1 -1
  12. package/dist/phone.js +90 -0
  13. package/dist/phone.js.map +1 -1
  14. package/dist/phone.mjs +90 -0
  15. package/dist/phone.mjs.map +1 -1
  16. package/dist/{sales-C3jFBx08.d.mts → sales-QqKh6_iy.d.mts} +55 -2
  17. package/dist/{sales-C3jFBx08.d.ts → sales-QqKh6_iy.d.ts} +55 -2
  18. package/dist/sales.d.mts +1 -1
  19. package/dist/sales.d.ts +1 -1
  20. package/dist/sales.js +16 -0
  21. package/dist/sales.js.map +1 -1
  22. package/dist/sales.mjs +16 -0
  23. package/dist/sales.mjs.map +1 -1
  24. package/dist/server.js +90 -0
  25. package/dist/server.js.map +1 -1
  26. package/dist/server.mjs +90 -0
  27. package/dist/server.mjs.map +1 -1
  28. package/package.json +1 -1
package/README.md CHANGED
@@ -50,10 +50,12 @@ Create one shared tracking module and use its scoped exports throughout your app
50
50
  "use client";
51
51
 
52
52
  import { createTracking } from "@aranova/tracking-next";
53
+ import { ARANOVA_TRACKING_CONFIG } from "@/aranova-services";
53
54
 
54
55
  export const { TrackingProvider, useTracking } = createTracking({
55
56
  apiKey: process.env.NEXT_PUBLIC_ARANOVA_TRACKING_API_KEY!,
56
57
  endpoint: process.env.NEXT_PUBLIC_ARANOVA_TRACKING_ENDPOINT!,
58
+ trackingConfig: ARANOVA_TRACKING_CONFIG,
57
59
  triggers: {
58
60
  automatic: {
59
61
  page_view: {},
@@ -76,16 +78,15 @@ Wrap the root layout.
76
78
 
77
79
  ```tsx
78
80
  // app/layout.tsx
79
- import { GoogleAdsTracking } from "@aranova/tracking-next";
81
+ import { AdPlatformTracking } from "@aranova/tracking-next";
82
+ import { ARANOVA_TRACKING_CONFIG } from "@/aranova-services";
80
83
  import { TrackingProvider } from "@/lib/tracking";
81
84
 
82
85
  export default function RootLayout({ children }: { children: React.ReactNode }) {
83
86
  return (
84
87
  <html lang="en">
85
88
  <head>
86
- {process.env.NEXT_PUBLIC_GTAG_ID && (
87
- <GoogleAdsTracking gtagId={process.env.NEXT_PUBLIC_GTAG_ID} />
88
- )}
89
+ <AdPlatformTracking trackingConfig={ARANOVA_TRACKING_CONFIG} />
89
90
  </head>
90
91
  <body>
91
92
  <TrackingProvider>{children}</TrackingProvider>
@@ -108,11 +109,12 @@ Tracking is on by default (consent v2, opt-out model) — no banner. Add a foote
108
109
  "cookie preferences" control built on `useCookiePreferences()` (see **Consent** below)
109
110
  and disclose the tracking + opt-out in the site's privacy policy.
110
111
 
111
- ### Multiple gtag IDs
112
+ ### Legacy static gtag IDs
112
113
 
113
- Pass `gtagIds` (instead of `gtagId`) to install several Google Ads tags at once — e.g. a real
114
- account plus a test MCC. Each entry fires `gtag('config', …)` on every page; the labels surface in
115
- the dashboard's SDK table. Pass `environment` to the factory to tag events for dashboard filtering.
114
+ `gtagId`, `gtagIds`, `GoogleAdsTracking`, and generated `ARANOVA_GTAG_IDS` remain
115
+ compatibility APIs. Do not use them for new installs: static IDs cannot consume dashboard
116
+ tag changes or tombstones without a redeploy. If maintaining a legacy install, `gtagIds`
117
+ loads every entry and takes precedence over `gtagId`.
116
118
 
117
119
  ```tsx
118
120
  <GoogleAdsTracking gtagIds={{ production: "AW-111111111", test: "AW-222222222" }} />
@@ -338,30 +340,38 @@ and the CLI reference: [cli.md](https://github.com/AranovaIO/aranova_internal/bl
338
340
 
339
341
  ## On-site conversion firing
340
342
 
341
- Map conversion actions in the Aranova dashboard, run `tracking-cli gen` to bake `ARANOVA_CONFIG_URL`, then pass it to `createTracking`. The SDK fires `gtag('event','conversion', …)` on-page and reads the per-business config from the CDN with stale-while-revalidate — so **changing the mapping needs no client redeploy**.
343
+ Run `tracking-cli gen` once to emit `ARANOVA_TRACKING_CONFIG`, then use that
344
+ reference everywhere Google tracking is initialized. R2 is authoritative: the SDK confirms
345
+ the current object before emitting Google tag, page-view, or conversion commands. Dashboard
346
+ tag changes, goal remaps, and disabled-state tombstones propagate under
347
+ `public, max-age=60, must-revalidate` with no CLI run or site redeploy.
342
348
 
343
349
  ```ts
344
- import { createTracking } from "@aranova/tracking-next";
345
- import { ARANOVA_CONFIG_URL } from "./aranova-services"; // emitted by `tracking-cli gen`
350
+ import {
351
+ createSalesClient,
352
+ createTracking,
353
+ getTrackingConfigRuntime,
354
+ toMinor,
355
+ } from "@aranova/tracking-next";
356
+ import {
357
+ ARANOVA_TRACKING_CONFIG,
358
+ type AranovaConversion,
359
+ type AranovaService,
360
+ } from "./aranova-services";
361
+
362
+ const googleTracking = getTrackingConfigRuntime(ARANOVA_TRACKING_CONFIG);
346
363
 
347
364
  export const { TrackingProvider, useTracking } = createTracking({
348
365
  apiKey,
349
366
  endpoint,
350
367
  triggers,
351
- conversionConfig: { cdnUrl: ARANOVA_CONFIG_URL },
368
+ trackingConfig: ARANOVA_TRACKING_CONFIG,
352
369
  });
353
- ```
354
370
 
355
- - **Automatic event-goals** (scroll depth, time-on-site, page views, multi-page, form-start) fire **themselves** when their detector crosses the published threshold — zero extra code.
356
- - **Sales + manual events** fire through the sales client (use a **public** key in the browser; a secret-key server-side client no-ops firing since there's no `gtag`):
357
-
358
- ```ts
359
- import { createSalesClient, resolveConversionConfig, toMinor } from "@aranova/tracking-next";
360
-
361
- const sales = createSalesClient({
371
+ const sales = createSalesClient<AranovaService, AranovaConversion>({
362
372
  apiKey,
363
373
  endpoint,
364
- firing: resolveConversionConfig({ cdnUrl: ARANOVA_CONFIG_URL }),
374
+ firing: googleTracking,
365
375
  });
366
376
 
367
377
  await sales.recordSale({
@@ -372,7 +382,16 @@ await sales.recordSale({
372
382
  sales.trackConversion("phone_click"); // fires a manual event-goal only (no sale recorded)
373
383
  ```
374
384
 
375
- 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).
385
+ - **Automatic event-goals** fire when their registered detector crosses the published threshold.
386
+ - **Sales + manual goals** use the shared runtime above. Firing is consent-gated,
387
+ transaction-deduped, and browser-only.
388
+ - A remap of an existing key needs no codegen. A **new manual goal key** still requires
389
+ `tracking-cli gen` to refresh `AranovaConversion`, plus site handler wiring that calls
390
+ `trackConversion(key)`.
391
+
392
+ `ARANOVA_CONFIG_URL` and `conversionConfig: { cdnUrl }` remain legacy compatibility
393
+ APIs; do not use them for new installs. See
394
+ [conversion-config-schema.md](https://github.com/AranovaIO/aranova_internal/blob/master/docs/tracking-package/conversion-config-schema.md).
376
395
 
377
396
  ## Consent (v2 — opt-out model)
378
397
 
@@ -405,7 +424,14 @@ The hook returns the effective `state` (`"granted" | "denied"`), its `source` (`
405
424
 
406
425
  ## Exports
407
426
 
408
- - 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`)
427
+ - Root package: `createTracking`, `TrackingProvider`, `useTracking`, `AdPlatformTracking`,
428
+ `getTrackingConfigRuntime`, legacy `GoogleAdsTracking`, consent v2
429
+ (`useCookiePreferences`, `optIn`, `optOut`, `resetConsent`, `getConsentChoice`,
430
+ `onConsentChange`) + deprecated shims (`ConsentBanner`, `useConsent`, `useConsentState`),
431
+ attribution hooks, event types; `createSalesClient()` (isomorphic — public key writes;
432
+ secret key reads/CRUD, `summary`, `customers.*`, `business.config`) +
433
+ `toMinor`/`fromMinor`/`formatMoney`/`formatDateInTz`; phone
434
+ (`parsePhone`/`toE164`/`formatPhone`/`phoneField`, `usePhoneField`, `PhoneField`)
409
435
  - `@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.
410
436
  - `@aranova/tracking-next/middleware`: `createTrackingMiddleware()`
411
437
  - `@aranova/tracking-next/server`: `getTrackingParamsServer()`
package/dist/index.d.mts CHANGED
@@ -1,7 +1,7 @@
1
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
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
- import { C as ConversionConfig } from './sales-C3jFBx08.mjs';
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-C3jFBx08.mjs';
3
+ import { T as TrackingConfigReference, C as ConversionConfig } from './sales-QqKh6_iy.mjs';
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, U as SaleSummaryQuery, V as SaleSummaryQueryV2, W as SaleSummaryV2, X as SaleUpdateInput, Y as SalesBusinessClient, Z as SalesCategoryBreakdown, _ as SalesClient, $ as SalesClientConfig, a0 as SalesCustomersClient, a1 as SalesServiceBreakdown, a2 as SalesTransportConfig, a3 as SalesTrendPoint, a4 as SummaryCurrencyDelta, a5 as SummaryDeltas, a6 as SummaryWindow, a7 as SupportedCurrency, a8 as TRACKING_RANGES, a9 as TrackingOverviewRange, aa as createSalesClient, ab as fetchServices, ac as formatDateInTz, ad as formatMoney, ae as fromMinor, af as getTrackingConfigRuntime, ag as resolveConversionConfig, ah as saleCreateSchema, ai as saleItemSchema, aj as saleServiceSchema, ak as saleUpdateSchema, al as salesRequest, am as toMinor } from './sales-QqKh6_iy.mjs';
5
5
  import { z } from 'zod';
6
6
  import * as src from 'src';
7
7
  import * as react from 'react';
@@ -88,8 +88,8 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
88
88
  };
89
89
  cta_name: string;
90
90
  section?: string | null | undefined;
91
- destination_url?: string | null | undefined;
92
91
  href?: string | null | undefined;
92
+ destination_url?: string | null | undefined;
93
93
  element?: string | null | undefined;
94
94
  }, {
95
95
  page: {
@@ -97,8 +97,8 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
97
97
  };
98
98
  cta_name: string;
99
99
  section?: string | null | undefined;
100
- destination_url?: string | null | undefined;
101
100
  href?: string | null | undefined;
101
+ destination_url?: string | null | undefined;
102
102
  element?: string | null | undefined;
103
103
  }>;
104
104
  type CtaClickMetadata = z.infer<typeof ctaClickMetadataSchema>;
@@ -302,6 +302,7 @@ type MultiPageSessionConfig = z.infer<typeof multiPageSessionConfigSchema>;
302
302
  declare const pageExitMetadataSchema: z.ZodObject<{
303
303
  dwell_ms: z.ZodNumber;
304
304
  max_scroll_percent: z.ZodNullable<z.ZodNumber>;
305
+ scroll_baseline_percent: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
305
306
  page: z.ZodObject<{
306
307
  path: z.ZodString;
307
308
  }, "strict", z.ZodTypeAny, {
@@ -315,12 +316,14 @@ declare const pageExitMetadataSchema: z.ZodObject<{
315
316
  };
316
317
  dwell_ms: number;
317
318
  max_scroll_percent: number | null;
319
+ scroll_baseline_percent?: number | null | undefined;
318
320
  }, {
319
321
  page: {
320
322
  path: string;
321
323
  };
322
324
  dwell_ms: number;
323
325
  max_scroll_percent: number | null;
326
+ scroll_baseline_percent?: number | null | undefined;
324
327
  }>;
325
328
  type PageExitMetadata = z.infer<typeof pageExitMetadataSchema>;
326
329
  /**
@@ -602,10 +605,101 @@ declare const timeOnSiteConfigSchema: z.ZodObject<{
602
605
  }>;
603
606
  type TimeOnSiteConfig = z.infer<typeof timeOnSiteConfigSchema>;
604
607
 
608
+ type EventOutcomeRole = "lead" | "engagement" | "navigation" | "diagnostic";
609
+ type EventCategory = "page" | "engagement" | "lead" | "commerce" | "system";
610
+ type EventClientVisibility = "simple" | "detailed" | "hidden";
611
+ interface EventSemantics {
612
+ label: string;
613
+ category: EventCategory;
614
+ outcomeRole: EventOutcomeRole;
615
+ clientVisibility: EventClientVisibility;
616
+ }
617
+ /**
618
+ * Lightweight runtime event metadata. This module intentionally imports no
619
+ * Zod schemas so dashboards and framework adapters can consume it without
620
+ * pulling the validation registry into their bundles.
621
+ */
622
+ declare const EVENT_SEMANTICS: {
623
+ readonly page_view: {
624
+ readonly label: "Page view";
625
+ readonly category: "page";
626
+ readonly outcomeRole: "navigation";
627
+ readonly clientVisibility: "simple";
628
+ };
629
+ readonly time_on_site: {
630
+ readonly label: "Time on site";
631
+ readonly category: "engagement";
632
+ readonly outcomeRole: "engagement";
633
+ readonly clientVisibility: "detailed";
634
+ };
635
+ readonly specific_page_visit: {
636
+ readonly label: "Key page visit";
637
+ readonly category: "engagement";
638
+ readonly outcomeRole: "engagement";
639
+ readonly clientVisibility: "detailed";
640
+ };
641
+ readonly scroll_depth: {
642
+ readonly label: "Scroll depth";
643
+ readonly category: "engagement";
644
+ readonly outcomeRole: "engagement";
645
+ readonly clientVisibility: "detailed";
646
+ };
647
+ readonly multi_page_session: {
648
+ readonly label: "Multi-page session";
649
+ readonly category: "engagement";
650
+ readonly outcomeRole: "engagement";
651
+ readonly clientVisibility: "detailed";
652
+ };
653
+ readonly form_start: {
654
+ readonly label: "Form started";
655
+ readonly category: "engagement";
656
+ readonly outcomeRole: "engagement";
657
+ readonly clientVisibility: "simple";
658
+ };
659
+ readonly sdk_heartbeat: {
660
+ readonly label: "SDK heartbeat";
661
+ readonly category: "system";
662
+ readonly outcomeRole: "diagnostic";
663
+ readonly clientVisibility: "hidden";
664
+ };
665
+ readonly page_exit: {
666
+ readonly label: "Page exit";
667
+ readonly category: "engagement";
668
+ readonly outcomeRole: "diagnostic";
669
+ readonly clientVisibility: "detailed";
670
+ };
671
+ readonly form_submit: {
672
+ readonly label: "Form submitted";
673
+ readonly category: "lead";
674
+ readonly outcomeRole: "lead";
675
+ readonly clientVisibility: "simple";
676
+ };
677
+ readonly phone_click: {
678
+ readonly label: "Phone click";
679
+ readonly category: "lead";
680
+ readonly outcomeRole: "lead";
681
+ readonly clientVisibility: "simple";
682
+ };
683
+ readonly cta_click: {
684
+ readonly label: "CTA click";
685
+ readonly category: "engagement";
686
+ readonly outcomeRole: "engagement";
687
+ readonly clientVisibility: "simple";
688
+ };
689
+ };
690
+ type EventName = keyof typeof EVENT_SEMANTICS;
691
+ declare function getEventSemantics(eventName: string): EventSemantics | null;
692
+
605
693
  type EventKind = "automatic" | "manual";
606
694
  declare const EVENT_REGISTRY: {
607
695
  readonly page_view: {
608
696
  readonly kind: "automatic";
697
+ readonly semantics: {
698
+ readonly label: "Page view";
699
+ readonly category: "page";
700
+ readonly outcomeRole: "navigation";
701
+ readonly clientVisibility: "simple";
702
+ };
609
703
  readonly metadataSchema: z.ZodObject<{
610
704
  page: z.ZodObject<{
611
705
  title: z.ZodNullable<z.ZodString>;
@@ -663,6 +757,12 @@ declare const EVENT_REGISTRY: {
663
757
  };
664
758
  readonly time_on_site: {
665
759
  readonly kind: "automatic";
760
+ readonly semantics: {
761
+ readonly label: "Time on site";
762
+ readonly category: "engagement";
763
+ readonly outcomeRole: "engagement";
764
+ readonly clientVisibility: "detailed";
765
+ };
666
766
  readonly metadataSchema: z.ZodObject<{
667
767
  duration_ms: z.ZodNumber;
668
768
  page: z.ZodObject<{
@@ -693,6 +793,12 @@ declare const EVENT_REGISTRY: {
693
793
  };
694
794
  readonly specific_page_visit: {
695
795
  readonly kind: "automatic";
796
+ readonly semantics: {
797
+ readonly label: "Key page visit";
798
+ readonly category: "engagement";
799
+ readonly outcomeRole: "engagement";
800
+ readonly clientVisibility: "detailed";
801
+ };
696
802
  readonly metadataSchema: z.ZodObject<{
697
803
  page_name: z.ZodEnum<["contact_page", "about_page", "services_page", "booking_page", "location_page", "pricing_page", "faq_page", "testimonials_page"]>;
698
804
  page: z.ZodObject<{
@@ -738,6 +844,12 @@ declare const EVENT_REGISTRY: {
738
844
  };
739
845
  readonly scroll_depth: {
740
846
  readonly kind: "automatic";
847
+ readonly semantics: {
848
+ readonly label: "Scroll depth";
849
+ readonly category: "engagement";
850
+ readonly outcomeRole: "engagement";
851
+ readonly clientVisibility: "detailed";
852
+ };
741
853
  readonly metadataSchema: z.ZodObject<{
742
854
  depth_percent: z.ZodNumber;
743
855
  page: z.ZodObject<{
@@ -768,6 +880,12 @@ declare const EVENT_REGISTRY: {
768
880
  };
769
881
  readonly multi_page_session: {
770
882
  readonly kind: "automatic";
883
+ readonly semantics: {
884
+ readonly label: "Multi-page session";
885
+ readonly category: "engagement";
886
+ readonly outcomeRole: "engagement";
887
+ readonly clientVisibility: "detailed";
888
+ };
771
889
  readonly metadataSchema: z.ZodObject<{
772
890
  page_count: z.ZodNumber;
773
891
  page: z.ZodObject<{
@@ -798,6 +916,12 @@ declare const EVENT_REGISTRY: {
798
916
  };
799
917
  readonly form_start: {
800
918
  readonly kind: "automatic";
919
+ readonly semantics: {
920
+ readonly label: "Form started";
921
+ readonly category: "engagement";
922
+ readonly outcomeRole: "engagement";
923
+ readonly clientVisibility: "simple";
924
+ };
801
925
  readonly metadataSchema: z.ZodObject<{
802
926
  form: z.ZodObject<{
803
927
  id: z.ZodString;
@@ -843,6 +967,12 @@ declare const EVENT_REGISTRY: {
843
967
  };
844
968
  readonly sdk_heartbeat: {
845
969
  readonly kind: "automatic";
970
+ readonly semantics: {
971
+ readonly label: "SDK heartbeat";
972
+ readonly category: "system";
973
+ readonly outcomeRole: "diagnostic";
974
+ readonly clientVisibility: "hidden";
975
+ };
846
976
  readonly metadataSchema: z.ZodObject<{
847
977
  sdk_version: z.ZodString;
848
978
  package_name: z.ZodNullable<z.ZodString>;
@@ -884,9 +1014,16 @@ declare const EVENT_REGISTRY: {
884
1014
  };
885
1015
  readonly page_exit: {
886
1016
  readonly kind: "automatic";
1017
+ readonly semantics: {
1018
+ readonly label: "Page exit";
1019
+ readonly category: "engagement";
1020
+ readonly outcomeRole: "diagnostic";
1021
+ readonly clientVisibility: "detailed";
1022
+ };
887
1023
  readonly metadataSchema: z.ZodObject<{
888
1024
  dwell_ms: z.ZodNumber;
889
1025
  max_scroll_percent: z.ZodNullable<z.ZodNumber>;
1026
+ scroll_baseline_percent: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
890
1027
  page: z.ZodObject<{
891
1028
  path: z.ZodString;
892
1029
  }, "strict", z.ZodTypeAny, {
@@ -900,17 +1037,25 @@ declare const EVENT_REGISTRY: {
900
1037
  };
901
1038
  dwell_ms: number;
902
1039
  max_scroll_percent: number | null;
1040
+ scroll_baseline_percent?: number | null | undefined;
903
1041
  }, {
904
1042
  page: {
905
1043
  path: string;
906
1044
  };
907
1045
  dwell_ms: number;
908
1046
  max_scroll_percent: number | null;
1047
+ scroll_baseline_percent?: number | null | undefined;
909
1048
  }>;
910
1049
  readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
911
1050
  };
912
1051
  readonly form_submit: {
913
1052
  readonly kind: "manual";
1053
+ readonly semantics: {
1054
+ readonly label: "Form submitted";
1055
+ readonly category: "lead";
1056
+ readonly outcomeRole: "lead";
1057
+ readonly clientVisibility: "simple";
1058
+ };
914
1059
  readonly metadataSchema: z.ZodObject<{
915
1060
  form: z.ZodObject<{
916
1061
  id: z.ZodString;
@@ -990,6 +1135,12 @@ declare const EVENT_REGISTRY: {
990
1135
  };
991
1136
  readonly phone_click: {
992
1137
  readonly kind: "manual";
1138
+ readonly semantics: {
1139
+ readonly label: "Phone click";
1140
+ readonly category: "lead";
1141
+ readonly outcomeRole: "lead";
1142
+ readonly clientVisibility: "simple";
1143
+ };
993
1144
  readonly metadataSchema: z.ZodObject<{
994
1145
  phone_number: z.ZodString;
995
1146
  page: z.ZodObject<{
@@ -1033,6 +1184,12 @@ declare const EVENT_REGISTRY: {
1033
1184
  };
1034
1185
  readonly cta_click: {
1035
1186
  readonly kind: "manual";
1187
+ readonly semantics: {
1188
+ readonly label: "CTA click";
1189
+ readonly category: "engagement";
1190
+ readonly outcomeRole: "engagement";
1191
+ readonly clientVisibility: "simple";
1192
+ };
1036
1193
  readonly metadataSchema: z.ZodObject<{
1037
1194
  cta_name: z.ZodString;
1038
1195
  page: z.ZodObject<{
@@ -1052,8 +1209,8 @@ declare const EVENT_REGISTRY: {
1052
1209
  };
1053
1210
  cta_name: string;
1054
1211
  section?: string | null | undefined;
1055
- destination_url?: string | null | undefined;
1056
1212
  href?: string | null | undefined;
1213
+ destination_url?: string | null | undefined;
1057
1214
  element?: string | null | undefined;
1058
1215
  }, {
1059
1216
  page: {
@@ -1061,8 +1218,8 @@ declare const EVENT_REGISTRY: {
1061
1218
  };
1062
1219
  cta_name: string;
1063
1220
  section?: string | null | undefined;
1064
- destination_url?: string | null | undefined;
1065
1221
  href?: string | null | undefined;
1222
+ destination_url?: string | null | undefined;
1066
1223
  element?: string | null | undefined;
1067
1224
  }>;
1068
1225
  readonly configSchema: z.ZodObject<{
@@ -1084,10 +1241,6 @@ declare const EVENT_REGISTRY: {
1084
1241
  }>;
1085
1242
  };
1086
1243
  };
1087
- /**
1088
- * Name of any event known to the tracking SDK.
1089
- */
1090
- type EventName = keyof typeof EVENT_REGISTRY;
1091
1244
  /**
1092
1245
  * Event names that are fired by the SDK when their configured signal occurs.
1093
1246
  *
@@ -1149,6 +1302,10 @@ declare const ALL_AUTOMATIC_EVENT_NAMES: readonly AutomaticEventName[];
1149
1302
  * Runtime list of manual event names.
1150
1303
  */
1151
1304
  declare const ALL_MANUAL_EVENT_NAMES: readonly ManualEventName[];
1305
+ /**
1306
+ * Events that represent a lead/outcome in first-party tracking projections.
1307
+ */
1308
+ declare const ALL_LEAD_EVENT_NAMES: readonly EventName[];
1152
1309
  /**
1153
1310
  * Trigger registry passed to `createTracking({ triggers })`.
1154
1311
  *
@@ -1212,6 +1369,7 @@ type TrackableEvent<TRegistry extends TriggerRegistryConfig> = {
1212
1369
  }[RegisteredManualEvents<TRegistry>];
1213
1370
  declare function getEventDefinition(name: EventName): {
1214
1371
  kind: EventKind;
1372
+ semantics: EventSemantics;
1215
1373
  metadataSchema: z.ZodTypeAny;
1216
1374
  configSchema: z.ZodTypeAny;
1217
1375
  };
@@ -1453,6 +1611,10 @@ interface AdPlatformTrackingProps {
1453
1611
  gtagId?: string;
1454
1612
  /** Labelled Google Ads tag map — ALL loaded; wins over `gtagId`. */
1455
1613
  gtagIds?: GtagEnvironmentMap;
1614
+ /** R2-authoritative Google tracking config. When set, static gtagId(s) are ignored. */
1615
+ trackingConfig?: TrackingConfigReference;
1616
+ /** Fire a Google page view from this standalone loader. Leave false when using TrackingProvider. */
1617
+ standalonePageView?: boolean;
1456
1618
  /** Single Meta Pixel id, e.g. `123456789012345`. */
1457
1619
  metaPixelId?: string;
1458
1620
  /** Labelled Meta Pixel map — ALL loaded; wins over `metaPixelId`. */
@@ -1464,7 +1626,7 @@ interface AdPlatformTrackingProps {
1464
1626
  * `next/script`. Render once in the root layout; omit a platform's props to
1465
1627
  * skip it. Renders no visible UI.
1466
1628
  */
1467
- declare function AdPlatformTracking({ gtagId, gtagIds, metaPixelId, metaPixelIds, }: AdPlatformTrackingProps): react_jsx_runtime.JSX.Element;
1629
+ declare function AdPlatformTracking({ gtagId, gtagIds, trackingConfig, standalonePageView, metaPixelId, metaPixelIds, }: AdPlatformTrackingProps): react_jsx_runtime.JSX.Element;
1468
1630
 
1469
1631
  /**
1470
1632
  * Props for the Next.js Google Ads tracking component.
@@ -1537,6 +1699,7 @@ interface CreateTrackingOptions<TRegistry extends TriggerRegistryConfig> {
1537
1699
  cdnUrl: string;
1538
1700
  baked?: ConversionConfig | null;
1539
1701
  };
1702
+ trackingConfig?: TrackingConfigReference;
1540
1703
  }
1541
1704
  interface TrackingProviderProps {
1542
1705
  /**
@@ -1625,4 +1788,4 @@ interface PhoneFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "t
1625
1788
  */
1626
1789
  declare const PhoneField: react.ForwardRefExoticComponent<PhoneFieldProps & react.RefAttributes<HTMLInputElement>>;
1627
1790
 
1628
- 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 };
1791
+ export { ALL_AUTOMATIC_EVENT_NAMES, ALL_LEAD_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, EVENT_SEMANTICS, type EventCategory, type EventClientVisibility, type EventConfig, type EventKind, type EventMetadata, type EventName, type EventOutcomeRole, type EventSemantics, 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, TrackingConfigReference, 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, getEventSemantics, 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 };