@glomopay/react-native-sdk 4.1.0 → 5.0.0

package/src/utils/analytics.ts

@@ -13,6 +13,16 @@
 import { Platform } from "react-native";
 import { getSegmentClient, isSegmentAvailable, getAnonymousId, getSegmentWriteKey } from "../config/segment";
 
+/**
+ * Type-only, so nothing is emitted and the cycle with `types/checkout.ts` - which imports SdkError
+ * from here - stays a compile-time one.
+ */
+/**
+ * Runtime allowlists, not type constraints - see the module comment in event-projections.ts for why
+ * a tracker must never take a payload type directly.
+ */
+import { type PaymentEventData, type TerminationEventData, type JourneyEventData } from "./event-projections";
+
 /**
  * Flow type for checkout
  */
@@ -23,6 +33,13 @@ export type FlowType = "lrs" | "standard" | "unified" | "subscriptions";
  */
 export interface CommonEventProperties {
     sdkVersion?: string;
+
+    /** Correlates every event from one mounted checkout, across repeated start() calls */
+    sessionId?: string;
+
+    /** Resolved at capture time from the bound getter, so it is never stale */
+    checkoutStatus?: string;
+
     devMode?: boolean;
     mockMode?: boolean;
     orderId?: string;
@@ -36,11 +53,105 @@ export interface CommonEventProperties {
     [key: string]: unknown;
 }
 
+/** Why start() refused to run. Distinguishes a compromised device from one we could not check. */
+export type StartFailureReason =
+    | "device_forbidden"
+    | "device_compliance_unknown"
+    | "validation_error"
+    | "payment_successful"
+    | "invalid_status"
+    | "invalid_url";
+
+/**
+ * What the SDK could and could not load in this build, carried on start_attempted and start_failed.
+ *
+ * Optional dependencies degrade silently by design, so this inventory is the only way to tell a
+ * merchant who chose not to install one from a build where something failed to link. Names packages
+ * and check names, never device identifiers.
+ */
+export interface SdkDependencyInfo {
+    jailbreakDetectionLibraryInstalled: boolean;
+    jailbreakDetected: boolean | null;
+    complianceSource?: string;
+    complianceSignals?: string[];
+    fileSaveAvailable?: boolean;
+    missingFileSavePackages?: string[];
+}
+
+/** Where a permission refusal was observed. The two are not interchangeable - see the tracker. */
+export type DevicePermissionSource = "permission_request" | "get_user_media";
+
 /** SDK error information */
 export interface SdkError {
     type: "validation_error" | "device_forbidden";
     message: string;
-    field?: "publicKey" | "orderId" | "subscriptionId" | "baseCheckoutUrl" | "generatedCheckoutUrl";
+    /**
+     * What produced the error. The first five are configuration the merchant supplied; `file.save`
+     * is a bridge message type, and is here so a document that failed to save can be filtered apart
+     * from a bad public key on a callback that carries both.
+     */
+    field?: "publicKey" | "orderId" | "subscriptionId" | "baseCheckoutUrl" | "generatedCheckoutUrl" | "file.save";
+}
+
+/**
+ * The current checkout attempt, and how to read its status.
+ *
+ * Module scope because `buildCommonProperties` is spread into every event and takes no context
+ * argument. Installed by useSdkSession for as long as a checkout component is mounted, so nothing
+ * here survives a merchant's screen being torn down.
+ */
+let activeSessionId: string | undefined;
+let readCheckoutStatus: (() => string) | undefined;
+
+/**
+ * Installs the id that correlates every event from one checkout attempt.
+ *
+ * Nothing else does: joining on `orderId` fails the moment a merchant retries `start()`, which
+ * produces two attempts that are indistinguishable without this. Scoped per mount rather than per
+ * `start()`, so a retry reads as two start_attempted events inside one session - which is the signal
+ * worth having.
+ */
+export function setSdkSession(sessionId: string | undefined): void {
+    activeSessionId = sessionId;
+}
+
+/**
+ * Binds a getter for the checkout status, resolved at capture time.
+ *
+ * A getter rather than a value, deliberately. Pushing the status per call would mean touching every
+ * tracker and would go stale between transitions - which is exactly the bug the Flutter SDK fixed in
+ * KAN-8085, where `checkout_status` was null on every real event.
+ */
+export function bindCheckoutStatus(read: (() => string) | undefined): void {
+    readCheckoutStatus = read;
+}
+
+/**
+ * Releases the session a mount installed, and only if it is still the active one.
+ *
+ * Clearing unconditionally is wrong whenever two checkout components overlap - a merchant who keeps
+ * a previous screen mounted, or renders one per row in a list. The component unmounting would strip
+ * `sessionId` and `checkoutStatus` off every later event of a sibling that is still mid-payment, and
+ * an event missing them is indistinguishable from one sent by a pre-v5 build.
+ *
+ * It does not make the singletons safe for concurrent mounts - the last mount still wins while both
+ * are alive. It removes the case where the survivor is left reporting nothing at all.
+ */
+export function releaseSdkSession(sessionId: string): void {
+    if (activeSessionId !== sessionId) {
+        return;
+    }
+    activeSessionId = undefined;
+    readCheckoutStatus = undefined;
+}
+
+/** Never lets a merchant's status getter break an event */
+function currentCheckoutStatus(): string | undefined {
+    try {
+        return readCheckoutStatus?.();
+    } catch {
+        return undefined;
+    }
 }
 
 /**
@@ -91,6 +202,8 @@ function buildCommonProperties(
         sdkVersion: getSdkVersion(),
         timestamp: new Date().toISOString(),
         ...(flowType && { flowType }),
+        ...(activeSessionId && { sessionId: activeSessionId }),
+        ...(currentCheckoutStatus() !== undefined && { checkoutStatus: currentCheckoutStatus() }),
     };
 }
 
@@ -173,7 +286,7 @@ async function trackEvent(
  * @param devMode - Whether dev mode is enabled
  * @param mockMode - Whether mock mode is enabled
  * @param lrsUrl - The LRS checkout URL
- * @param jailbreakDetectionInfo - Optional jailbreak detection information
+ * @param dependencyInfo - Optional inventory of what this build could and could not load
  */
 export function trackStartSuccess(
     orderId: string,
@@ -181,17 +294,11 @@ export function trackStartSuccess(
     devMode: boolean = false,
     mockMode: boolean = false,
     lrsUrl?: string,
-    jailbreakDetectionInfo?: {
-        jailbreakDetectionLibraryInstalled: boolean;
-        jailbreakDetected: boolean | null;
-    }
+    dependencyInfo?: SdkDependencyInfo
 ): void {
     const properties = {
         ...buildCommonProperties(orderId, publicKey, devMode, mockMode, lrsUrl),
-        ...(jailbreakDetectionInfo && {
-            jailbreakDetectionLibraryInstalled: jailbreakDetectionInfo.jailbreakDetectionLibraryInstalled,
-            jailbreakDetected: jailbreakDetectionInfo.jailbreakDetected,
-        }),
+        ...dependencyInfo,
     };
     // Async tracking to avoid blocking the main thread
     trackEvent("LRS Checkout Started", properties, devMode).catch((error) => {
@@ -210,7 +317,7 @@ export function trackStartSuccess(
  * @param devMode - Whether dev mode is enabled
  * @param mockMode - Whether mock mode is enabled
  * @param lrsUrl - The LRS checkout URL
- * @param jailbreakDetectionInfo - Optional jailbreak detection information
+ * @param dependencyInfo - Optional inventory of what this build could and could not load
  */
 export function trackStartAttempt(
     status: string,
@@ -219,18 +326,12 @@ export function trackStartAttempt(
     devMode: boolean = false,
     mockMode: boolean = false,
     lrsUrl?: string,
-    jailbreakDetectionInfo?: {
-        jailbreakDetectionLibraryInstalled: boolean;
-        jailbreakDetected: boolean | null;
-    }
+    dependencyInfo?: SdkDependencyInfo
 ): void {
     const properties = {
         ...buildCommonProperties(orderId, publicKey, devMode, mockMode, lrsUrl),
         status,
-        ...(jailbreakDetectionInfo && {
-            jailbreakDetectionLibraryInstalled: jailbreakDetectionInfo.jailbreakDetectionLibraryInstalled,
-            jailbreakDetected: jailbreakDetectionInfo.jailbreakDetected,
-        }),
+        ...dependencyInfo,
     };
     // Async tracking to avoid blocking the main thread
     trackEvent("LRS Checkout Start Attempted", properties, devMode).catch((error) => {
@@ -249,27 +350,21 @@ export function trackStartAttempt(
  * @param devMode - Whether dev mode is enabled
  * @param mockMode - Whether mock mode is enabled
  * @param lrsUrl - The LRS checkout URL
- * @param jailbreakDetectionInfo - Optional jailbreak detection information
+ * @param dependencyInfo - Optional inventory of what this build could and could not load
  */
 export function trackStartFailure(
-    reason: "device_forbidden" | "validation_error" | "payment_successful" | "invalid_status" | "invalid_url",
+    reason: StartFailureReason,
     orderId?: string,
     publicKey?: string,
     devMode: boolean = false,
     mockMode: boolean = false,
     lrsUrl?: string,
-    jailbreakDetectionInfo?: {
-        jailbreakDetectionLibraryInstalled: boolean;
-        jailbreakDetected: boolean | null;
-    }
+    dependencyInfo?: SdkDependencyInfo
 ): void {
     const properties = {
         ...buildCommonProperties(orderId, publicKey, devMode, mockMode, lrsUrl),
         failureReason: reason,
-        ...(jailbreakDetectionInfo && {
-            jailbreakDetectionLibraryInstalled: jailbreakDetectionInfo.jailbreakDetectionLibraryInstalled,
-            jailbreakDetected: jailbreakDetectionInfo.jailbreakDetected,
-        }),
+        ...dependencyInfo,
     };
     // Async tracking to avoid blocking the main thread
     trackEvent("LRS Checkout Start Failed", properties, devMode).catch((error) => {
@@ -408,16 +503,15 @@ export function trackInvalidMessageReceived(
  * @param lrsUrl - The LRS checkout URL
  */
 export function trackPaymentSuccess(
-    orderId: string,
-    paymentId: string,
+    payment: PaymentEventData,
     publicKey: string,
     devMode: boolean = false,
     mockMode: boolean = false,
     lrsUrl?: string
 ): void {
     const properties = {
-        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, lrsUrl),
-        paymentId,
+        ...buildCommonProperties(payment.orderId, publicKey, devMode, mockMode, lrsUrl),
+        ...payment,
     };
     // Async tracking to avoid blocking the main thread
     trackEvent("LRS Payment Success", properties, devMode).catch((error) => {
@@ -438,16 +532,15 @@ export function trackPaymentSuccess(
  * @param lrsUrl - The LRS checkout URL
  */
 export function trackPaymentFailure(
-    orderId: string,
-    paymentId: string,
+    payment: PaymentEventData,
     publicKey: string,
     devMode: boolean = false,
     mockMode: boolean = false,
     lrsUrl?: string
 ): void {
     const properties = {
-        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, lrsUrl),
-        paymentId,
+        ...buildCommonProperties(payment.orderId, publicKey, devMode, mockMode, lrsUrl),
+        ...payment,
     };
     // Async tracking to avoid blocking the main thread
     trackEvent("LRS Payment Failure", properties, devMode).catch((error) => {
@@ -469,7 +562,7 @@ export function trackPaymentFailure(
  */
 export function trackPaymentTerminate(
     orderId: string,
-    source: "user_dismiss" | "back_button" | "checkout_closed",
+    termination: TerminationEventData,
     publicKey: string,
     devMode: boolean = false,
     mockMode: boolean = false,
@@ -477,7 +570,7 @@ export function trackPaymentTerminate(
 ): void {
     const properties = {
         ...buildCommonProperties(orderId, publicKey, devMode, mockMode, lrsUrl),
-        terminationSource: source,
+        ...termination,
     };
     // Async tracking to avoid blocking the main thread
     trackEvent("LRS Payment Terminated", properties, devMode).catch((error) => {
@@ -619,17 +712,11 @@ export function trackStandardStartSuccess(
     devMode: boolean = false,
     mockMode: boolean = false,
     standardUrl?: string,
-    jailbreakDetectionInfo?: {
-        jailbreakDetectionLibraryInstalled: boolean;
-        jailbreakDetected: boolean | null;
-    }
+    dependencyInfo?: SdkDependencyInfo
 ): void {
     const properties = {
         ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
-        ...(jailbreakDetectionInfo && {
-            jailbreakDetectionLibraryInstalled: jailbreakDetectionInfo.jailbreakDetectionLibraryInstalled,
-            jailbreakDetected: jailbreakDetectionInfo.jailbreakDetected,
-        }),
+        ...dependencyInfo,
     };
     trackEvent("Standard Checkout Started", properties, devMode).catch((error) => {
         if (devMode) {
@@ -648,18 +735,12 @@ export function trackStandardStartAttempt(
     devMode: boolean = false,
     mockMode: boolean = false,
     standardUrl?: string,
-    jailbreakDetectionInfo?: {
-        jailbreakDetectionLibraryInstalled: boolean;
-        jailbreakDetected: boolean | null;
-    }
+    dependencyInfo?: SdkDependencyInfo
 ): void {
     const properties = {
         ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
         status,
-        ...(jailbreakDetectionInfo && {
-            jailbreakDetectionLibraryInstalled: jailbreakDetectionInfo.jailbreakDetectionLibraryInstalled,
-            jailbreakDetected: jailbreakDetectionInfo.jailbreakDetected,
-        }),
+        ...dependencyInfo,
     };
     trackEvent("Standard Checkout Start Attempted", properties, devMode).catch((error) => {
         if (devMode) {
@@ -672,24 +753,18 @@ export function trackStandardStartAttempt(
  * Tracks when the standard checkout start() method fails
  */
 export function trackStandardStartFailure(
-    reason: "device_forbidden" | "validation_error" | "payment_successful" | "invalid_status" | "invalid_url",
+    reason: StartFailureReason,
     orderId?: string,
     publicKey?: string,
     devMode: boolean = false,
     mockMode: boolean = false,
     standardUrl?: string,
-    jailbreakDetectionInfo?: {
-        jailbreakDetectionLibraryInstalled: boolean;
-        jailbreakDetected: boolean | null;
-    }
+    dependencyInfo?: SdkDependencyInfo
 ): void {
     const properties = {
         ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
         failureReason: reason,
-        ...(jailbreakDetectionInfo && {
-            jailbreakDetectionLibraryInstalled: jailbreakDetectionInfo.jailbreakDetectionLibraryInstalled,
-            jailbreakDetected: jailbreakDetectionInfo.jailbreakDetected,
-        }),
+        ...dependencyInfo,
     };
     trackEvent("Standard Checkout Start Failed", properties, devMode).catch((error) => {
         if (devMode) {
@@ -792,16 +867,15 @@ export function trackStandardInvalidMessageReceived(
  * Tracks when standard checkout onPaymentSuccess callback is invoked
  */
 export function trackStandardPaymentSuccess(
-    orderId: string,
-    paymentId: string,
+    payment: PaymentEventData,
     publicKey: string,
     devMode: boolean = false,
     mockMode: boolean = false,
     standardUrl?: string
 ): void {
     const properties = {
-        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
-        paymentId,
+        ...buildCommonProperties(payment.orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
+        ...payment,
     };
     trackEvent("Standard Payment Success", properties, devMode).catch((error) => {
         if (devMode) {
@@ -814,16 +888,15 @@ export function trackStandardPaymentSuccess(
  * Tracks when standard checkout onPaymentFailure callback is invoked
  */
 export function trackStandardPaymentFailure(
-    orderId: string,
-    paymentId: string,
+    payment: PaymentEventData,
     publicKey: string,
     devMode: boolean = false,
     mockMode: boolean = false,
     standardUrl?: string
 ): void {
     const properties = {
-        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
-        paymentId,
+        ...buildCommonProperties(payment.orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
+        ...payment,
     };
     trackEvent("Standard Payment Failure", properties, devMode).catch((error) => {
         if (devMode) {
@@ -837,7 +910,7 @@ export function trackStandardPaymentFailure(
  */
 export function trackStandardPaymentTerminate(
     orderId: string,
-    source: "user_dismiss" | "back_button" | "checkout_closed",
+    termination: TerminationEventData,
     publicKey: string,
     devMode: boolean = false,
     mockMode: boolean = false,
@@ -845,7 +918,7 @@ export function trackStandardPaymentTerminate(
 ): void {
     const properties = {
         ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
-        terminationSource: source,
+        ...termination,
     };
     trackEvent("Standard Payment Terminated", properties, devMode).catch((error) => {
         if (devMode) {
@@ -901,6 +974,7 @@ export function trackStandardSdkError(
 
 export function trackStandardBankTransferSubmitted(
     orderId: string,
+    journey: JourneyEventData,
     publicKey: string,
     devMode: boolean = false,
     mockMode: boolean = false,
@@ -908,6 +982,7 @@ export function trackStandardBankTransferSubmitted(
 ): void {
     const properties = {
         ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
+        ...journey,
     };
     trackEvent("Standard Bank Transfer Submitted", properties, devMode).catch((error) => {
         if (devMode) {
@@ -918,15 +993,15 @@ export function trackStandardBankTransferSubmitted(
 
 export function trackStandardPayViaBankCompleted(
     orderId: string,
+    journey: JourneyEventData,
     publicKey: string,
-    status: string,
     devMode: boolean = false,
     mockMode: boolean = false,
     standardUrl?: string
 ): void {
     const properties = {
         ...buildCommonProperties(orderId, publicKey, devMode, mockMode, standardUrl, "standard"),
-        payViaBankStatus: status,
+        ...journey,
     };
     trackEvent("Standard Pay Via Bank Completed", properties, devMode).catch((error) => {
         if (devMode) {
@@ -1042,19 +1117,13 @@ export function trackSubscriptionStartAttempt(
     devMode: boolean = false,
     mockMode: boolean = false,
     checkoutUrl?: string,
-    jailbreakDetectionInfo?: {
-        jailbreakDetectionLibraryInstalled: boolean;
-        jailbreakDetected: boolean | null;
-    }
+    dependencyInfo?: SdkDependencyInfo
 ): void {
     const properties = {
         ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, "subscriptions"),
         subscriptionId: orderId,
         status,
-        ...(jailbreakDetectionInfo && {
-            jailbreakDetectionLibraryInstalled: jailbreakDetectionInfo.jailbreakDetectionLibraryInstalled,
-            jailbreakDetected: jailbreakDetectionInfo.jailbreakDetected,
-        }),
+        ...dependencyInfo,
     };
     trackEvent("Subscription Checkout Start Attempted", properties, devMode).catch((error) => {
         if (devMode) {
@@ -1072,18 +1141,12 @@ export function trackSubscriptionStartSuccess(
     devMode: boolean = false,
     mockMode: boolean = false,
     checkoutUrl?: string,
-    jailbreakDetectionInfo?: {
-        jailbreakDetectionLibraryInstalled: boolean;
-        jailbreakDetected: boolean | null;
-    }
+    dependencyInfo?: SdkDependencyInfo
 ): void {
     const properties = {
         ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, "subscriptions"),
         subscriptionId: orderId,
-        ...(jailbreakDetectionInfo && {
-            jailbreakDetectionLibraryInstalled: jailbreakDetectionInfo.jailbreakDetectionLibraryInstalled,
-            jailbreakDetected: jailbreakDetectionInfo.jailbreakDetected,
-        }),
+        ...dependencyInfo,
     };
     trackEvent("Subscription Checkout Started", properties, devMode).catch((error) => {
         if (devMode) {
@@ -1096,25 +1159,19 @@ export function trackSubscriptionStartSuccess(
  * Tracks when the subscription checkout start() method fails
  */
 export function trackSubscriptionStartFailure(
-    reason: "device_forbidden" | "validation_error" | "payment_successful" | "invalid_status" | "invalid_url",
+    reason: StartFailureReason,
     orderId?: string,
     publicKey?: string,
     devMode: boolean = false,
     mockMode: boolean = false,
     checkoutUrl?: string,
-    jailbreakDetectionInfo?: {
-        jailbreakDetectionLibraryInstalled: boolean;
-        jailbreakDetected: boolean | null;
-    }
+    dependencyInfo?: SdkDependencyInfo
 ): void {
     const properties = {
         ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, "subscriptions"),
         subscriptionId: orderId,
         failureReason: reason,
-        ...(jailbreakDetectionInfo && {
-            jailbreakDetectionLibraryInstalled: jailbreakDetectionInfo.jailbreakDetectionLibraryInstalled,
-            jailbreakDetected: jailbreakDetectionInfo.jailbreakDetected,
-        }),
+        ...dependencyInfo,
     };
     trackEvent("Subscription Checkout Start Failed", properties, devMode).catch((error) => {
         if (devMode) {
@@ -1220,17 +1277,16 @@ export function trackSubscriptionInvalidMessageReceived(
  * Tracks when subscription checkout onPaymentSuccess callback is invoked
  */
 export function trackSubscriptionPaymentSuccess(
-    orderId: string,
-    paymentId: string,
+    payment: PaymentEventData,
     publicKey: string,
     devMode: boolean = false,
     mockMode: boolean = false,
     checkoutUrl?: string
 ): void {
     const properties = {
-        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, "subscriptions"),
-        subscriptionId: orderId,
-        paymentId,
+        ...buildCommonProperties(payment.orderId, publicKey, devMode, mockMode, checkoutUrl, "subscriptions"),
+        subscriptionId: payment.orderId,
+        ...payment,
     };
     trackEvent("Subscription Payment Success", properties, devMode).catch((error) => {
         if (devMode) {
@@ -1243,17 +1299,16 @@ export function trackSubscriptionPaymentSuccess(
  * Tracks when subscription checkout onPaymentFailure callback is invoked
  */
 export function trackSubscriptionPaymentFailure(
-    orderId: string,
-    paymentId: string,
+    payment: PaymentEventData,
     publicKey: string,
     devMode: boolean = false,
     mockMode: boolean = false,
     checkoutUrl?: string
 ): void {
     const properties = {
-        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, "subscriptions"),
-        subscriptionId: orderId,
-        paymentId,
+        ...buildCommonProperties(payment.orderId, publicKey, devMode, mockMode, checkoutUrl, "subscriptions"),
+        subscriptionId: payment.orderId,
+        ...payment,
     };
     trackEvent("Subscription Payment Failure", properties, devMode).catch((error) => {
         if (devMode) {
@@ -1267,7 +1322,7 @@ export function trackSubscriptionPaymentFailure(
  */
 export function trackSubscriptionPaymentTerminate(
     orderId: string,
-    source: "user_dismiss" | "back_button" | "checkout_closed",
+    termination: TerminationEventData,
     publicKey: string,
     devMode: boolean = false,
     mockMode: boolean = false,
@@ -1276,7 +1331,7 @@ export function trackSubscriptionPaymentTerminate(
     const properties = {
         ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, "subscriptions"),
         subscriptionId: orderId,
-        terminationSource: source,
+        ...termination,
     };
     trackEvent("Subscription Payment Terminated", properties, devMode).catch((error) => {
         if (devMode) {
@@ -1360,6 +1415,258 @@ export function trackUseOfUnsupportedFunctionality(
     });
 }
 
+// ---------------------------------------------------------------------------
+// SDK Navigation Telemetry
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal telemetry - fires when the user taps the SDK's back chevron over a bank flow.
+ *
+ * Its own event rather than `window.close`, which it used to reuse. The chevron is back-navigation:
+ * it returns the user to the main checkout with the session intact and the ability to pay, where
+ * `window.close` means something actually closed. Reusing it made a user pressing back
+ * indistinguishable in Segment from the page closing a window.
+ *
+ * This is the only host-invisible interaction the SDK has - the chevron deliberately does not reach
+ * onPaymentTerminate, because a merchant who cancels the order on terminate would cancel live
+ * orders every time a user backed out of one bank to try another. This event is how it stays
+ * visible to us without becoming a termination.
+ */
+export function trackBackNavigationViaSdkBackButton(
+    orderId: string,
+    publicKey: string,
+    devMode: boolean,
+    mockMode: boolean,
+    checkoutUrl: string,
+    flowType?: FlowType
+): void {
+    const properties = buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, flowType);
+    trackEvent("Back Navigation Via SDK Back Button", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on SDK back navigation:", error);
+        }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Device Permission Telemetry
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal telemetry - fires when the user refuses a device permission the bank's page asked for.
+ *
+ * This was the one callback in the SDK with no tracker at all, so a refusal was invisible: there was
+ * no way to answer how often it happens or on which flows.
+ *
+ * `source` says where the observation came from, and the two are not equivalent:
+ *
+ * - `permission_request` is the Android WebView asking us, which is also what drives
+ *   `onUserRefusedDevicePermissions`. Android only - iOS raises its own prompt inside WKWebView and
+ *   never reports the answer back.
+ * - `get_user_media` is the flow injection watching `getUserMedia` reject with `NotAllowedError`.
+ *   It reaches iOS, and it fires no callback: coverage depends on whether a given bank uses
+ *   `getUserMedia` at all, and a callback with partial coverage is a contract we cannot hold.
+ *
+ * So an absent event still means "not observable" rather than "did not happen", and `source` plus
+ * the `deviceOS` already on every event is what separates the cases.
+ */
+export function trackDevicePermissionRefused(
+    resource: string,
+    source: DevicePermissionSource,
+    orderId: string | undefined,
+    publicKey: string,
+    devMode: boolean,
+    mockMode: boolean,
+    checkoutUrl: string,
+    flowType?: FlowType
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, flowType),
+        resource,
+        source,
+    };
+    trackEvent("Device Permission Refused", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on device permission refused:", error);
+        }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Payment Payload Integrity Telemetry
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal telemetry - fires when a terminal payment payload arrives without `paymentId` or
+ * `signature`.
+ *
+ * The callback still fires; this measures how often the page reports an outcome before the backend
+ * has resolved ids, which is the thing that made the old strict validation drop real payments.
+ * Names the missing fields, never their values.
+ */
+export function trackIncompletePaymentPayload(
+    event: string,
+    missingFields: string[],
+    source: string,
+    orderId: string,
+    publicKey: string,
+    devMode: boolean,
+    mockMode: boolean,
+    checkoutUrl: string,
+    flowType?: FlowType
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, flowType),
+        event,
+        source,
+        missingFields,
+        missingFieldCount: missingFields.length,
+    };
+    trackEvent("Incomplete Payment Payload", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on incomplete payment payload:", error);
+        }
+    });
+}
+
+/**
+ * Internal telemetry - fires when a payment payload cannot be routed at all.
+ *
+ * Reached only when `orderId` is absent or the optional fields carry the wrong type, so there is no
+ * outcome to report to the merchant without fabricating one. Before v5 this path was a
+ * devMode-only `console.error`, which meant a dropped payment left no trace in a release build.
+ *
+ * Carries the payload's **key names** and nothing else - the values are payment identifiers.
+ */
+export function trackDroppedPaymentPayload(
+    event: string,
+    payloadKeys: string[],
+    source: string,
+    orderId: string | undefined,
+    publicKey: string,
+    devMode: boolean,
+    mockMode: boolean,
+    checkoutUrl: string,
+    flowType?: FlowType
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, flowType),
+        event,
+        source,
+        payloadKeys,
+    };
+    trackEvent("Payment Payload Dropped", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on dropped payment payload:", error);
+        }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// File Upload Telemetry
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal telemetry - fires when the user taps a file input on a bank's page.
+ *
+ * **The attempt only.** react-native-webview runs the whole chooser natively through
+ * `onShowFileChooser` and `startPhotoPickerIntent`, so no outcome - picked, cancelled or failed -
+ * ever reaches JavaScript. Getting one would need either a patched rnw or a page-side `change`
+ * listener reporting over the bridge, and the page here is a third party's.
+ *
+ * So an absent follow-up event means "not observable", never "the upload failed". Do not build a
+ * success rate on this.
+ */
+export function trackFileUploadRequested(
+    acceptTypes: string | undefined,
+    hasCapture: boolean,
+    orderId: string | undefined,
+    publicKey: string,
+    devMode: boolean,
+    mockMode: boolean,
+    checkoutUrl: string,
+    flowType?: FlowType
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, flowType),
+        acceptTypes,
+        hasCapture,
+    };
+    trackEvent("File Upload Requested", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on file upload requested:", error);
+        }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// File Save Telemetry
+// ---------------------------------------------------------------------------
+
+/**
+ * Event names carry no flow prefix, unlike every payment event above.
+ *
+ * Saving a document is not owned by a flow - the capability is advertised to every WebView the SDK
+ * opens - so a prefix would assert a distinction that does not exist. `flowType` rides the common
+ * properties for anyone who wants to slice by it. The names match the Flutter SDK's so one query
+ * spans both.
+ */
+
+/**
+ * Internal telemetry - fires when the page asks the SDK to put a document on the device.
+ *
+ * Paired with trackFileSaveCompleted by `saveId`, which fires for every request that got this far,
+ * including the failures and the dismissals. A requested with no completion means the handler died.
+ */
+export function trackFileSaveRequested(
+    saveId: string,
+    orderId: string | undefined,
+    publicKey: string,
+    devMode: boolean,
+    mockMode: boolean,
+    checkoutUrl: string,
+    flowType?: FlowType
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, flowType),
+        saveId,
+    };
+    trackEvent("File Save Requested", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on file save requested:", error);
+        }
+    });
+}
+
+/**
+ * Internal telemetry - fires once per request, whatever the outcome.
+ *
+ * `eventData` is the projection the saver builds, never the result object itself. The inputs to a
+ * save are a signed URL and a filename; the projection is what is safe to send, and taking it
+ * pre-built keeps the decision about what that means in one place next to the values it excludes.
+ */
+export function trackFileSaveCompleted(
+    saveId: string,
+    eventData: Record<string, unknown>,
+    orderId: string | undefined,
+    publicKey: string,
+    devMode: boolean,
+    mockMode: boolean,
+    checkoutUrl: string,
+    flowType?: FlowType
+): void {
+    const properties = {
+        ...buildCommonProperties(orderId, publicKey, devMode, mockMode, checkoutUrl, flowType),
+        ...eventData,
+        saveId,
+    };
+    trackEvent("File Save Completed", properties, devMode).catch((error) => {
+        if (devMode) {
+            console.error("[Glomo-RN-SDK] Event tracking error on file save completed:", error);
+        }
+    });
+}
+
 // ---------------------------------------------------------------------------
 // Checkout Analytics Tracker Map
 // ---------------------------------------------------------------------------
@@ -1416,14 +1723,12 @@ export const subscriptionCheckoutTrackers: CheckoutAnalyticsTrackers = {
     trackPaymentTerminate: trackSubscriptionPaymentTerminate,
     trackConnectionError: trackSubscriptionConnectionError,
     trackSdkError: trackSubscriptionSdkError,
-    trackBankTransferSubmitted: (...args) => {
-        const devMode = args[2];
+    trackBankTransferSubmitted: (_orderId, _journey, _publicKey, devMode) => {
         if (devMode) {
             console.warn("[Glomo-RN-SDK] Unexpected bank transfer event in subscription flow");
         }
     },
-    trackPayViaBankCompleted: (...args) => {
-        const devMode = args[3];
+    trackPayViaBankCompleted: (_orderId, _journey, _publicKey, devMode) => {
         if (devMode) {
             console.warn("[Glomo-RN-SDK] Unexpected pay via bank completed event in subscription flow");
         }