@switchlabs/verify-ai-react-native 2.4.15 → 2.4.17

package/lib/components/VerifyAIScanner.d.ts

@@ -1,6 +1,6 @@
 import React from 'react';
 import { type ViewStyle } from 'react-native';
-import type { VerificationResult, ScannerOverlayConfig } from '../types';
+import type { VerificationResult, ScannerOverlayConfig, ScannerTelemetryContext } from '../types';
 import type { TelemetryReporter } from '../telemetry/TelemetryReporter';
 export interface VerifyAIScannerProps {
     /** Called with base64 image data when the user captures a photo. */
@@ -27,6 +27,8 @@ export interface VerifyAIScannerProps {
     enableTorch?: boolean;
     /** Optional telemetry reporter (falls back to TelemetryContext). */
     telemetry?: TelemetryReporter | null;
+    /** Optional host-app context attached to scanner telemetry. */
+    telemetryContext?: ScannerTelemetryContext;
 }
 /**
  * Camera scanner component for capturing verification photos.
@@ -49,4 +51,4 @@ export interface VerifyAIScannerProps {
  * />
  * ```
  */
-export declare function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose, overlay: overlayProp, style, showCaptureButton, showCloseButton, captureRef, enableTorch, telemetry: telemetryProp, }: VerifyAIScannerProps): import("react/jsx-runtime").JSX.Element;
+export declare function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose, overlay: overlayProp, style, showCaptureButton, showCloseButton, captureRef, enableTorch, telemetry: telemetryProp, telemetryContext, }: VerifyAIScannerProps): import("react/jsx-runtime").JSX.Element;

package/lib/components/VerifyAIScanner.js

@@ -19,6 +19,8 @@ const TRANSIENT_ERROR_DISPLAY_MS = 3000;
 const CAMERA_CAPTURE_RETRY_DELAY_MS = 350;
 const IOS_CAMERA_STARTUP_WATCHDOG_MS = 3000;
 const ANDROID_CAMERA_STARTUP_WATCHDOG_MS = 5000;
+const ANDROID_ORIENTATION_NO_EVENT_TIMEOUT_MS = 3000;
+const ANDROID_ORIENTATION_SAMPLE_TELEMETRY_MS = 3000;
 function getPolicyScannerDefaults(policy) {
     const id = policy?.toLowerCase() ?? '';
     const isForest = id.includes('forest') || id.includes('humanforest');
@@ -90,6 +92,15 @@ function compactTelemetryMetadata(metadata) {
     }
     return compacted;
 }
+function getPlatformConstantString(...keys) {
+    const constants = Platform.constants;
+    for (const key of keys) {
+        const value = constants[key];
+        if (typeof value === 'string' && value.trim())
+            return value;
+    }
+    return null;
+}
 function getErrorDisplay(error, showTechnicalDetails) {
     if (!error) {
         return {
@@ -171,7 +182,7 @@ function isTerminalRequestError(error) {
  * />
  * ```
  */
-export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose, overlay: overlayProp, style, showCaptureButton = true, showCloseButton = false, captureRef, enableTorch, telemetry: telemetryProp, }) {
+export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose, overlay: overlayProp, style, showCaptureButton = true, showCloseButton = false, captureRef, enableTorch, telemetry: telemetryProp, telemetryContext, }) {
     const contextTelemetry = useTelemetry();
     const telemetry = telemetryProp ?? contextTelemetry;
     const overlay = useMemo(() => applyPolicyDefaults(overlayProp, policy), [overlayProp, policy]);
@@ -197,6 +208,19 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
     const lastOrientationRemountAtRef = useRef(null);
     const lastCaptureRetryAtRef = useRef(null);
     const cameraRemountCountRef = useRef(0);
+    const androidOrientationSubscriptionActiveRef = useRef(false);
+    const androidOrientationEventCountRef = useRef(0);
+    const androidOrientationChangeCountRef = useRef(0);
+    const androidOrientationStartedAtRef = useRef(null);
+    const lastAndroidOrientationEventAtRef = useRef(null);
+    const lastAndroidOrientationTelemetryAtRef = useRef(0);
+    const lastAndroidOrientationXRef = useRef(null);
+    const lastAndroidOrientationYRef = useRef(null);
+    const lastAndroidOrientationZRef = useRef(null);
+    const lastAndroidOrientationDerivedRef = useRef(null);
+    const lastAndroidOrientationIgnoredReasonRef = useRef(null);
+    const lastAndroidOrientationErrorAtRef = useRef(null);
+    const lastAndroidOrientationErrorRef = useRef(null);
     // Track dimensions for orientation detection and responsive layout
     const { width: windowWidth, height: windowHeight } = useWindowDimensions();
     const isLandscape = windowWidth > windowHeight;
@@ -207,47 +231,6 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
     // uses the accelerometer via expo-sensors (the callback is iOS-only). Either
     // way we rotate the overlay UI to stay readable from the user's viewpoint.
     const [physicalOrientation, setPhysicalOrientation] = useState('portrait');
-    useEffect(() => {
-        if (Platform.OS !== 'android')
-            return;
-        let subscription = null;
-        let cancelled = false;
-        let lastOrientation = 'portrait';
-        (async () => {
-            let Accelerometer = null;
-            try {
-                // eslint-disable-next-line @typescript-eslint/no-require-imports
-                const mod = require('expo-sensors');
-                Accelerometer = mod?.Accelerometer ?? null;
-            }
-            catch {
-                return;
-            }
-            if (cancelled || !Accelerometer)
-                return;
-            Accelerometer.setUpdateInterval(500);
-            subscription = Accelerometer.addListener(({ x, y }) => {
-                let next;
-                if (Math.abs(x) > Math.abs(y) + 0.2) {
-                    next = x > 0 ? 'landscapeRight' : 'landscapeLeft';
-                }
-                else if (Math.abs(y) > Math.abs(x) + 0.2) {
-                    next = y > 0 ? 'portraitUpsideDown' : 'portrait';
-                }
-                else {
-                    return; // ambiguous tilt — ignore
-                }
-                if (next !== lastOrientation) {
-                    lastOrientation = next;
-                    setPhysicalOrientation(next);
-                }
-            });
-        })();
-        return () => {
-            cancelled = true;
-            subscription?.remove();
-        };
-    }, []);
     const overlayRotationDeg = (() => {
         switch (physicalOrientation) {
             case 'landscapeLeft':
@@ -273,6 +256,10 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         exhausted,
         app_state: AppState.currentState,
         sdk_platform: Platform.OS,
+        device_model: getPlatformConstantString('Model', 'model'),
+        device_os_version: String(Platform.Version),
+        route_name: telemetryContext?.routeName,
+        is_portrait_locked: telemetryContext?.isPortraitLocked,
         window_width: windowWidth,
         window_height: windowHeight,
         interface_orientation: isLandscape ? 'landscape' : 'portrait',
@@ -282,6 +269,18 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         last_appstate_remount_at: lastAppStateRemountAtRef.current,
         last_orientation_remount_at: lastOrientationRemountAtRef.current,
         last_capture_retry_at: lastCaptureRetryAtRef.current,
+        android_orientation_subscription_active: androidOrientationSubscriptionActiveRef.current,
+        android_orientation_started_at: androidOrientationStartedAtRef.current,
+        android_orientation_event_count: androidOrientationEventCountRef.current,
+        android_orientation_change_count: androidOrientationChangeCountRef.current,
+        last_android_orientation_event_at: lastAndroidOrientationEventAtRef.current,
+        last_android_orientation_x: lastAndroidOrientationXRef.current,
+        last_android_orientation_y: lastAndroidOrientationYRef.current,
+        last_android_orientation_z: lastAndroidOrientationZRef.current,
+        last_android_orientation_derived_orientation: lastAndroidOrientationDerivedRef.current,
+        last_android_orientation_ignored_reason: lastAndroidOrientationIgnoredReasonRef.current,
+        last_android_orientation_error_at: lastAndroidOrientationErrorAtRef.current,
+        last_android_orientation_error: lastAndroidOrientationErrorRef.current,
         ...extra,
     }), [
         cameraKey,
@@ -291,10 +290,146 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         physicalOrientation,
         policy,
         status,
+        telemetryContext?.isPortraitLocked,
+        telemetryContext?.routeName,
         terminated,
         windowHeight,
         windowWidth,
     ]);
+    useEffect(() => {
+        if (Platform.OS !== 'android')
+            return;
+        let subscription = null;
+        let cancelled = false;
+        let noEventTimer = null;
+        let lastOrientation = 'portrait';
+        const androidMetadata = (extra = {}) => compactTelemetryMetadata({
+            policy,
+            sdk_platform: Platform.OS,
+            device_model: getPlatformConstantString('Model', 'model'),
+            device_os_version: String(Platform.Version),
+            route_name: telemetryContext?.routeName,
+            is_portrait_locked: telemetryContext?.isPortraitLocked,
+            android_orientation_subscription_active: androidOrientationSubscriptionActiveRef.current,
+            android_orientation_started_at: androidOrientationStartedAtRef.current,
+            android_orientation_event_count: androidOrientationEventCountRef.current,
+            android_orientation_change_count: androidOrientationChangeCountRef.current,
+            last_android_orientation_event_at: lastAndroidOrientationEventAtRef.current,
+            last_android_orientation_x: lastAndroidOrientationXRef.current,
+            last_android_orientation_y: lastAndroidOrientationYRef.current,
+            last_android_orientation_z: lastAndroidOrientationZRef.current,
+            last_android_orientation_derived_orientation: lastAndroidOrientationDerivedRef.current,
+            last_android_orientation_ignored_reason: lastAndroidOrientationIgnoredReasonRef.current,
+            last_android_orientation_error_at: lastAndroidOrientationErrorAtRef.current,
+            last_android_orientation_error: lastAndroidOrientationErrorRef.current,
+            ...extra,
+        });
+        const trackAndroidOrientationEvent = (eventType, error, metadata = {}) => {
+            telemetry?.track(eventType, {
+                component: 'scanner',
+                error,
+                metadata: androidMetadata(metadata),
+            });
+        };
+        (async () => {
+            let Accelerometer = null;
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports
+                const mod = require('expo-sensors');
+                Accelerometer = mod?.Accelerometer ?? null;
+            }
+            catch (err) {
+                const error = normalizeScannerError(err);
+                const message = error.message || '';
+                const isMissingModule = error.code === 'MODULE_NOT_FOUND' ||
+                    /cannot find module/i.test(message) ||
+                    /unable to resolve module/i.test(message) ||
+                    /requireNativeModule/i.test(message);
+                if (isMissingModule) {
+                    // expo-sensors is an optional peer dep. Host apps that don't bundle it
+                    // simply lose Android orientation tracking — that's expected, not a failure.
+                    return;
+                }
+                lastAndroidOrientationErrorAtRef.current = new Date().toISOString();
+                lastAndroidOrientationErrorRef.current = error.message;
+                trackAndroidOrientationEvent('camera_android_accelerometer_start_failure', error);
+                return;
+            }
+            if (cancelled)
+                return;
+            if (!Accelerometer) {
+                // Module loaded but no Accelerometer export — same expected-absence case.
+                return;
+            }
+            const startedAt = new Date().toISOString();
+            androidOrientationStartedAtRef.current = startedAt;
+            androidOrientationSubscriptionActiveRef.current = true;
+            androidOrientationEventCountRef.current = 0;
+            androidOrientationChangeCountRef.current = 0;
+            lastAndroidOrientationTelemetryAtRef.current = 0;
+            trackAndroidOrientationEvent('camera_android_accelerometer_started', 'android_accelerometer_orientation_tracking_started', {
+                accelerometer_update_interval_ms: 500,
+                accelerometer_no_event_timeout_ms: ANDROID_ORIENTATION_NO_EVENT_TIMEOUT_MS,
+            });
+            noEventTimer = setTimeout(() => {
+                if (cancelled || androidOrientationEventCountRef.current > 0)
+                    return;
+                trackAndroidOrientationEvent('camera_android_accelerometer_no_events', `No Android accelerometer events within ${ANDROID_ORIENTATION_NO_EVENT_TIMEOUT_MS}ms`);
+            }, ANDROID_ORIENTATION_NO_EVENT_TIMEOUT_MS);
+            Accelerometer.setUpdateInterval(500);
+            subscription = Accelerometer.addListener(({ x, y, z }) => {
+                const at = new Date();
+                const atIso = at.toISOString();
+                androidOrientationEventCountRef.current++;
+                lastAndroidOrientationEventAtRef.current = atIso;
+                lastAndroidOrientationXRef.current = Number(x.toFixed(4));
+                lastAndroidOrientationYRef.current = Number(y.toFixed(4));
+                lastAndroidOrientationZRef.current = Number(z.toFixed(4));
+                if (noEventTimer) {
+                    clearTimeout(noEventTimer);
+                    noEventTimer = null;
+                }
+                let next = null;
+                let ignoredReason = null;
+                if (Math.abs(x) > Math.abs(y) + 0.2) {
+                    next = x > 0 ? 'landscapeRight' : 'landscapeLeft';
+                }
+                else if (Math.abs(y) > Math.abs(x) + 0.2) {
+                    next = y > 0 ? 'portraitUpsideDown' : 'portrait';
+                }
+                else {
+                    ignoredReason = 'ambiguous_tilt';
+                }
+                lastAndroidOrientationDerivedRef.current = next;
+                lastAndroidOrientationIgnoredReasonRef.current = ignoredReason;
+                if (next && next !== lastOrientation) {
+                    const previous = lastOrientation;
+                    lastOrientation = next;
+                    androidOrientationChangeCountRef.current++;
+                    setPhysicalOrientation(next);
+                    trackAndroidOrientationEvent('camera_android_physical_orientation_changed', `${previous} -> ${next}`, {
+                        previous_physical_orientation: previous,
+                        next_physical_orientation: next,
+                        accelerometer_sampled_at: atIso,
+                    });
+                    return;
+                }
+                const shouldTrackSample = androidOrientationEventCountRef.current === 1 ||
+                    at.getTime() - lastAndroidOrientationTelemetryAtRef.current >= ANDROID_ORIENTATION_SAMPLE_TELEMETRY_MS;
+                if (shouldTrackSample) {
+                    lastAndroidOrientationTelemetryAtRef.current = at.getTime();
+                    trackAndroidOrientationEvent('camera_android_accelerometer_sample', `accelerometer_sample_${androidOrientationEventCountRef.current}`, { accelerometer_sampled_at: atIso });
+                }
+            });
+        })();
+        return () => {
+            cancelled = true;
+            androidOrientationSubscriptionActiveRef.current = false;
+            if (noEventTimer)
+                clearTimeout(noEventTimer);
+            subscription?.remove();
+        };
+    }, [policy, telemetry, telemetryContext?.isPortraitLocked, telemetryContext?.routeName]);
     // Detect orientation changes and remount camera after rotation settles.
     // On iOS, AVCaptureVideoPreviewLayer distorts if remounted during the rotation
     // animation — the native preview layer initializes with transitional bounds.
@@ -478,9 +613,29 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         }
     }, [buildScannerTelemetryMetadata, permission, telemetry]);
     const handleCapture = useCallback(async () => {
-        if (!cameraRef.current || status === 'capturing' || status === 'processing' || exhausted)
+        const blockedReason = !cameraRef.current
+            ? 'camera_ref_null'
+            : !cameraReadyRef.current
+                ? 'camera_not_ready'
+                : status === 'capturing'
+                    ? 'already_capturing'
+                    : status === 'processing'
+                        ? 'already_processing'
+                        : terminated
+                            ? 'terminated'
+                            : exhausted
+                                ? 'exhausted'
+                                : null;
+        telemetry?.track('camera_capture_request', {
+            component: 'scanner',
+            error: blockedReason == null ? 'capture_requested' : 'capture_ignored',
+            metadata: buildScannerTelemetryMetadata({
+                capture_blocked_reason: blockedReason,
+            }),
+        });
+        if (blockedReason && blockedReason !== 'camera_not_ready')
             return;
-        if (!cameraReadyRef.current) {
+        if (blockedReason === 'camera_not_ready') {
             const error = createScannerError('Camera is not ready yet. Please wait a moment and try again.', CAMERA_NOT_READY_ERROR_CODE, 'CameraNotReadyError');
             setResult(null);
             setLastError(error);
@@ -508,6 +663,17 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
         let captureRetryReady = false;
         let lastNativeCaptureErrorMessage = null;
         try {
+            const capturePhysicalOrientation = physicalOrientation;
+            const captureOverlayRotationDeg = overlayRotationDeg;
+            telemetry?.track('camera_capture_orientation_context', {
+                component: 'scanner',
+                error: 'capture_orientation_context',
+                metadata: buildScannerTelemetryMetadata({
+                    capture_physical_orientation: capturePhysicalOrientation,
+                    capture_overlay_rotation_deg: captureOverlayRotationDeg,
+                    capture_rotation_applied: 0,
+                }),
+            });
             // --- Capture + best-effort resize ---
             // Strategy: try to dynamically import expo-image-manipulator.
             //   If available → resize to MAX_DIMENSION, EXIF-normalize, return base64.
@@ -561,6 +727,19 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                             setCameraKey((key) => key + 1);
                             await sleep(CAMERA_CAPTURE_RETRY_DELAY_MS);
                             captureRetryReady = await waitForCameraReady(2500);
+                            telemetry?.track('camera_capture_retry', {
+                                component: 'scanner',
+                                error: normalized,
+                                errorCode: normalized.code,
+                                metadata: buildScannerTelemetryMetadata({
+                                    native_capture_attempts: nativeCaptureAttempts,
+                                    capture_retry_attempted: captureRetryAttempted,
+                                    capture_retry_ready: captureRetryReady,
+                                    capture_retry_delay_ms: CAMERA_CAPTURE_RETRY_DELAY_MS,
+                                    capture_retry_ready_timeout_ms: 2500,
+                                    last_native_capture_error: lastNativeCaptureErrorMessage,
+                                }),
+                            });
                             if (captureRetryReady) {
                                 continue;
                             }
@@ -714,7 +893,7 @@ 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, telemetry, terminated]);
+    }, [status, exhausted, onCapture, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust, releaseCamera, scheduleTerminalResult, buildScannerTelemetryMetadata, telemetry, terminated, physicalOrientation, overlayRotationDeg]);
     // Expose capture to parent via ref
     if (captureRef) {
         captureRef.current = handleCapture;
@@ -730,6 +909,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                 setPhysicalOrientation(event.orientation);
             }, children: _jsxs(View, { style: styles.overlay, children: [overlay?.title && (_jsx(View, { style: [styles.topBar, isLandscape && styles.topBarLandscape], children: _jsx(Text, { style: [
                                 styles.titleText,
+                                overlay.theme?.titleStyle,
                                 { transform: [{ rotate: `${overlayRotationDeg}deg` }] },
                             ], children: overlay.title }) })), overlay?.showGuideFrame && (_jsxs(View, { style: [styles.guideContainer, isLandscape && styles.guideContainerLandscape], children: [_jsxs(View, { style: [
                                     styles.guideFrame,
@@ -739,8 +919,9 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                                         : undefined,
                                 ], children: [overlay.guideOverlayContent && (_jsx(View, { style: [StyleSheet.absoluteFill, { opacity: overlay.guideOverlayOpacity ?? 0.3 }], children: overlay.guideOverlayContent })), _jsx(View, { style: [styles.corner, styles.cornerTopLeft, overlay.theme?.cornerColor ? { borderColor: overlay.theme.cornerColor } : undefined] }), _jsx(View, { style: [styles.corner, styles.cornerTopRight, overlay.theme?.cornerColor ? { borderColor: overlay.theme.cornerColor } : undefined] }), _jsx(View, { style: [styles.corner, styles.cornerBottomLeft, overlay.theme?.cornerColor ? { borderColor: overlay.theme.cornerColor } : undefined] }), _jsx(View, { style: [styles.corner, styles.cornerBottomRight, overlay.theme?.cornerColor ? { borderColor: overlay.theme.cornerColor } : undefined] })] }), overlay.guideCaption && (_jsx(Text, { style: [
                                     styles.guideCaptionText,
+                                    overlay.theme?.feedbackStyle,
                                     { transform: [{ rotate: `${overlayRotationDeg}deg` }] },
-                                ], children: overlay.guideCaption }))] })), status === 'processing' && (_jsxs(View, { style: styles.processingOverlay, children: [_jsx(ActivityIndicator, { size: "large", color: "#fff" }), _jsx(Text, { style: styles.statusText, children: overlay?.processingMessage || 'Analyzing photo...' })] })), showBottomCard && _jsx(View, { style: styles.cardBackdrop }), _jsxs(View, { style: [styles.bottomArea, isLandscape && styles.bottomAreaLandscape], children: [status === 'success' && result && (_jsxs(View, { style: styles.resultCard, children: [_jsxs(View, { style: styles.resultCardHeader, children: [_jsx(View, { style: [
+                                ], children: overlay.guideCaption }))] })), status === 'processing' && (_jsxs(View, { style: styles.processingOverlay, children: [_jsx(ActivityIndicator, { size: "large", color: "#fff" }), _jsx(Text, { style: [styles.statusText, overlay?.theme?.feedbackStyle], children: overlay?.processingMessage || 'Analyzing photo...' })] })), showBottomCard && _jsx(View, { style: styles.cardBackdrop }), _jsxs(View, { style: [styles.bottomArea, isLandscape && styles.bottomAreaLandscape], children: [status === 'success' && result && (_jsxs(View, { style: styles.resultCard, children: [_jsxs(View, { style: styles.resultCardHeader, children: [_jsx(View, { style: [
                                                     styles.resultIconCircle,
                                                     exhausted
                                                         ? styles.resultIconExhausted
@@ -758,7 +939,7 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                                                     ? (overlay?.exhaustedMessage || 'Submitted for review')
                                                     : result.is_compliant
                                                         ? (overlay?.successMessage || 'Verified')
-                                                        : (overlay?.failureMessage || 'Not Verified') })] }), _jsx(Text, { style: styles.feedbackText, children: result.feedback }), overlay?.showTerminalActionButton !== false && onResult && (_jsx(TouchableOpacity, { style: styles.cardButton, onPress: deliverVisibleTerminalResult, children: _jsx(Text, { style: styles.cardButtonText, children: overlay?.terminalActionLabel || 'Continue' }) }))] })), status === 'error' && (() => {
+                                                        : (overlay?.failureMessage || 'Not Verified') })] }), _jsx(Text, { style: [styles.feedbackText, overlay?.theme?.feedbackStyle], children: result.feedback }), overlay?.showTerminalActionButton !== false && onResult && (_jsx(TouchableOpacity, { style: styles.cardButton, onPress: deliverVisibleTerminalResult, children: _jsx(Text, { style: styles.cardButtonText, children: overlay?.terminalActionLabel || 'Continue' }) }))] })), status === 'error' && (() => {
                                 let errorTitle;
                                 let errorMessage;
                                 let showCloseAction = false;
@@ -785,9 +966,10 @@ export function VerifyAIScanner({ onCapture, policy, onResult, onError, onClose,
                                     errorMessage = display.message;
                                     showCloseAction = !!lastError && isTerminalRequestError(lastError) && !!onClose;
                                 }
-                                return (_jsxs(View, { style: styles.resultCard, children: [_jsxs(View, { style: styles.resultCardHeader, children: [_jsx(View, { style: [styles.resultIconCircle, styles.resultIconError, overlay?.theme?.failureColor ? { backgroundColor: overlay.theme.failureColor } : undefined], children: _jsx(Text, { style: styles.resultIcon, children: "!" }) }), _jsx(Text, { style: [styles.resultLabel, styles.resultLabelError, overlay?.theme?.failureColor ? { color: overlay.theme.failureColor } : undefined], children: errorTitle })] }), _jsx(Text, { style: styles.feedbackText, children: errorMessage }), showCloseAction && (_jsx(TouchableOpacity, { style: styles.cardButton, onPress: handleClose, children: _jsx(Text, { style: styles.cardButtonText, children: "Close" }) }))] }));
+                                return (_jsxs(View, { style: styles.resultCard, children: [_jsxs(View, { style: styles.resultCardHeader, children: [_jsx(View, { style: [styles.resultIconCircle, styles.resultIconError, overlay?.theme?.failureColor ? { backgroundColor: overlay.theme.failureColor } : undefined], children: _jsx(Text, { style: styles.resultIcon, children: "!" }) }), _jsx(Text, { style: [styles.resultLabel, styles.resultLabelError, overlay?.theme?.failureColor ? { color: overlay.theme.failureColor } : undefined], children: errorTitle })] }), _jsx(Text, { style: [styles.feedbackText, overlay?.theme?.feedbackStyle], children: errorMessage }), showCloseAction && (_jsx(TouchableOpacity, { style: styles.cardButton, onPress: handleClose, children: _jsx(Text, { style: styles.cardButtonText, children: "Close" }) }))] }));
                             })(), !showBottomCard && (_jsxs(_Fragment, { children: [overlay?.instructions && status === 'idle' && (_jsx(Text, { style: [
                                             styles.instructionsText,
+                                            overlay.theme?.feedbackStyle,
                                             { transform: [{ rotate: `${overlayRotationDeg}deg` }] },
                                         ], children: overlay.instructions })), showCaptureButton && (_jsx(View, { style: styles.captureButtonRow, children: _jsx(TouchableOpacity, { style: [
                                                 styles.captureButton,

package/lib/index.d.ts

@@ -5,4 +5,4 @@ export { TelemetryReporter } from './telemetry/TelemetryReporter';
 export { TelemetryContext } from './telemetry/TelemetryContext';
 export { OfflineQueue } from './storage/offlineQueue';
 export type { BundleManifest, ModelArtifact, FeatureVector, Detection as MLDetection, PolicyAST, PolicyResult, RuleResult, } from './ml/types';
-export type { VerifyAIConfig, VerificationRequest, MultipartVerificationRequest, VerificationResult, VerificationListResponse, VerificationListParams, QueueItem, VerifyAIError, ScannerStatus, ScannerOverlayConfig, ScannerTheme, PolicyConfigResponse, } from './types';
+export type { VerifyAIConfig, VerificationRequest, MultipartVerificationRequest, VerificationResult, VerificationListResponse, VerificationListParams, QueueItem, VerifyAIError, ScannerStatus, ScannerOverlayConfig, ScannerTheme, ScannerTelemetryContext, PolicyConfigResponse, } from './types';

package/lib/types/index.d.ts

@@ -1,4 +1,5 @@
 import type React from 'react';
+import type { TextStyle } from 'react-native';
 export interface VerifyAIConfig {
     apiKey: string;
     baseUrl?: string;
@@ -76,6 +77,13 @@ export interface VerifyAIError {
     method?: string;
 }
 export type ScannerStatus = 'idle' | 'capturing' | 'processing' | 'success' | 'error';
+/** Optional host-app context attached to scanner telemetry. */
+export interface ScannerTelemetryContext {
+    /** Route or screen name from the host app. */
+    routeName?: string;
+    /** Whether the host app keeps this screen portrait-locked. */
+    isPortraitLocked?: boolean;
+}
 /**
  * Theme customization for the scanner overlay.
  *
@@ -92,6 +100,10 @@ export interface ScannerTheme {
     captureButtonColor?: string;
     /** Color for the guide frame corner brackets. Default: 'rgba(255, 255, 255, 0.7)'. */
     cornerColor?: string;
+    /** Text style override for the scanner title. */
+    titleStyle?: TextStyle;
+    /** Text style override for feedback/instruction text. */
+    feedbackStyle?: TextStyle;
 }
 export interface ScannerOverlayConfig {
     title?: string;

package/lib/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "2.4.15";
+export declare const SDK_VERSION = "2.4.17";

package/lib/version.js

@@ -1 +1 @@
-export const SDK_VERSION = '2.4.15';
+export const SDK_VERSION = '2.4.17';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchlabs/verify-ai-react-native",
-  "version": "2.4.15",
+  "version": "2.4.17",
   "description": "React Native SDK for Verify AI - photo verification with AI vision processing",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",

package/src/components/VerifyAIScanner.tsx

@@ -18,6 +18,7 @@ import type {
   VerificationResult,
   ScannerStatus,
   ScannerOverlayConfig,
+  ScannerTelemetryContext,
 } from '../types';
 import { VerifyAIRequestError } from '../client';
 import { useTelemetry } from '../telemetry/TelemetryContext';
@@ -38,6 +39,8 @@ const TRANSIENT_ERROR_DISPLAY_MS = 3000;
 const CAMERA_CAPTURE_RETRY_DELAY_MS = 350;
 const IOS_CAMERA_STARTUP_WATCHDOG_MS = 3000;
 const ANDROID_CAMERA_STARTUP_WATCHDOG_MS = 5000;
+const ANDROID_ORIENTATION_NO_EVENT_TIMEOUT_MS = 3000;
+const ANDROID_ORIENTATION_SAMPLE_TELEMETRY_MS = 3000;
 
 export interface VerifyAIScannerProps {
   /** Called with base64 image data when the user captures a photo. */
@@ -64,6 +67,8 @@ export interface VerifyAIScannerProps {
   enableTorch?: boolean;
   /** Optional telemetry reporter (falls back to TelemetryContext). */
   telemetry?: TelemetryReporter | null;
+  /** Optional host-app context attached to scanner telemetry. */
+  telemetryContext?: ScannerTelemetryContext;
 }
 
 type ErrorWithDetails = Error & {
@@ -165,6 +170,15 @@ function compactTelemetryMetadata(
   return compacted;
 }
 
+function getPlatformConstantString(...keys: string[]): string | null {
+  const constants = Platform.constants as Record<string, unknown>;
+  for (const key of keys) {
+    const value = constants[key];
+    if (typeof value === 'string' && value.trim()) return value;
+  }
+  return null;
+}
+
 function getErrorDisplay(error: ErrorWithDetails | null, showTechnicalDetails?: boolean): { title: string; message: string } {
   if (!error) {
     return {
@@ -261,6 +275,7 @@ export function VerifyAIScanner({
   captureRef,
   enableTorch,
   telemetry: telemetryProp,
+  telemetryContext,
 }: VerifyAIScannerProps) {
   const contextTelemetry = useTelemetry();
   const telemetry = telemetryProp ?? contextTelemetry;
@@ -291,6 +306,19 @@ export function VerifyAIScanner({
   const lastOrientationRemountAtRef = useRef<string | null>(null);
   const lastCaptureRetryAtRef = useRef<string | null>(null);
   const cameraRemountCountRef = useRef(0);
+  const androidOrientationSubscriptionActiveRef = useRef(false);
+  const androidOrientationEventCountRef = useRef(0);
+  const androidOrientationChangeCountRef = useRef(0);
+  const androidOrientationStartedAtRef = useRef<string | null>(null);
+  const lastAndroidOrientationEventAtRef = useRef<string | null>(null);
+  const lastAndroidOrientationTelemetryAtRef = useRef(0);
+  const lastAndroidOrientationXRef = useRef<number | null>(null);
+  const lastAndroidOrientationYRef = useRef<number | null>(null);
+  const lastAndroidOrientationZRef = useRef<number | null>(null);
+  const lastAndroidOrientationDerivedRef = useRef<string | null>(null);
+  const lastAndroidOrientationIgnoredReasonRef = useRef<string | null>(null);
+  const lastAndroidOrientationErrorAtRef = useRef<string | null>(null);
+  const lastAndroidOrientationErrorRef = useRef<string | null>(null);
 
   // Track dimensions for orientation detection and responsive layout
   const { width: windowWidth, height: windowHeight } = useWindowDimensions();
@@ -306,51 +334,6 @@ export function VerifyAIScanner({
     'portrait' | 'portraitUpsideDown' | 'landscapeLeft' | 'landscapeRight'
   >('portrait');
 
-  useEffect(() => {
-    if (Platform.OS !== 'android') return;
-    let subscription: { remove: () => void } | null = null;
-    let cancelled = false;
-    let lastOrientation: typeof physicalOrientation = 'portrait';
-
-    (async () => {
-      let Accelerometer: {
-        setUpdateInterval: (ms: number) => void;
-        addListener: (
-          cb: (data: { x: number; y: number; z: number }) => void,
-        ) => { remove: () => void };
-      } | null = null;
-      try {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const mod = require('expo-sensors');
-        Accelerometer = mod?.Accelerometer ?? null;
-      } catch {
-        return;
-      }
-      if (cancelled || !Accelerometer) return;
-
-      Accelerometer.setUpdateInterval(500);
-      subscription = Accelerometer.addListener(({ x, y }) => {
-        let next: typeof physicalOrientation;
-        if (Math.abs(x) > Math.abs(y) + 0.2) {
-          next = x > 0 ? 'landscapeRight' : 'landscapeLeft';
-        } else if (Math.abs(y) > Math.abs(x) + 0.2) {
-          next = y > 0 ? 'portraitUpsideDown' : 'portrait';
-        } else {
-          return; // ambiguous tilt — ignore
-        }
-        if (next !== lastOrientation) {
-          lastOrientation = next;
-          setPhysicalOrientation(next);
-        }
-      });
-    })();
-
-    return () => {
-      cancelled = true;
-      subscription?.remove();
-    };
-  }, []);
-
   const overlayRotationDeg = (() => {
     switch (physicalOrientation) {
       case 'landscapeLeft':
@@ -379,6 +362,10 @@ export function VerifyAIScanner({
     exhausted,
     app_state: AppState.currentState,
     sdk_platform: Platform.OS,
+    device_model: getPlatformConstantString('Model', 'model'),
+    device_os_version: String(Platform.Version),
+    route_name: telemetryContext?.routeName,
+    is_portrait_locked: telemetryContext?.isPortraitLocked,
     window_width: windowWidth,
     window_height: windowHeight,
     interface_orientation: isLandscape ? 'landscape' : 'portrait',
@@ -388,6 +375,18 @@ export function VerifyAIScanner({
     last_appstate_remount_at: lastAppStateRemountAtRef.current,
     last_orientation_remount_at: lastOrientationRemountAtRef.current,
     last_capture_retry_at: lastCaptureRetryAtRef.current,
+    android_orientation_subscription_active: androidOrientationSubscriptionActiveRef.current,
+    android_orientation_started_at: androidOrientationStartedAtRef.current,
+    android_orientation_event_count: androidOrientationEventCountRef.current,
+    android_orientation_change_count: androidOrientationChangeCountRef.current,
+    last_android_orientation_event_at: lastAndroidOrientationEventAtRef.current,
+    last_android_orientation_x: lastAndroidOrientationXRef.current,
+    last_android_orientation_y: lastAndroidOrientationYRef.current,
+    last_android_orientation_z: lastAndroidOrientationZRef.current,
+    last_android_orientation_derived_orientation: lastAndroidOrientationDerivedRef.current,
+    last_android_orientation_ignored_reason: lastAndroidOrientationIgnoredReasonRef.current,
+    last_android_orientation_error_at: lastAndroidOrientationErrorAtRef.current,
+    last_android_orientation_error: lastAndroidOrientationErrorRef.current,
     ...extra,
   }), [
     cameraKey,
@@ -397,11 +396,173 @@ export function VerifyAIScanner({
     physicalOrientation,
     policy,
     status,
+    telemetryContext?.isPortraitLocked,
+    telemetryContext?.routeName,
     terminated,
     windowHeight,
     windowWidth,
   ]);
 
+  useEffect(() => {
+    if (Platform.OS !== 'android') return;
+
+    let subscription: { remove: () => void } | null = null;
+    let cancelled = false;
+    let noEventTimer: ReturnType<typeof setTimeout> | null = null;
+    let lastOrientation: typeof physicalOrientation = 'portrait';
+
+    const androidMetadata = (
+      extra: Record<string, string | number | boolean | null | undefined> = {},
+    ) => compactTelemetryMetadata({
+      policy,
+      sdk_platform: Platform.OS,
+      device_model: getPlatformConstantString('Model', 'model'),
+      device_os_version: String(Platform.Version),
+      route_name: telemetryContext?.routeName,
+      is_portrait_locked: telemetryContext?.isPortraitLocked,
+      android_orientation_subscription_active: androidOrientationSubscriptionActiveRef.current,
+      android_orientation_started_at: androidOrientationStartedAtRef.current,
+      android_orientation_event_count: androidOrientationEventCountRef.current,
+      android_orientation_change_count: androidOrientationChangeCountRef.current,
+      last_android_orientation_event_at: lastAndroidOrientationEventAtRef.current,
+      last_android_orientation_x: lastAndroidOrientationXRef.current,
+      last_android_orientation_y: lastAndroidOrientationYRef.current,
+      last_android_orientation_z: lastAndroidOrientationZRef.current,
+      last_android_orientation_derived_orientation: lastAndroidOrientationDerivedRef.current,
+      last_android_orientation_ignored_reason: lastAndroidOrientationIgnoredReasonRef.current,
+      last_android_orientation_error_at: lastAndroidOrientationErrorAtRef.current,
+      last_android_orientation_error: lastAndroidOrientationErrorRef.current,
+      ...extra,
+    });
+
+    const trackAndroidOrientationEvent = (
+      eventType: string,
+      error: unknown,
+      metadata: Record<string, string | number | boolean | null | undefined> = {},
+    ) => {
+      telemetry?.track(eventType, {
+        component: 'scanner',
+        error,
+        metadata: androidMetadata(metadata),
+      });
+    };
+
+    (async () => {
+      let Accelerometer: {
+        setUpdateInterval: (ms: number) => void;
+        addListener: (
+          cb: (data: { x: number; y: number; z: number }) => void,
+        ) => { remove: () => void };
+      } | null = null;
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const mod = require('expo-sensors');
+        Accelerometer = mod?.Accelerometer ?? null;
+      } catch (err) {
+        const error = normalizeScannerError(err);
+        const message = error.message || '';
+        const isMissingModule =
+          (error as { code?: string }).code === 'MODULE_NOT_FOUND' ||
+          /cannot find module/i.test(message) ||
+          /unable to resolve module/i.test(message) ||
+          /requireNativeModule/i.test(message);
+        if (isMissingModule) {
+          // expo-sensors is an optional peer dep. Host apps that don't bundle it
+          // simply lose Android orientation tracking — that's expected, not a failure.
+          return;
+        }
+        lastAndroidOrientationErrorAtRef.current = new Date().toISOString();
+        lastAndroidOrientationErrorRef.current = error.message;
+        trackAndroidOrientationEvent('camera_android_accelerometer_start_failure', error);
+        return;
+      }
+      if (cancelled) return;
+      if (!Accelerometer) {
+        // Module loaded but no Accelerometer export — same expected-absence case.
+        return;
+      }
+
+      const startedAt = new Date().toISOString();
+      androidOrientationStartedAtRef.current = startedAt;
+      androidOrientationSubscriptionActiveRef.current = true;
+      androidOrientationEventCountRef.current = 0;
+      androidOrientationChangeCountRef.current = 0;
+      lastAndroidOrientationTelemetryAtRef.current = 0;
+      trackAndroidOrientationEvent('camera_android_accelerometer_started', 'android_accelerometer_orientation_tracking_started', {
+        accelerometer_update_interval_ms: 500,
+        accelerometer_no_event_timeout_ms: ANDROID_ORIENTATION_NO_EVENT_TIMEOUT_MS,
+      });
+
+      noEventTimer = setTimeout(() => {
+        if (cancelled || androidOrientationEventCountRef.current > 0) return;
+        trackAndroidOrientationEvent(
+          'camera_android_accelerometer_no_events',
+          `No Android accelerometer events within ${ANDROID_ORIENTATION_NO_EVENT_TIMEOUT_MS}ms`,
+        );
+      }, ANDROID_ORIENTATION_NO_EVENT_TIMEOUT_MS);
+
+      Accelerometer.setUpdateInterval(500);
+      subscription = Accelerometer.addListener(({ x, y, z }) => {
+        const at = new Date();
+        const atIso = at.toISOString();
+        androidOrientationEventCountRef.current++;
+        lastAndroidOrientationEventAtRef.current = atIso;
+        lastAndroidOrientationXRef.current = Number(x.toFixed(4));
+        lastAndroidOrientationYRef.current = Number(y.toFixed(4));
+        lastAndroidOrientationZRef.current = Number(z.toFixed(4));
+        if (noEventTimer) {
+          clearTimeout(noEventTimer);
+          noEventTimer = null;
+        }
+
+        let next: typeof physicalOrientation | null = null;
+        let ignoredReason: string | null = null;
+        if (Math.abs(x) > Math.abs(y) + 0.2) {
+          next = x > 0 ? 'landscapeRight' : 'landscapeLeft';
+        } else if (Math.abs(y) > Math.abs(x) + 0.2) {
+          next = y > 0 ? 'portraitUpsideDown' : 'portrait';
+        } else {
+          ignoredReason = 'ambiguous_tilt';
+        }
+
+        lastAndroidOrientationDerivedRef.current = next;
+        lastAndroidOrientationIgnoredReasonRef.current = ignoredReason;
+
+        if (next && next !== lastOrientation) {
+          const previous = lastOrientation;
+          lastOrientation = next;
+          androidOrientationChangeCountRef.current++;
+          setPhysicalOrientation(next);
+          trackAndroidOrientationEvent('camera_android_physical_orientation_changed', `${previous} -> ${next}`, {
+            previous_physical_orientation: previous,
+            next_physical_orientation: next,
+            accelerometer_sampled_at: atIso,
+          });
+          return;
+        }
+
+        const shouldTrackSample =
+          androidOrientationEventCountRef.current === 1 ||
+          at.getTime() - lastAndroidOrientationTelemetryAtRef.current >= ANDROID_ORIENTATION_SAMPLE_TELEMETRY_MS;
+        if (shouldTrackSample) {
+          lastAndroidOrientationTelemetryAtRef.current = at.getTime();
+          trackAndroidOrientationEvent(
+            'camera_android_accelerometer_sample',
+            `accelerometer_sample_${androidOrientationEventCountRef.current}`,
+            { accelerometer_sampled_at: atIso },
+          );
+        }
+      });
+    })();
+
+    return () => {
+      cancelled = true;
+      androidOrientationSubscriptionActiveRef.current = false;
+      if (noEventTimer) clearTimeout(noEventTimer);
+      subscription?.remove();
+    };
+  }, [policy, telemetry, telemetryContext?.isPortraitLocked, telemetryContext?.routeName]);
+
   // Detect orientation changes and remount camera after rotation settles.
   // On iOS, AVCaptureVideoPreviewLayer distorts if remounted during the rotation
   // animation — the native preview layer initializes with transitional bounds.
@@ -605,8 +766,31 @@ export function VerifyAIScanner({
   }, [buildScannerTelemetryMetadata, permission, telemetry]);
 
   const handleCapture = useCallback(async () => {
-    if (!cameraRef.current || status === 'capturing' || status === 'processing' || exhausted) return;
-    if (!cameraReadyRef.current) {
+    const blockedReason =
+      !cameraRef.current
+        ? 'camera_ref_null'
+        : !cameraReadyRef.current
+          ? 'camera_not_ready'
+          : status === 'capturing'
+            ? 'already_capturing'
+            : status === 'processing'
+              ? 'already_processing'
+              : terminated
+                ? 'terminated'
+                : exhausted
+                  ? 'exhausted'
+                  : null;
+
+    telemetry?.track('camera_capture_request', {
+      component: 'scanner',
+      error: blockedReason == null ? 'capture_requested' : 'capture_ignored',
+      metadata: buildScannerTelemetryMetadata({
+        capture_blocked_reason: blockedReason,
+      }),
+    });
+
+    if (blockedReason && blockedReason !== 'camera_not_ready') return;
+    if (blockedReason === 'camera_not_ready') {
       const error = createScannerError(
         'Camera is not ready yet. Please wait a moment and try again.',
         CAMERA_NOT_READY_ERROR_CODE,
@@ -641,6 +825,18 @@ export function VerifyAIScanner({
     let lastNativeCaptureErrorMessage: string | null = null;
 
     try {
+      const capturePhysicalOrientation = physicalOrientation;
+      const captureOverlayRotationDeg = overlayRotationDeg;
+      telemetry?.track('camera_capture_orientation_context', {
+        component: 'scanner',
+        error: 'capture_orientation_context',
+        metadata: buildScannerTelemetryMetadata({
+          capture_physical_orientation: capturePhysicalOrientation,
+          capture_overlay_rotation_deg: captureOverlayRotationDeg,
+          capture_rotation_applied: 0,
+        }),
+      });
+
       // --- Capture + best-effort resize ---
       // Strategy: try to dynamically import expo-image-manipulator.
       //   If available → resize to MAX_DIMENSION, EXIF-normalize, return base64.
@@ -704,6 +900,19 @@ export function VerifyAIScanner({
               setCameraKey((key) => key + 1);
               await sleep(CAMERA_CAPTURE_RETRY_DELAY_MS);
               captureRetryReady = await waitForCameraReady(2500);
+              telemetry?.track('camera_capture_retry', {
+                component: 'scanner',
+                error: normalized,
+                errorCode: normalized.code,
+                metadata: buildScannerTelemetryMetadata({
+                  native_capture_attempts: nativeCaptureAttempts,
+                  capture_retry_attempted: captureRetryAttempted,
+                  capture_retry_ready: captureRetryReady,
+                  capture_retry_delay_ms: CAMERA_CAPTURE_RETRY_DELAY_MS,
+                  capture_retry_ready_timeout_ms: 2500,
+                  last_native_capture_error: lastNativeCaptureErrorMessage,
+                }),
+              });
               if (captureRetryReady) {
                 continue;
               }
@@ -891,7 +1100,7 @@ export function VerifyAIScanner({
         setTimeout(() => setStatus('idle'), TRANSIENT_ERROR_DISPLAY_MS);
       }
     }
-  }, [status, exhausted, onCapture, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust, releaseCamera, scheduleTerminalResult, buildScannerTelemetryMetadata, telemetry, terminated]);
+  }, [status, exhausted, onCapture, onError, overlay?.maxAttempts, overlay?.autoApproveOnExhaust, releaseCamera, scheduleTerminalResult, buildScannerTelemetryMetadata, telemetry, terminated, physicalOrientation, overlayRotationDeg]);
 
   // Expose capture to parent via ref
   if (captureRef) {
@@ -937,6 +1146,7 @@ export function VerifyAIScanner({
               <Text
                 style={[
                   styles.titleText,
+                  overlay.theme?.titleStyle,
                   { transform: [{ rotate: `${overlayRotationDeg}deg` }] },
                 ]}
               >
@@ -972,6 +1182,7 @@ export function VerifyAIScanner({
                 <Text
                   style={[
                     styles.guideCaptionText,
+                    overlay.theme?.feedbackStyle,
                     { transform: [{ rotate: `${overlayRotationDeg}deg` }] },
                   ]}
                 >
@@ -985,7 +1196,7 @@ export function VerifyAIScanner({
           {status === 'processing' && (
             <View style={styles.processingOverlay}>
               <ActivityIndicator size="large" color="#fff" />
-              <Text style={styles.statusText}>
+              <Text style={[styles.statusText, overlay?.theme?.feedbackStyle]}>
                 {overlay?.processingMessage || 'Analyzing photo...'}
               </Text>
             </View>
@@ -1030,7 +1241,7 @@ export function VerifyAIScanner({
                         : (overlay?.failureMessage || 'Not Verified')}
                   </Text>
                 </View>
-                <Text style={styles.feedbackText}>{result.feedback}</Text>
+                <Text style={[styles.feedbackText, overlay?.theme?.feedbackStyle]}>{result.feedback}</Text>
                 {overlay?.showTerminalActionButton !== false && onResult && (
                   <TouchableOpacity style={styles.cardButton} onPress={deliverVisibleTerminalResult}>
                     <Text style={styles.cardButtonText}>
@@ -1077,7 +1288,7 @@ export function VerifyAIScanner({
                       {errorTitle}
                     </Text>
                   </View>
-                  <Text style={styles.feedbackText}>{errorMessage}</Text>
+                  <Text style={[styles.feedbackText, overlay?.theme?.feedbackStyle]}>{errorMessage}</Text>
                   {showCloseAction && (
                     <TouchableOpacity style={styles.cardButton} onPress={handleClose}>
                       <Text style={styles.cardButtonText}>Close</Text>
@@ -1093,6 +1304,7 @@ export function VerifyAIScanner({
                   <Text
                     style={[
                       styles.instructionsText,
+                      overlay.theme?.feedbackStyle,
                       { transform: [{ rotate: `${overlayRotationDeg}deg` }] },
                     ]}
                   >

package/src/index.ts

@@ -39,5 +39,6 @@ export type {
   ScannerStatus,
   ScannerOverlayConfig,
   ScannerTheme,
+  ScannerTelemetryContext,
   PolicyConfigResponse,
 } from './types';

package/src/types/index.ts

@@ -1,4 +1,5 @@
 import type React from 'react';
+import type { TextStyle } from 'react-native';
 
 export interface VerifyAIConfig {
   apiKey: string;
@@ -87,6 +88,14 @@ export interface VerifyAIError {
 
 export type ScannerStatus = 'idle' | 'capturing' | 'processing' | 'success' | 'error';
 
+/** Optional host-app context attached to scanner telemetry. */
+export interface ScannerTelemetryContext {
+  /** Route or screen name from the host app. */
+  routeName?: string;
+  /** Whether the host app keeps this screen portrait-locked. */
+  isPortraitLocked?: boolean;
+}
+
 /**
  * Theme customization for the scanner overlay.
  *
@@ -103,6 +112,10 @@ export interface ScannerTheme {
   captureButtonColor?: string;
   /** Color for the guide frame corner brackets. Default: 'rgba(255, 255, 255, 0.7)'. */
   cornerColor?: string;
+  /** Text style override for the scanner title. */
+  titleStyle?: TextStyle;
+  /** Text style override for feedback/instruction text. */
+  feedbackStyle?: TextStyle;
 }
 
 export interface ScannerOverlayConfig {

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = '2.4.15';
+export const SDK_VERSION = '2.4.17';