@switchlabs/verify-ai-react-native 2.5.1 → 2.5.3

package/lib/client/index.js

@@ -52,6 +52,49 @@ function stringifyErrorMessage(value, fallback) {
     }
     return fallback;
 }
+const VERIFY_METADATA_TELEMETRY_KEYS = [
+    'rideId',
+    'vehicleType',
+    'verificationAttemptId',
+    'verificationAttempt',
+    'verificationMaxAttempts',
+    'verificationSource',
+    'torchEnabled',
+    'scannerSessionId',
+];
+function toTelemetryKey(key) {
+    return key
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/[^a-zA-Z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .toLowerCase();
+}
+function compactClientTelemetryMetadata(metadata = {}) {
+    const compacted = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        if (value === null || value === undefined)
+            continue;
+        compacted[key] = typeof value === 'boolean' ? (value ? 1 : 0) : value;
+    }
+    return compacted;
+}
+function buildVerifyTelemetryMetadata(requestMetadata, options) {
+    const metadata = {
+        ...options?.telemetryMetadata,
+    };
+    if (options?.idempotencyKey) {
+        metadata.idempotency_key = options.idempotencyKey;
+    }
+    for (const key of VERIFY_METADATA_TELEMETRY_KEYS) {
+        const value = requestMetadata?.[key];
+        if (typeof value === 'string' ||
+            typeof value === 'number' ||
+            typeof value === 'boolean') {
+            metadata[`verify_metadata_${toTelemetryKey(key)}`] = value;
+        }
+    }
+    return metadata;
+}
 export class VerifyAIClient {
     constructor(config) {
         if (!config.apiKey) {
@@ -101,7 +144,7 @@ export class VerifyAIClient {
         const message = error instanceof Error ? error.message : stringifyErrorMessage(error, 'VerifyAI request failed');
         return this.buildRequestError(message, 0, context);
     }
-    async executeRequest(path, options = {}) {
+    async executeRequest(path, options = {}, telemetryMetadata = {}) {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.timeout);
         const method = (options.method || 'GET').toUpperCase();
@@ -156,6 +199,7 @@ export class VerifyAIClient {
                     ? `${normalized.message} [${context.method} ${context.path}; timeout=${this.timeout}ms]`
                     : normalized;
                 const metadata = {
+                    ...compactClientTelemetryMetadata(telemetryMetadata),
                     method: context.method,
                     path: context.path,
                     status: normalized.status,
@@ -178,8 +222,8 @@ export class VerifyAIClient {
             clearTimeout(timer);
         }
     }
-    async request(path, options = {}) {
-        return this.executeRequest(path, options);
+    async request(path, options = {}, telemetryMetadata = {}) {
+        return this.executeRequest(path, options, telemetryMetadata);
     }
     /**
      * Submit a photo for AI verification.
@@ -209,11 +253,12 @@ export class VerifyAIClient {
             headers['Idempotency-Key'] = options.idempotencyKey;
         }
         const enrichedRequest = { ...request, metadata: enrichMetadata(request.metadata) };
+        const telemetryMetadata = buildVerifyTelemetryMetadata(enrichedRequest.metadata, options);
         return this.request('/verify', {
             method: 'POST',
             headers,
             body: JSON.stringify(enrichedRequest),
-        });
+        }, telemetryMetadata);
     }
     /**
      * Submit a photo for AI verification using multipart/form-data.
@@ -232,7 +277,8 @@ export class VerifyAIClient {
             name: 'photo.jpg',
         });
         formData.append('policy', request.policy);
-        formData.append('metadata', JSON.stringify(enrichMetadata(request.metadata)));
+        const enrichedMetadata = enrichMetadata(request.metadata);
+        formData.append('metadata', JSON.stringify(enrichedMetadata));
         if (request.provider) {
             formData.append('provider', request.provider);
         }
@@ -246,12 +292,13 @@ export class VerifyAIClient {
         if (options?.idempotencyKey) {
             headers['Idempotency-Key'] = options.idempotencyKey;
         }
+        const telemetryMetadata = buildVerifyTelemetryMetadata(enrichedMetadata, options);
         try {
             return await this.executeRequest('/verify', {
                 method: 'POST',
                 headers,
                 body: formData,
-            });
+            }, telemetryMetadata);
         }
         catch (error) {
             // 5xx during multipart can mean the server crashed before reservation
@@ -271,7 +318,7 @@ export class VerifyAIClient {
                         metadata: request.metadata,
                         provider: request.provider,
                         include_image_data: request.include_image_data,
-                    }, options?.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : undefined);
+                    }, options);
                 }
                 catch {
                     // If the retry itself fails, throw the original error

package/lib/components/VerifyAIScanner.js

@@ -20,12 +20,21 @@ const CAMERA_INIT_ERROR_CODE = 'ERR_CAMERA_INIT_FAILED';
 const DEFAULT_TERMINAL_RESULT_DISPLAY_MS = 3000;
 const TRANSIENT_ERROR_DISPLAY_MS = 3000;
 const CAMERA_CAPTURE_RETRY_DELAY_MS = 350;
+const CAMERA_CAPTURE_RETRY_TORCH_SETTLE_MS = 800;
 const IOS_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS = 3000;
 const ANDROID_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS = 10000;
-const IOS_CAMERA_STARTUP_WATCHDOG_MS = 8000;
+// iOS AVCaptureSession cold start can legitimately exceed 8s on first launch (permission
+// prompt, first-ever session spin-up, thermal/low-power throttling). An 8s watchdog tore
+// down sessions that were seconds from ready and restarted from scratch, which made slow
+// cold starts *worse* and fired camera_preview_timeout in bursts. Match Android at 10s.
+const IOS_CAMERA_STARTUP_WATCHDOG_MS = 10000;
 const ANDROID_CAMERA_STARTUP_WATCHDOG_MS = 10000;
 const CAMERA_STARTUP_SLOW_TELEMETRY_MS = 3000;
+// Base backoff between startup remounts. Each successive remount escalates this (see
+// startupRemountBackoffMs below) so later attempts get progressively more uninterrupted
+// time to initialize the native session instead of thrashing at a fixed interval.
 const CAMERA_STARTUP_REMOUNT_BACKOFF_MS = 350;
+const CAMERA_STARTUP_REMOUNT_BACKOFF_MAX_MS = 1200;
 const CAMERA_STARTUP_WATCHDOG_MAX_REMOUNTS = 5;
 const ANDROID_ORIENTATION_NO_EVENT_TIMEOUT_MS = 3000;
 const ANDROID_ORIENTATION_SAMPLE_TELEMETRY_MS = 3000;
@@ -76,6 +85,9 @@ function createScannerError(message, code, name) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function createScannerSessionId() {
+    return `scan_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
 function isNativeCameraCaptureError(error) {
     const message = error.message.toLowerCase();
     return (error.code === CAMERA_CAPTURE_ERROR_CODE ||
@@ -261,7 +273,12 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
     const [physicalOrientation, setPhysicalOrientation] = useState('portrait');
     physicalOrientationRef.current = physicalOrientation;
     const overlayRotationDeg = getOverlayRotationDeg(physicalOrientation);
+    const scannerSessionIdRef = useRef(createScannerSessionId());
+    const captureSequenceRef = useRef(0);
+    const torchRetrySuppressedRef = useRef(false);
+    const [torchRetrySuppressed, setTorchRetrySuppressed] = useState(false);
     const buildScannerTelemetryMetadata = useCallback((extra = {}) => compactTelemetryMetadata({
+        scanner_session_id: scannerSessionIdRef.current,
         policy,
         status,
         camera_ready: cameraReadyRef.current,
@@ -290,6 +307,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         last_orientation_remount_at: lastOrientationRemountAtRef.current,
         last_capture_retry_at: lastCaptureRetryAtRef.current,
         requested_torch_enabled: enableTorch ? 1 : 0,
+        torch_retry_suppressed: torchRetrySuppressedRef.current,
         android_native_orientation_subscription_active: 0,
         android_native_orientation_event_count: 0,
         android_native_orientation_change_count: 0,
@@ -342,6 +360,10 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
     ]);
     telemetryRef.current = telemetry;
     buildScannerTelemetryMetadataRef.current = buildScannerTelemetryMetadata;
+    const setTorchSuppressedForRetry = useCallback((nextSuppressed) => {
+        torchRetrySuppressedRef.current = nextSuppressed;
+        setTorchRetrySuppressed(nextSuppressed);
+    }, []);
     useEffect(() => {
         const reporter = telemetryRef.current;
         if (reporter) {
@@ -382,7 +404,8 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         cameraStartupAttemptStartedAtRef.current = Date.now();
         if (opts.log) {
             console.warn(`VerifyAI[${SDK_VERSION}]: remounting camera reason=${reason} ` +
-                `backoffMs=${opts.backoffMs ?? 0} torchRequested=${enableTorch ? 1 : 0}`);
+                `backoffMs=${opts.backoffMs ?? 0} torchRequested=${enableTorch ? 1 : 0} ` +
+                `torchRetrySuppressed=${torchRetrySuppressedRef.current ? 1 : 0}`);
         }
         const remount = () => {
             setCameraKey((k) => k + 1);
@@ -829,6 +852,9 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                     const startupWatchdogRemountCount = startupWatchdogRemountCountRef.current + 1;
                     startupWatchdogRemountCountRef.current = startupWatchdogRemountCount;
                     cameraRemountCountRef.current++;
+                    // Escalate the backoff with each attempt (350, 700, 1050, capped at 1200ms) so a
+                    // camera that just needs more time isn't repeatedly interrupted at a fixed cadence.
+                    const startupRemountBackoffMs = Math.min(CAMERA_STARTUP_REMOUNT_BACKOFF_MS * startupWatchdogRemountCount, CAMERA_STARTUP_REMOUNT_BACKOFF_MAX_MS);
                     telemetry?.track('camera_preview_timeout', {
                         component: 'scanner',
                         error: `Camera did not initialize within ${Math.round(watchdogMs / 1000)} seconds — remounting`,
@@ -837,12 +863,12 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                             remount_reason: 'startup_watchdog',
                             startup_watchdog_remount_count: startupWatchdogRemountCount,
                             startup_watchdog_max_remounts: CAMERA_STARTUP_WATCHDOG_MAX_REMOUNTS,
-                            startup_remount_backoff_ms: CAMERA_STARTUP_REMOUNT_BACKOFF_MS,
+                            startup_remount_backoff_ms: startupRemountBackoffMs,
                             torch_deferred_until_ready: enableTorch ? 1 : 0,
                         }),
                     });
                     requestCameraRemount('startup_watchdog', {
-                        backoffMs: CAMERA_STARTUP_REMOUNT_BACKOFF_MS,
+                        backoffMs: startupRemountBackoffMs,
                         log: true,
                     });
                 }
@@ -875,6 +901,9 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         }
     }, [buildScannerTelemetryMetadata, permission, telemetry]);
     const handleCapture = useCallback(async () => {
+        const captureSequence = captureSequenceRef.current + 1;
+        captureSequenceRef.current = captureSequence;
+        const captureAttemptId = `${scannerSessionIdRef.current}_cap_${captureSequence}`;
         const blockedReason = !cameraRef.current
             ? 'camera_ref_null'
             : !cameraReadyRef.current
@@ -892,6 +921,8 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
             component: 'scanner',
             error: blockedReason == null ? 'capture_requested' : 'capture_ignored',
             metadata: buildScannerTelemetryMetadata({
+                capture_attempt_id: captureAttemptId,
+                capture_sequence: captureSequence,
                 capture_blocked_reason: blockedReason,
             }),
         });
@@ -912,6 +943,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
             return;
         }
         setStatus('capturing');
+        setTorchSuppressedForRetry(false);
         setResult(null);
         setLastError(null);
         terminalResultRef.current = null;
@@ -923,6 +955,9 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         let nativeCaptureAttempts = 0;
         let captureRetryAttempted = false;
         let captureRetryReady = false;
+        let captureRetryTorchSuppressed = false;
+        let captureRetrySettleDelayMs = CAMERA_CAPTURE_RETRY_DELAY_MS;
+        let captureRetryRemountBackoffMs = 0;
         let lastNativeCaptureErrorMessage = null;
         try {
             const capturePhysicalOrientation = physicalOrientation;
@@ -931,6 +966,8 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                 component: 'scanner',
                 error: 'capture_orientation_context',
                 metadata: buildScannerTelemetryMetadata({
+                    capture_attempt_id: captureAttemptId,
+                    capture_sequence: captureSequence,
                     capture_physical_orientation: capturePhysicalOrientation,
                     capture_overlay_rotation_deg: captureOverlayRotationDeg,
                     capture_rotation_applied: 0,
@@ -988,11 +1025,23 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                         lastNativeCaptureErrorMessage = normalized.message;
                         if (attempt === 1 && isNativeCameraCaptureError(normalized) && !terminated) {
                             captureRetryAttempted = true;
+                            captureRetryTorchSuppressed = !!enableTorch;
+                            captureRetrySettleDelayMs = captureRetryTorchSuppressed
+                                ? CAMERA_CAPTURE_RETRY_TORCH_SETTLE_MS
+                                : CAMERA_CAPTURE_RETRY_DELAY_MS;
+                            captureRetryRemountBackoffMs = captureRetryTorchSuppressed
+                                ? CAMERA_CAPTURE_RETRY_DELAY_MS
+                                : 0;
                             const retryAt = new Date().toISOString();
                             lastCaptureRetryAtRef.current = retryAt;
                             cameraRemountCountRef.current++;
-                            requestCameraRemount('capture_retry');
-                            await sleep(CAMERA_CAPTURE_RETRY_DELAY_MS);
+                            if (captureRetryTorchSuppressed) {
+                                setTorchSuppressedForRetry(true);
+                            }
+                            requestCameraRemount('capture_retry', captureRetryRemountBackoffMs > 0
+                                ? { backoffMs: captureRetryRemountBackoffMs }
+                                : undefined);
+                            await sleep(captureRetrySettleDelayMs);
                             const captureRetryReadyTimeoutMs = Platform.OS === 'android'
                                 ? ANDROID_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS
                                 : IOS_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS;
@@ -1002,11 +1051,16 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                                 error: normalized,
                                 errorCode: normalized.code,
                                 metadata: buildScannerTelemetryMetadata({
+                                    capture_attempt_id: captureAttemptId,
+                                    capture_sequence: captureSequence,
                                     native_capture_attempts: nativeCaptureAttempts,
                                     capture_retry_attempted: captureRetryAttempted,
                                     capture_retry_ready: captureRetryReady,
                                     capture_retry_delay_ms: CAMERA_CAPTURE_RETRY_DELAY_MS,
+                                    capture_retry_settle_delay_ms: captureRetrySettleDelayMs,
+                                    capture_retry_remount_backoff_ms: captureRetryRemountBackoffMs,
                                     capture_retry_ready_timeout_ms: captureRetryReadyTimeoutMs,
+                                    capture_retry_torch_suppressed: captureRetryTorchSuppressed,
                                     last_native_capture_error: lastNativeCaptureErrorMessage,
                                 }),
                             });
@@ -1074,6 +1128,8 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
             telemetry?.track('image_processed', {
                 component: 'scanner',
                 metadata: buildScannerTelemetryMetadata({
+                    capture_attempt_id: captureAttemptId,
+                    capture_sequence: captureSequence,
                     original_width: origWidth,
                     original_height: origHeight,
                     processed_width: processedWidth,
@@ -1083,6 +1139,9 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                     native_capture_attempts: nativeCaptureAttempts,
                     capture_retry_attempted: captureRetryAttempted,
                     capture_retry_ready: captureRetryReady,
+                    capture_retry_torch_suppressed: captureRetryTorchSuppressed,
+                    capture_retry_settle_delay_ms: captureRetrySettleDelayMs,
+                    capture_retry_remount_backoff_ms: captureRetryRemountBackoffMs,
                     recovered_native_capture_failure: captureRetryAttempted ? 1 : 0,
                     last_native_capture_error: lastNativeCaptureErrorMessage,
                 }),
@@ -1151,9 +1210,14 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                     component: 'scanner',
                     error,
                     metadata: buildScannerTelemetryMetadata({
+                        capture_attempt_id: captureAttemptId,
+                        capture_sequence: captureSequence,
                         native_capture_attempts: nativeCaptureAttempts,
                         capture_retry_attempted: captureRetryAttempted,
                         capture_retry_ready: captureRetryReady,
+                        capture_retry_torch_suppressed: captureRetryTorchSuppressed,
+                        capture_retry_settle_delay_ms: captureRetrySettleDelayMs,
+                        capture_retry_remount_backoff_ms: captureRetryRemountBackoffMs,
                         is_native_camera_capture_error: isNativeCameraCaptureError(error),
                         last_native_capture_error: lastNativeCaptureErrorMessage,
                     }),
@@ -1163,7 +1227,10 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                 setTimeout(() => setStatus('idle'), TRANSIENT_ERROR_DISPLAY_MS);
             }
         }
-    }, [status, exhausted, onCapture, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust, releaseCamera, scheduleTerminalResult, buildScannerTelemetryMetadata, requestCameraRemount, telemetry, terminated, physicalOrientation, overlayRotationDeg]);
+        finally {
+            setTorchSuppressedForRetry(false);
+        }
+    }, [status, exhausted, onCapture, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust, releaseCamera, scheduleTerminalResult, buildScannerTelemetryMetadata, requestCameraRemount, telemetry, terminated, physicalOrientation, overlayRotationDeg, enableTorch, setTorchSuppressedForRetry]);
     // Expose capture to parent via ref
     if (captureRef) {
         captureRef.current = handleCapture;
@@ -1175,7 +1242,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         return (_jsxs(View, { style: [styles.container, styles.permissionContainer, style], children: [_jsx(Text, { style: styles.permissionText, children: "Camera access is required for photo verification" }), _jsx(TouchableOpacity, { style: styles.permissionButton, onPress: requestPermission, children: _jsx(Text, { style: styles.permissionButtonText, children: "Grant Camera Access" }) })] }));
     }
     const showBottomCard = status === 'success' || status === 'error';
-    const shouldEnableTorch = !terminated && cameraReady && !!enableTorch;
+    const shouldEnableTorch = !terminated && cameraReady && !!enableTorch && !torchRetrySuppressed;
     return (_jsx(View, { style: [styles.container, style], children: cameraMounted && (_jsx(CameraView, { ref: cameraRef, style: styles.camera, facing: "back", enableTorch: shouldEnableTorch, onCameraReady: onCameraReady, onMountError: onMountError, responsiveOrientationWhenOrientationLocked: true, onResponsiveOrientationChanged: (event) => {
                 setPhysicalOrientation(event.orientation);
             }, children: _jsxs(View, { style: styles.overlay, children: [overlay?.title && (_jsx(View, { style: [styles.topBar, isLandscape && styles.topBarLandscape], children: _jsx(Text, { style: [

package/lib/types/index.d.ts

@@ -57,6 +57,8 @@ export interface VerificationListParams {
 export interface VerifyOptions {
     /** Idempotency key to prevent duplicate verifications on retry. */
     idempotencyKey?: string;
+    /** Optional primitive metadata attached to client-side request telemetry. */
+    telemetryMetadata?: Record<string, string | number | boolean | null | undefined>;
 }
 export interface QueueItem {
     id: string;

package/lib/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "2.5.1";
+export declare const SDK_VERSION = "2.5.2";

package/lib/version.js

@@ -1 +1 @@
-export const SDK_VERSION = '2.5.1';
+export const SDK_VERSION = '2.5.2';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchlabs/verify-ai-react-native",
-  "version": "2.5.1",
+  "version": "2.5.3",
   "description": "React Native SDK for Verify AI - photo verification with AI vision processing",
   "repository": {
     "type": "git",

package/src/client/index.ts

@@ -78,6 +78,65 @@ interface RequestContext {
   method: string;
 }
 
+type ClientTelemetryValue = string | number | boolean | null | undefined;
+type ClientTelemetryMetadata = Record<string, ClientTelemetryValue>;
+
+const VERIFY_METADATA_TELEMETRY_KEYS = [
+  'rideId',
+  'vehicleType',
+  'verificationAttemptId',
+  'verificationAttempt',
+  'verificationMaxAttempts',
+  'verificationSource',
+  'torchEnabled',
+  'scannerSessionId',
+];
+
+function toTelemetryKey(key: string): string {
+  return key
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/[^a-zA-Z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .toLowerCase();
+}
+
+function compactClientTelemetryMetadata(
+  metadata: ClientTelemetryMetadata = {},
+): Record<string, string | number> {
+  const compacted: Record<string, string | number> = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (value === null || value === undefined) continue;
+    compacted[key] = typeof value === 'boolean' ? (value ? 1 : 0) : value;
+  }
+  return compacted;
+}
+
+function buildVerifyTelemetryMetadata(
+  requestMetadata: Record<string, unknown> | undefined,
+  options?: VerifyOptions,
+): ClientTelemetryMetadata {
+  const metadata: ClientTelemetryMetadata = {
+    ...options?.telemetryMetadata,
+  };
+
+  if (options?.idempotencyKey) {
+    metadata.idempotency_key = options.idempotencyKey;
+  }
+
+  for (const key of VERIFY_METADATA_TELEMETRY_KEYS) {
+    const value = requestMetadata?.[key];
+    if (
+      typeof value === 'string' ||
+      typeof value === 'number' ||
+      typeof value === 'boolean'
+    ) {
+      metadata[`verify_metadata_${toTelemetryKey(key)}`] = value;
+    }
+  }
+
+  return metadata;
+}
+
 export class VerifyAIClient {
   private apiKey: string;
   private baseUrl: string;
@@ -147,7 +206,8 @@ export class VerifyAIClient {
 
   private async executeRequest<T>(
     path: string,
-    options: RequestInit = {}
+    options: RequestInit = {},
+    telemetryMetadata: ClientTelemetryMetadata = {},
   ): Promise<T> {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeout);
@@ -218,6 +278,7 @@ export class VerifyAIClient {
           ? `${normalized.message} [${context.method} ${context.path}; timeout=${this.timeout}ms]`
           : normalized;
         const metadata: Record<string, string | number> = {
+          ...compactClientTelemetryMetadata(telemetryMetadata),
           method: context.method,
           path: context.path,
           status: normalized.status,
@@ -243,9 +304,10 @@ export class VerifyAIClient {
 
   private async request<T>(
     path: string,
-    options: RequestInit = {}
+    options: RequestInit = {},
+    telemetryMetadata: ClientTelemetryMetadata = {},
   ): Promise<T> {
-    return this.executeRequest<T>(path, options);
+    return this.executeRequest<T>(path, options, telemetryMetadata);
   }
 
   /**
@@ -276,11 +338,12 @@ export class VerifyAIClient {
       headers['Idempotency-Key'] = options.idempotencyKey;
     }
     const enrichedRequest = { ...request, metadata: enrichMetadata(request.metadata) };
+    const telemetryMetadata = buildVerifyTelemetryMetadata(enrichedRequest.metadata, options);
     return this.request<VerificationResult>('/verify', {
       method: 'POST',
       headers,
       body: JSON.stringify(enrichedRequest),
-    });
+    }, telemetryMetadata);
   }
 
   /**
@@ -300,7 +363,8 @@ export class VerifyAIClient {
       name: 'photo.jpg',
     } as unknown as Blob);
     formData.append('policy', request.policy);
-    formData.append('metadata', JSON.stringify(enrichMetadata(request.metadata)));
+    const enrichedMetadata = enrichMetadata(request.metadata);
+    formData.append('metadata', JSON.stringify(enrichedMetadata));
     if (request.provider) {
       formData.append('provider', request.provider);
     }
@@ -316,12 +380,14 @@ export class VerifyAIClient {
       headers['Idempotency-Key'] = options.idempotencyKey;
     }
 
+    const telemetryMetadata = buildVerifyTelemetryMetadata(enrichedMetadata, options);
+
     try {
       return await this.executeRequest<VerificationResult>('/verify', {
         method: 'POST',
         headers,
         body: formData,
-      });
+      }, telemetryMetadata);
     } catch (error) {
       // 5xx during multipart can mean the server crashed before reservation
       // (e.g. Vercel multipart-parse failure) OR after the verification was
@@ -342,7 +408,7 @@ export class VerifyAIClient {
               provider: request.provider,
               include_image_data: request.include_image_data,
             },
-            options?.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : undefined,
+            options,
           );
         } catch {
           // If the retry itself fails, throw the original error

package/src/components/VerifyAIScanner.tsx

@@ -45,12 +45,21 @@ const CAMERA_INIT_ERROR_CODE = 'ERR_CAMERA_INIT_FAILED';
 const DEFAULT_TERMINAL_RESULT_DISPLAY_MS = 3000;
 const TRANSIENT_ERROR_DISPLAY_MS = 3000;
 const CAMERA_CAPTURE_RETRY_DELAY_MS = 350;
+const CAMERA_CAPTURE_RETRY_TORCH_SETTLE_MS = 800;
 const IOS_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS = 3000;
 const ANDROID_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS = 10000;
-const IOS_CAMERA_STARTUP_WATCHDOG_MS = 8000;
+// iOS AVCaptureSession cold start can legitimately exceed 8s on first launch (permission
+// prompt, first-ever session spin-up, thermal/low-power throttling). An 8s watchdog tore
+// down sessions that were seconds from ready and restarted from scratch, which made slow
+// cold starts *worse* and fired camera_preview_timeout in bursts. Match Android at 10s.
+const IOS_CAMERA_STARTUP_WATCHDOG_MS = 10000;
 const ANDROID_CAMERA_STARTUP_WATCHDOG_MS = 10000;
 const CAMERA_STARTUP_SLOW_TELEMETRY_MS = 3000;
+// Base backoff between startup remounts. Each successive remount escalates this (see
+// startupRemountBackoffMs below) so later attempts get progressively more uninterrupted
+// time to initialize the native session instead of thrashing at a fixed interval.
 const CAMERA_STARTUP_REMOUNT_BACKOFF_MS = 350;
+const CAMERA_STARTUP_REMOUNT_BACKOFF_MAX_MS = 1200;
 const CAMERA_STARTUP_WATCHDOG_MAX_REMOUNTS = 5;
 const ANDROID_ORIENTATION_NO_EVENT_TIMEOUT_MS = 3000;
 const ANDROID_ORIENTATION_SAMPLE_TELEMETRY_MS = 3000;
@@ -153,6 +162,10 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function createScannerSessionId(): string {
+  return `scan_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
 function isNativeCameraCaptureError(error: ErrorWithDetails): boolean {
   const message = error.message.toLowerCase();
   return (
@@ -369,10 +382,15 @@ export function VerifyAIScanner({
 
   physicalOrientationRef.current = physicalOrientation;
   const overlayRotationDeg = getOverlayRotationDeg(physicalOrientation);
+  const scannerSessionIdRef = useRef(createScannerSessionId());
+  const captureSequenceRef = useRef(0);
+  const torchRetrySuppressedRef = useRef(false);
+  const [torchRetrySuppressed, setTorchRetrySuppressed] = useState(false);
 
   const buildScannerTelemetryMetadata = useCallback((
     extra: Record<string, string | number | boolean | null | undefined> = {},
   ): ScannerTelemetryMetadata => compactTelemetryMetadata({
+    scanner_session_id: scannerSessionIdRef.current,
     policy,
     status,
     camera_ready: cameraReadyRef.current,
@@ -401,6 +419,7 @@ export function VerifyAIScanner({
     last_orientation_remount_at: lastOrientationRemountAtRef.current,
     last_capture_retry_at: lastCaptureRetryAtRef.current,
     requested_torch_enabled: enableTorch ? 1 : 0,
+    torch_retry_suppressed: torchRetrySuppressedRef.current,
     android_native_orientation_subscription_active: 0,
     android_native_orientation_event_count: 0,
     android_native_orientation_change_count: 0,
@@ -455,6 +474,11 @@ export function VerifyAIScanner({
   telemetryRef.current = telemetry;
   buildScannerTelemetryMetadataRef.current = buildScannerTelemetryMetadata;
 
+  const setTorchSuppressedForRetry = useCallback((nextSuppressed: boolean) => {
+    torchRetrySuppressedRef.current = nextSuppressed;
+    setTorchRetrySuppressed(nextSuppressed);
+  }, []);
+
   useEffect(() => {
     const reporter = telemetryRef.current;
     if (reporter) {
@@ -509,7 +533,8 @@ export function VerifyAIScanner({
     if (opts.log) {
       console.warn(
         `VerifyAI[${SDK_VERSION}]: remounting camera reason=${reason} ` +
-          `backoffMs=${opts.backoffMs ?? 0} torchRequested=${enableTorch ? 1 : 0}`,
+          `backoffMs=${opts.backoffMs ?? 0} torchRequested=${enableTorch ? 1 : 0} ` +
+          `torchRetrySuppressed=${torchRetrySuppressedRef.current ? 1 : 0}`,
       );
     }
 
@@ -1025,6 +1050,12 @@ export function VerifyAIScanner({
           const startupWatchdogRemountCount = startupWatchdogRemountCountRef.current + 1;
           startupWatchdogRemountCountRef.current = startupWatchdogRemountCount;
           cameraRemountCountRef.current++;
+          // Escalate the backoff with each attempt (350, 700, 1050, capped at 1200ms) so a
+          // camera that just needs more time isn't repeatedly interrupted at a fixed cadence.
+          const startupRemountBackoffMs = Math.min(
+            CAMERA_STARTUP_REMOUNT_BACKOFF_MS * startupWatchdogRemountCount,
+            CAMERA_STARTUP_REMOUNT_BACKOFF_MAX_MS,
+          );
           telemetry?.track('camera_preview_timeout', {
             component: 'scanner',
             error: `Camera did not initialize within ${Math.round(watchdogMs / 1000)} seconds — remounting`,
@@ -1033,12 +1064,12 @@ export function VerifyAIScanner({
               remount_reason: 'startup_watchdog',
               startup_watchdog_remount_count: startupWatchdogRemountCount,
               startup_watchdog_max_remounts: CAMERA_STARTUP_WATCHDOG_MAX_REMOUNTS,
-              startup_remount_backoff_ms: CAMERA_STARTUP_REMOUNT_BACKOFF_MS,
+              startup_remount_backoff_ms: startupRemountBackoffMs,
               torch_deferred_until_ready: enableTorch ? 1 : 0,
             }),
           });
           requestCameraRemount('startup_watchdog', {
-            backoffMs: CAMERA_STARTUP_REMOUNT_BACKOFF_MS,
+            backoffMs: startupRemountBackoffMs,
             log: true,
           });
         }
@@ -1076,6 +1107,9 @@ export function VerifyAIScanner({
   }, [buildScannerTelemetryMetadata, permission, telemetry]);
 
   const handleCapture = useCallback(async () => {
+    const captureSequence = captureSequenceRef.current + 1;
+    captureSequenceRef.current = captureSequence;
+    const captureAttemptId = `${scannerSessionIdRef.current}_cap_${captureSequence}`;
     const blockedReason =
       !cameraRef.current
         ? 'camera_ref_null'
@@ -1095,6 +1129,8 @@ export function VerifyAIScanner({
       component: 'scanner',
       error: blockedReason == null ? 'capture_requested' : 'capture_ignored',
       metadata: buildScannerTelemetryMetadata({
+        capture_attempt_id: captureAttemptId,
+        capture_sequence: captureSequence,
         capture_blocked_reason: blockedReason,
       }),
     });
@@ -1120,6 +1156,7 @@ export function VerifyAIScanner({
     }
 
     setStatus('capturing');
+    setTorchSuppressedForRetry(false);
     setResult(null);
     setLastError(null);
     terminalResultRef.current = null;
@@ -1132,6 +1169,9 @@ export function VerifyAIScanner({
     let nativeCaptureAttempts = 0;
     let captureRetryAttempted = false;
     let captureRetryReady = false;
+    let captureRetryTorchSuppressed = false;
+    let captureRetrySettleDelayMs = CAMERA_CAPTURE_RETRY_DELAY_MS;
+    let captureRetryRemountBackoffMs = 0;
     let lastNativeCaptureErrorMessage: string | null = null;
 
     try {
@@ -1141,6 +1181,8 @@ export function VerifyAIScanner({
         component: 'scanner',
         error: 'capture_orientation_context',
         metadata: buildScannerTelemetryMetadata({
+          capture_attempt_id: captureAttemptId,
+          capture_sequence: captureSequence,
           capture_physical_orientation: capturePhysicalOrientation,
           capture_overlay_rotation_deg: captureOverlayRotationDeg,
           capture_rotation_applied: 0,
@@ -1209,11 +1251,26 @@ export function VerifyAIScanner({
 
             if (attempt === 1 && isNativeCameraCaptureError(normalized) && !terminated) {
               captureRetryAttempted = true;
+              captureRetryTorchSuppressed = !!enableTorch;
+              captureRetrySettleDelayMs = captureRetryTorchSuppressed
+                ? CAMERA_CAPTURE_RETRY_TORCH_SETTLE_MS
+                : CAMERA_CAPTURE_RETRY_DELAY_MS;
+              captureRetryRemountBackoffMs = captureRetryTorchSuppressed
+                ? CAMERA_CAPTURE_RETRY_DELAY_MS
+                : 0;
               const retryAt = new Date().toISOString();
               lastCaptureRetryAtRef.current = retryAt;
               cameraRemountCountRef.current++;
-              requestCameraRemount('capture_retry');
-              await sleep(CAMERA_CAPTURE_RETRY_DELAY_MS);
+              if (captureRetryTorchSuppressed) {
+                setTorchSuppressedForRetry(true);
+              }
+              requestCameraRemount(
+                'capture_retry',
+                captureRetryRemountBackoffMs > 0
+                  ? { backoffMs: captureRetryRemountBackoffMs }
+                  : undefined,
+              );
+              await sleep(captureRetrySettleDelayMs);
               const captureRetryReadyTimeoutMs = Platform.OS === 'android'
                 ? ANDROID_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS
                 : IOS_CAMERA_CAPTURE_RETRY_READY_TIMEOUT_MS;
@@ -1223,11 +1280,16 @@ export function VerifyAIScanner({
                 error: normalized,
                 errorCode: normalized.code,
                 metadata: buildScannerTelemetryMetadata({
+                  capture_attempt_id: captureAttemptId,
+                  capture_sequence: captureSequence,
                   native_capture_attempts: nativeCaptureAttempts,
                   capture_retry_attempted: captureRetryAttempted,
                   capture_retry_ready: captureRetryReady,
                   capture_retry_delay_ms: CAMERA_CAPTURE_RETRY_DELAY_MS,
+                  capture_retry_settle_delay_ms: captureRetrySettleDelayMs,
+                  capture_retry_remount_backoff_ms: captureRetryRemountBackoffMs,
                   capture_retry_ready_timeout_ms: captureRetryReadyTimeoutMs,
+                  capture_retry_torch_suppressed: captureRetryTorchSuppressed,
                   last_native_capture_error: lastNativeCaptureErrorMessage,
                 }),
               });
@@ -1321,6 +1383,8 @@ export function VerifyAIScanner({
       telemetry?.track('image_processed', {
         component: 'scanner',
         metadata: buildScannerTelemetryMetadata({
+          capture_attempt_id: captureAttemptId,
+          capture_sequence: captureSequence,
           original_width: origWidth,
           original_height: origHeight,
           processed_width: processedWidth,
@@ -1330,6 +1394,9 @@ export function VerifyAIScanner({
           native_capture_attempts: nativeCaptureAttempts,
           capture_retry_attempted: captureRetryAttempted,
           capture_retry_ready: captureRetryReady,
+          capture_retry_torch_suppressed: captureRetryTorchSuppressed,
+          capture_retry_settle_delay_ms: captureRetrySettleDelayMs,
+          capture_retry_remount_backoff_ms: captureRetryRemountBackoffMs,
           recovered_native_capture_failure: captureRetryAttempted ? 1 : 0,
           last_native_capture_error: lastNativeCaptureErrorMessage,
         }),
@@ -1404,9 +1471,14 @@ export function VerifyAIScanner({
             component: 'scanner',
             error,
             metadata: buildScannerTelemetryMetadata({
+              capture_attempt_id: captureAttemptId,
+              capture_sequence: captureSequence,
               native_capture_attempts: nativeCaptureAttempts,
               capture_retry_attempted: captureRetryAttempted,
               capture_retry_ready: captureRetryReady,
+              capture_retry_torch_suppressed: captureRetryTorchSuppressed,
+              capture_retry_settle_delay_ms: captureRetrySettleDelayMs,
+              capture_retry_remount_backoff_ms: captureRetryRemountBackoffMs,
               is_native_camera_capture_error: isNativeCameraCaptureError(error),
               last_native_capture_error: lastNativeCaptureErrorMessage,
             }),
@@ -1417,8 +1489,10 @@ export function VerifyAIScanner({
       if (!terminalRequestError) {
         setTimeout(() => setStatus('idle'), TRANSIENT_ERROR_DISPLAY_MS);
       }
+    } finally {
+      setTorchSuppressedForRetry(false);
     }
-  }, [status, exhausted, onCapture, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust, releaseCamera, scheduleTerminalResult, buildScannerTelemetryMetadata, requestCameraRemount, telemetry, terminated, physicalOrientation, overlayRotationDeg]);
+  }, [status, exhausted, onCapture, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust, releaseCamera, scheduleTerminalResult, buildScannerTelemetryMetadata, requestCameraRemount, telemetry, terminated, physicalOrientation, overlayRotationDeg, enableTorch, setTorchSuppressedForRetry]);
 
   // Expose capture to parent via ref
   if (captureRef) {
@@ -1441,7 +1515,7 @@ export function VerifyAIScanner({
   }
 
   const showBottomCard = status === 'success' || status === 'error';
-  const shouldEnableTorch = !terminated && cameraReady && !!enableTorch;
+  const shouldEnableTorch = !terminated && cameraReady && !!enableTorch && !torchRetrySuppressed;
 
   return (
     <View style={[styles.container, style]}>

package/src/types/index.ts

@@ -64,6 +64,8 @@ export interface VerificationListParams {
 export interface VerifyOptions {
   /** Idempotency key to prevent duplicate verifications on retry. */
   idempotencyKey?: string;
+  /** Optional primitive metadata attached to client-side request telemetry. */
+  telemetryMetadata?: Record<string, string | number | boolean | null | undefined>;
 }
 
 export interface QueueItem {

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = '2.5.1';
+export const SDK_VERSION = '2.5.2';