@aranova/tracking-next 0.15.0 → 0.16.0

package/README.md

@@ -140,6 +140,49 @@ export function LeadForm() {
 
 `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.
 
+### CTA clicks — manual or auto-capture
+
+Fire `cta_click` yourself for full control over the name:
+
+```tsx
+tracking.trackEvent("cta_click", {
+  cta_name: "Book appointment",
+  section: "hero",
+  destination_url: "/booking",
+  page: { path: window.location.pathname },
+});
+```
+
+Or opt into **auto-capture** and skip per-button code. Add `autoCapture` to the
+`cta_click` registration — this attaches a single delegated click listener:
+
+```tsx
+manual: {
+  cta_click: { autoCapture: {} }, // default selector: [data-aranova-cta]
+  // or target existing classes: { autoCapture: { selector: "a.cta, .btn-primary" } }
+},
+```
+
+Then tag your CTAs in markup — no imports, no handlers:
+
+```tsx
+<a href="/booking" data-aranova-cta="Book now" data-aranova-section="hero">Book now</a>
+<button data-aranova-cta="Get a quote">Get a quote</button>
+```
+
+`cta_name` resolves to the `data-aranova-cta` value, else the element's trimmed text
+(capped 120 chars), else `tag#id`. `section` comes from an optional `data-aranova-section`;
+`href`/`destination_url` and a short `element` descriptor are captured automatically. Point
+the selector at real CTAs (an explicit attribute is the safe default) — every matching click
+is counted, including ones that later `stopPropagation`.
+
+### Automatic dwell + exit (`page_exit`)
+
+`page_exit` is captured automatically — no registration. On route change, tab hide, and page
+unload it records the **active** (visible) time spent on the page plus the max scroll depth
+reached, delivered via a keepalive beacon so the final page still counts. This powers per-page
+dwell and drop-off in the dashboard Analytics tab; there is nothing to configure.
+
 ## Phone Fields
 
 Bundled `libphonenumber-js`: parse/format utils + a React input. Display is configurable; the

package/dist/index.d.mts

@@ -80,6 +80,8 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
     }>;
     section: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     destination_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    href: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    element: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, "strict", z.ZodTypeAny, {
     page: {
         path: string;
@@ -87,6 +89,8 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
     cta_name: string;
     section?: string | null | undefined;
     destination_url?: string | null | undefined;
+    href?: string | null | undefined;
+    element?: string | null | undefined;
 }, {
     page: {
         path: string;
@@ -94,14 +98,34 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
     cta_name: string;
     section?: string | null | undefined;
     destination_url?: string | null | undefined;
+    href?: string | null | undefined;
+    element?: string | null | undefined;
 }>;
 type CtaClickMetadata = z.infer<typeof ctaClickMetadataSchema>;
 /**
  * Registration config for `cta_click`.
  *
- * This event is manual-only and currently has no registration options.
+ * The event stays manually fireable; `autoCapture` additionally attaches a
+ * delegated click listener that fires it for any element matching `selector`
+ * (default `[data-aranova-cta]`) — tag your CTAs, get analytics for free.
  */
-declare const ctaClickConfigSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+declare const ctaClickConfigSchema: z.ZodObject<{
+    autoCapture: z.ZodOptional<z.ZodObject<{
+        selector: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        selector?: string | undefined;
+    }, {
+        selector?: string | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    autoCapture?: {
+        selector?: string | undefined;
+    } | undefined;
+}, {
+    autoCapture?: {
+        selector?: string | undefined;
+    } | undefined;
+}>;
 type CtaClickConfig = z.infer<typeof ctaClickConfigSchema>;
 
 /**
@@ -265,6 +289,49 @@ declare const multiPageSessionConfigSchema: z.ZodObject<{
 }>;
 type MultiPageSessionConfig = z.infer<typeof multiPageSessionConfigSchema>;
 
+/**
+ * Metadata for the automatic `page_exit` event.
+ *
+ * Fired when the user leaves a page (SPA navigation away, tab hidden, or
+ * pagehide). `dwell_ms` is the ACTIVE (visible) time spent on the page segment
+ * being closed — hidden time never counts, matching `time_on_site` semantics.
+ * A page revisited after being hidden emits another `page_exit` for the next
+ * visible segment, so summing `dwell_ms` per page/session yields total active
+ * dwell without double counting.
+ */
+declare const pageExitMetadataSchema: z.ZodObject<{
+    dwell_ms: z.ZodNumber;
+    max_scroll_percent: z.ZodNullable<z.ZodNumber>;
+    page: z.ZodObject<{
+        path: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        path: string;
+    }, {
+        path: string;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    page: {
+        path: string;
+    };
+    dwell_ms: number;
+    max_scroll_percent: number | null;
+}, {
+    page: {
+        path: string;
+    };
+    dwell_ms: number;
+    max_scroll_percent: number | null;
+}>;
+type PageExitMetadata = z.infer<typeof pageExitMetadataSchema>;
+/**
+ * Registration config for automatic `page_exit`.
+ *
+ * SDK-internal: attached unconditionally (like `sdk_heartbeat`), so there are
+ * no registration options.
+ */
+declare const pageExitConfigSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+type PageExitConfig = z.infer<typeof pageExitConfigSchema>;
+
 /**
  * Metadata for the automatic `page_view` event.
  *
@@ -796,6 +863,33 @@ declare const EVENT_REGISTRY: {
         }>;
         readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
     };
+    readonly page_exit: {
+        readonly kind: "automatic";
+        readonly metadataSchema: z.ZodObject<{
+            dwell_ms: z.ZodNumber;
+            max_scroll_percent: z.ZodNullable<z.ZodNumber>;
+            page: z.ZodObject<{
+                path: z.ZodString;
+            }, "strict", z.ZodTypeAny, {
+                path: string;
+            }, {
+                path: string;
+            }>;
+        }, "strict", z.ZodTypeAny, {
+            page: {
+                path: string;
+            };
+            dwell_ms: number;
+            max_scroll_percent: number | null;
+        }, {
+            page: {
+                path: string;
+            };
+            dwell_ms: number;
+            max_scroll_percent: number | null;
+        }>;
+        readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    };
     readonly form_submit: {
         readonly kind: "manual";
         readonly metadataSchema: z.ZodObject<{
@@ -915,6 +1009,8 @@ declare const EVENT_REGISTRY: {
             }>;
             section: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             destination_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            href: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            element: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         }, "strict", z.ZodTypeAny, {
             page: {
                 path: string;
@@ -922,6 +1018,8 @@ declare const EVENT_REGISTRY: {
             cta_name: string;
             section?: string | null | undefined;
             destination_url?: string | null | undefined;
+            href?: string | null | undefined;
+            element?: string | null | undefined;
         }, {
             page: {
                 path: string;
@@ -929,8 +1027,26 @@ declare const EVENT_REGISTRY: {
             cta_name: string;
             section?: string | null | undefined;
             destination_url?: string | null | undefined;
+            href?: string | null | undefined;
+            element?: string | null | undefined;
+        }>;
+        readonly configSchema: z.ZodObject<{
+            autoCapture: z.ZodOptional<z.ZodObject<{
+                selector: z.ZodOptional<z.ZodString>;
+            }, "strict", z.ZodTypeAny, {
+                selector?: string | undefined;
+            }, {
+                selector?: string | undefined;
+            }>>;
+        }, "strict", z.ZodTypeAny, {
+            autoCapture?: {
+                selector?: string | undefined;
+            } | undefined;
+        }, {
+            autoCapture?: {
+                selector?: string | undefined;
+            } | undefined;
         }>;
-        readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
     };
 };
 /**
@@ -959,6 +1075,7 @@ type MetadataByName = {
     multi_page_session: MultiPageSessionMetadata;
     form_start: FormStartMetadata;
     sdk_heartbeat: SdkHeartbeatMetadata;
+    page_exit: PageExitMetadata;
     form_submit: FormSubmitMetadata;
     phone_click: PhoneClickMetadata;
     cta_click: CtaClickMetadata;
@@ -971,6 +1088,7 @@ type ConfigByName = {
     multi_page_session: MultiPageSessionConfig;
     form_start: FormStartConfig;
     sdk_heartbeat: SdkHeartbeatConfig;
+    page_exit: PageExitConfig;
     form_submit: FormSubmitConfig;
     phone_click: PhoneClickConfig;
     cta_click: CtaClickConfig;
@@ -1085,8 +1203,14 @@ interface TrackEventInput {
 interface TrackingClient {
     /** Enqueue an event for batched delivery. */
     trackEvent: (input: TrackEventInput) => void;
-    /** Flush queued events immediately. */
+    /** Flush queued events immediately (fetch, non-keepalive). */
     flush: () => Promise<void>;
+    /**
+     * Flush queued events through the keepalive transport so the request
+     * survives document unload. Use from `pagehide`/`visibilitychange:hidden`
+     * handlers — a plain `flush()` there is aborted by the browser on unload.
+     */
+    flushBeacon: () => void;
     /** Return the current rolling session id. */
     getSessionId: () => string;
     /** Return the persistent visitor id. */
@@ -1466,4 +1590,4 @@ interface PhoneFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "t
  */
 declare const PhoneField: react.ForwardRefExoticComponent<PhoneFieldProps & react.RefAttributes<HTMLInputElement>>;
 
-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 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, pageViewConfigSchema, pageViewMetadataSchema, phoneClickConfigSchema, phoneClickMetadataSchema, scrollDepthConfigSchema, scrollDepthMetadataSchema, sdkHeartbeatConfigSchema, sdkHeartbeatMetadataSchema, sdkHeartbeatTriggersSchema, specificPageNameSchema, specificPageVisitConfigSchema, specificPageVisitMetadataSchema, timeOnSiteConfigSchema, timeOnSiteMetadataSchema, useConsent, useConsentState, useCookiePreferences, useGclid, usePhoneConfig, usePhoneField, useTrackingParams };
+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 };

package/dist/index.d.ts

@@ -80,6 +80,8 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
     }>;
     section: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     destination_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    href: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    element: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, "strict", z.ZodTypeAny, {
     page: {
         path: string;
@@ -87,6 +89,8 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
     cta_name: string;
     section?: string | null | undefined;
     destination_url?: string | null | undefined;
+    href?: string | null | undefined;
+    element?: string | null | undefined;
 }, {
     page: {
         path: string;
@@ -94,14 +98,34 @@ declare const ctaClickMetadataSchema: z.ZodObject<{
     cta_name: string;
     section?: string | null | undefined;
     destination_url?: string | null | undefined;
+    href?: string | null | undefined;
+    element?: string | null | undefined;
 }>;
 type CtaClickMetadata = z.infer<typeof ctaClickMetadataSchema>;
 /**
  * Registration config for `cta_click`.
  *
- * This event is manual-only and currently has no registration options.
+ * The event stays manually fireable; `autoCapture` additionally attaches a
+ * delegated click listener that fires it for any element matching `selector`
+ * (default `[data-aranova-cta]`) — tag your CTAs, get analytics for free.
  */
-declare const ctaClickConfigSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+declare const ctaClickConfigSchema: z.ZodObject<{
+    autoCapture: z.ZodOptional<z.ZodObject<{
+        selector: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        selector?: string | undefined;
+    }, {
+        selector?: string | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    autoCapture?: {
+        selector?: string | undefined;
+    } | undefined;
+}, {
+    autoCapture?: {
+        selector?: string | undefined;
+    } | undefined;
+}>;
 type CtaClickConfig = z.infer<typeof ctaClickConfigSchema>;
 
 /**
@@ -265,6 +289,49 @@ declare const multiPageSessionConfigSchema: z.ZodObject<{
 }>;
 type MultiPageSessionConfig = z.infer<typeof multiPageSessionConfigSchema>;
 
+/**
+ * Metadata for the automatic `page_exit` event.
+ *
+ * Fired when the user leaves a page (SPA navigation away, tab hidden, or
+ * pagehide). `dwell_ms` is the ACTIVE (visible) time spent on the page segment
+ * being closed — hidden time never counts, matching `time_on_site` semantics.
+ * A page revisited after being hidden emits another `page_exit` for the next
+ * visible segment, so summing `dwell_ms` per page/session yields total active
+ * dwell without double counting.
+ */
+declare const pageExitMetadataSchema: z.ZodObject<{
+    dwell_ms: z.ZodNumber;
+    max_scroll_percent: z.ZodNullable<z.ZodNumber>;
+    page: z.ZodObject<{
+        path: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        path: string;
+    }, {
+        path: string;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    page: {
+        path: string;
+    };
+    dwell_ms: number;
+    max_scroll_percent: number | null;
+}, {
+    page: {
+        path: string;
+    };
+    dwell_ms: number;
+    max_scroll_percent: number | null;
+}>;
+type PageExitMetadata = z.infer<typeof pageExitMetadataSchema>;
+/**
+ * Registration config for automatic `page_exit`.
+ *
+ * SDK-internal: attached unconditionally (like `sdk_heartbeat`), so there are
+ * no registration options.
+ */
+declare const pageExitConfigSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+type PageExitConfig = z.infer<typeof pageExitConfigSchema>;
+
 /**
  * Metadata for the automatic `page_view` event.
  *
@@ -796,6 +863,33 @@ declare const EVENT_REGISTRY: {
         }>;
         readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
     };
+    readonly page_exit: {
+        readonly kind: "automatic";
+        readonly metadataSchema: z.ZodObject<{
+            dwell_ms: z.ZodNumber;
+            max_scroll_percent: z.ZodNullable<z.ZodNumber>;
+            page: z.ZodObject<{
+                path: z.ZodString;
+            }, "strict", z.ZodTypeAny, {
+                path: string;
+            }, {
+                path: string;
+            }>;
+        }, "strict", z.ZodTypeAny, {
+            page: {
+                path: string;
+            };
+            dwell_ms: number;
+            max_scroll_percent: number | null;
+        }, {
+            page: {
+                path: string;
+            };
+            dwell_ms: number;
+            max_scroll_percent: number | null;
+        }>;
+        readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    };
     readonly form_submit: {
         readonly kind: "manual";
         readonly metadataSchema: z.ZodObject<{
@@ -915,6 +1009,8 @@ declare const EVENT_REGISTRY: {
             }>;
             section: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             destination_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            href: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            element: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         }, "strict", z.ZodTypeAny, {
             page: {
                 path: string;
@@ -922,6 +1018,8 @@ declare const EVENT_REGISTRY: {
             cta_name: string;
             section?: string | null | undefined;
             destination_url?: string | null | undefined;
+            href?: string | null | undefined;
+            element?: string | null | undefined;
         }, {
             page: {
                 path: string;
@@ -929,8 +1027,26 @@ declare const EVENT_REGISTRY: {
             cta_name: string;
             section?: string | null | undefined;
             destination_url?: string | null | undefined;
+            href?: string | null | undefined;
+            element?: string | null | undefined;
+        }>;
+        readonly configSchema: z.ZodObject<{
+            autoCapture: z.ZodOptional<z.ZodObject<{
+                selector: z.ZodOptional<z.ZodString>;
+            }, "strict", z.ZodTypeAny, {
+                selector?: string | undefined;
+            }, {
+                selector?: string | undefined;
+            }>>;
+        }, "strict", z.ZodTypeAny, {
+            autoCapture?: {
+                selector?: string | undefined;
+            } | undefined;
+        }, {
+            autoCapture?: {
+                selector?: string | undefined;
+            } | undefined;
         }>;
-        readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
     };
 };
 /**
@@ -959,6 +1075,7 @@ type MetadataByName = {
     multi_page_session: MultiPageSessionMetadata;
     form_start: FormStartMetadata;
     sdk_heartbeat: SdkHeartbeatMetadata;
+    page_exit: PageExitMetadata;
     form_submit: FormSubmitMetadata;
     phone_click: PhoneClickMetadata;
     cta_click: CtaClickMetadata;
@@ -971,6 +1088,7 @@ type ConfigByName = {
     multi_page_session: MultiPageSessionConfig;
     form_start: FormStartConfig;
     sdk_heartbeat: SdkHeartbeatConfig;
+    page_exit: PageExitConfig;
     form_submit: FormSubmitConfig;
     phone_click: PhoneClickConfig;
     cta_click: CtaClickConfig;
@@ -1085,8 +1203,14 @@ interface TrackEventInput {
 interface TrackingClient {
     /** Enqueue an event for batched delivery. */
     trackEvent: (input: TrackEventInput) => void;
-    /** Flush queued events immediately. */
+    /** Flush queued events immediately (fetch, non-keepalive). */
     flush: () => Promise<void>;
+    /**
+     * Flush queued events through the keepalive transport so the request
+     * survives document unload. Use from `pagehide`/`visibilitychange:hidden`
+     * handlers — a plain `flush()` there is aborted by the browser on unload.
+     */
+    flushBeacon: () => void;
     /** Return the current rolling session id. */
     getSessionId: () => string;
     /** Return the persistent visitor id. */
@@ -1466,4 +1590,4 @@ interface PhoneFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "t
  */
 declare const PhoneField: react.ForwardRefExoticComponent<PhoneFieldProps & react.RefAttributes<HTMLInputElement>>;
 
-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 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, pageViewConfigSchema, pageViewMetadataSchema, phoneClickConfigSchema, phoneClickMetadataSchema, scrollDepthConfigSchema, scrollDepthMetadataSchema, sdkHeartbeatConfigSchema, sdkHeartbeatMetadataSchema, sdkHeartbeatTriggersSchema, specificPageNameSchema, specificPageVisitConfigSchema, specificPageVisitMetadataSchema, timeOnSiteConfigSchema, timeOnSiteMetadataSchema, useConsent, useConsentState, useCookiePreferences, useGclid, usePhoneConfig, usePhoneField, useTrackingParams };
+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 };