@trustchex/react-native-sdk 1.381.0 → 1.464.0

package/src/Shared/Components/IdentityDocumentCamera.tsx

@@ -174,6 +174,7 @@ const IdentityDocumentCamera = ({
   const isHologramDetectionInProgress = useRef(false); // Prevent concurrent hologram detection calls
   const isCompletionCallbackInvoked = useRef(false); // Prevent multiple callback invocations when COMPLETED
   const isStepTransitionInProgress = useRef(false); // Prevent duplicate step transitions from rapid frames
+  const isCompletionAnnouncementSpoken = useRef(false); // Prevent duplicate "scan completed" voice guidance
 
   const faceDetectionErrorCount = useRef(0);
   const brightnessHistory = useRef<number[]>([]);
@@ -181,7 +182,6 @@ const IdentityDocumentCamera = ({
   const faceImages = useRef<string[]>([]);
   const hologramImageCountRef = useRef(0);
   const [hologramImageCount, setHologramImageCount] = useState(0);
-  const lastVoiceGuidanceMessage = useRef<string>('');
   const [latestHologramFaceImage, setLatestHologramFaceImage] = useState<
     string | undefined
   >(undefined);
@@ -264,6 +264,7 @@ const IdentityDocumentCamera = ({
       setIsActive(true);
       isCompletionCallbackInvoked.current = false; // Reset callback flag when starting new scan
       isStepTransitionInProgress.current = false;
+      isCompletionAnnouncementSpoken.current = false;
     } else {
       setIsActive(false);
       faceImages.current = [];
@@ -277,9 +278,9 @@ const IdentityDocumentCamera = ({
       lastValidMRZFields.current = null;
       validMRZConsecutiveCount.current = 0;
       cachedBarcode.current = null;
-      lastVoiceGuidanceMessage.current = '';
       isCompletionCallbackInvoked.current = false;
       isStepTransitionInProgress.current = false;
+      isCompletionAnnouncementSpoken.current = false;
       // Clear all captured image states from previous scan
       setCurrentFaceImage(undefined);
       setCurrentHologramImage(undefined);
@@ -293,9 +294,9 @@ const IdentityDocumentCamera = ({
       hologramImageCountRef.current = 0;
       setHologramImageCount(0);
       setLatestHologramFaceImage(undefined);
-      lastVoiceGuidanceMessage.current = '';
       isCompletionCallbackInvoked.current = false; // Reset callback flag on unmount
       isStepTransitionInProgress.current = false;
+      isCompletionAnnouncementSpoken.current = false;
       // Clear all captured image states on unmount
       setCurrentFaceImage(undefined);
       setCurrentHologramImage(undefined);
@@ -322,9 +323,17 @@ const IdentityDocumentCamera = ({
       t
     );
 
-    if (message && message !== lastVoiceGuidanceMessage.current) {
-      lastVoiceGuidanceMessage.current = message;
-      speak(message, true);
+    if (message) {
+      if (nextStep === 'COMPLETED') {
+        if (isCompletionAnnouncementSpoken.current) {
+          return;
+        }
+        isCompletionAnnouncementSpoken.current = true;
+      } else {
+        isCompletionAnnouncementSpoken.current = false;
+      }
+      const shouldBypassInterval = nextStep !== 'COMPLETED';
+      speak(message, shouldBypassInterval);
     }
   }, [
     appContext.currentWorkflowStep?.data?.voiceGuidanceActive,
@@ -365,6 +374,20 @@ const IdentityDocumentCamera = ({
     isStepTransitionInProgress.current = false;
   }, [nextStep]);
 
+  // Update status bar based on guide visibility
+  useEffect(() => {
+    if (hasGuideShown) {
+      // Scanning camera view - use light icons on dark background
+      StatusBar.setBarStyle('light-content', true);
+    } else {
+      // Guide screen with white background - use dark icons
+      StatusBar.setBarStyle('dark-content', true);
+      if (Platform.OS === 'android') {
+        StatusBar.setBackgroundColor('#ffffff', true);
+      }
+    }
+  }, [hasGuideShown]);
+
   // Error flash animation - flash red text when wrong side detected
   useEffect(() => {
     if (status === 'INCORRECT') {
@@ -2230,6 +2253,55 @@ const IdentityDocumentCamera = ({
     []
   );
 
+  // Show the guide immediately — the guide is pure UI and does not need
+  // camera access. Permission is requested in the background (useEffect) so
+  // it will usually be resolved by the time the user taps "Let's Go".
+  // This avoids a white/blank screen while the async permission check runs.
+  if (!hasGuideShown) {
+    return (
+      <View style={StyleSheet.absoluteFill}>
+        <StatusBar
+          barStyle="dark-content"
+          backgroundColor="#ffffff"
+          translucent
+        />
+        <SafeAreaView style={styles.guide}>
+          <LottieView
+            source={require('../../Shared/Animations/id-or-passport.json')}
+            style={styles.guideAnimation}
+            loop={true}
+            autoPlay
+          />
+          <TextView style={styles.guideHeader}>
+            {t('identityDocumentCamera.guideHeader')}
+          </TextView>
+          <View style={styles.guidePoints}>
+            <TextView style={styles.guideText}>
+              {t('identityDocumentCamera.guideText')}
+            </TextView>
+            <TextView style={styles.guideText}>
+              • {t('identityDocumentCamera.guidePoint1')}
+            </TextView>
+            <TextView style={styles.guideText}>
+              • {t('identityDocumentCamera.guidePoint2')}
+            </TextView>
+            <TextView style={styles.guideText}>
+              • {t('identityDocumentCamera.guidePoint3')}
+            </TextView>
+          </View>
+          <StyledButton
+            mode="contained"
+            onPress={() => {
+              setHasGuideShown(true);
+            }}
+          >
+            {t('general.letsGo')}
+          </StyledButton>
+        </SafeAreaView>
+      </View>
+    );
+  }
+
   if (!permissionsRequested) {
     return (
       <SafeAreaView style={styles.permissionContainer}>
@@ -2265,197 +2337,161 @@ const IdentityDocumentCamera = ({
         backgroundColor="transparent"
         translucent
       />
-      {!hasGuideShown ? (
-        <SafeAreaView style={styles.guide}>
-          <LottieView
-            source={require('../../Shared/Animations/id-or-passport.json')}
-            style={styles.guideAnimation}
-            loop={true}
-            autoPlay
-          />
-          <TextView style={styles.guideHeader}>
-            {t('identityDocumentCamera.guideHeader')}
-          </TextView>
-          <View style={styles.guidePoints}>
-            <TextView style={styles.guideText}>
-              {t('identityDocumentCamera.guideText')}
-            </TextView>
-            <TextView style={styles.guideText}>
-              • {t('identityDocumentCamera.guidePoint1')}
-            </TextView>
-            <TextView style={styles.guideText}>
-              • {t('identityDocumentCamera.guidePoint2')}
-            </TextView>
-            <TextView style={styles.guideText}>
-              • {t('identityDocumentCamera.guidePoint3')}
-            </TextView>
-          </View>
-          <StyledButton
-            mode="contained"
-            onPress={() => {
-              setHasGuideShown(true);
-            }}
-          >
-            {t('general.letsGo')}
-          </StyledButton>
-        </SafeAreaView>
-      ) : (
-        <>
-          <TrustchexCamera
-            ref={cameraRef}
-            style={StyleSheet.absoluteFill as ViewStyle}
-            cameraType="back"
-            enableFrameProcessing={isActive}
-            enableFaceDetection={isActive && faceDetectionEnabled}
-            enableTextRecognition={isActive}
-            enableBarcodeScanning={isActive && nextStep === 'SCAN_ID_BACK'}
-            includeBase64={isActive}
-            targetFps={10}
-            torchEnabled={isTorchOn}
-            onFrameAvailable={handleFrame}
-            onCameraReady={handleCameraReady}
-            onCameraError={handleCameraError}
-          />
-          <View style={[styles.topZone, { paddingTop: insets.top }]}>
-            {nextStep !== 'COMPLETED' &&
-              status !== 'SCANNED' &&
-              detectedDocumentType !== 'UNKNOWN' && (
-                <TextView style={styles.stepIndicator}>
-                  {nextStep === 'SCAN_ID_FRONT_OR_PASSPORT'
-                    ? `${t('identityDocumentCamera.frontSide')} • ${t(
+      <>
+        <TrustchexCamera
+          ref={cameraRef}
+          style={StyleSheet.absoluteFill as ViewStyle}
+          cameraType="back"
+          enableFrameProcessing={isActive}
+          enableFaceDetection={isActive && faceDetectionEnabled}
+          enableTextRecognition={isActive}
+          enableBarcodeScanning={isActive && nextStep === 'SCAN_ID_BACK'}
+          includeBase64={isActive}
+          targetFps={10}
+          torchEnabled={isTorchOn}
+          onFrameAvailable={handleFrame}
+          onCameraReady={handleCameraReady}
+          onCameraError={handleCameraError}
+        />
+        <View style={[styles.topZone, { paddingTop: insets.top }]}>
+          {nextStep !== 'COMPLETED' &&
+            status !== 'SCANNED' &&
+            detectedDocumentType !== 'UNKNOWN' && (
+              <TextView style={styles.stepIndicator}>
+                {nextStep === 'SCAN_ID_FRONT_OR_PASSPORT'
+                  ? `${t('identityDocumentCamera.frontSide')} • ${t(
+                      'identityDocumentCamera.stepProgress',
+                      {
+                        current: 1,
+                        total: onlyMRZScan
+                          ? detectedDocumentType === 'PASSPORT'
+                            ? 1
+                            : 2
+                          : detectedDocumentType === 'PASSPORT'
+                            ? 2
+                            : 3,
+                      }
+                    )}`
+                  : nextStep === 'SCAN_HOLOGRAM'
+                    ? `${t('identityDocumentCamera.hologramCheck')} • ${t(
                         'identityDocumentCamera.stepProgress',
                         {
-                          current: 1,
-                          total: onlyMRZScan
-                            ? detectedDocumentType === 'PASSPORT'
-                              ? 1
-                              : 2
-                            : detectedDocumentType === 'PASSPORT'
-                              ? 2
-                              : 3,
+                          current: 2,
+                          total: detectedDocumentType === 'PASSPORT' ? 2 : 3,
                         }
                       )}`
-                    : nextStep === 'SCAN_HOLOGRAM'
-                      ? `${t('identityDocumentCamera.hologramCheck')} • ${t(
-                          'identityDocumentCamera.stepProgress',
-                          {
-                            current: 2,
-                            total: detectedDocumentType === 'PASSPORT' ? 2 : 3,
-                          }
-                        )}`
-                      : nextStep === 'SCAN_ID_BACK'
-                        ? `${t('identityDocumentCamera.backSide')} • ${t('identityDocumentCamera.stepProgress', { current: 3, total: 3 })}`
-                        : ''}
-                </TextView>
-              )}
-
-            <AnimatedText
-              style={[
-                styles.topZoneText,
-                // Priority order for coloring (later styles override earlier ones)
-                // 1. Success (green) - scan completed
-                nextStep === 'COMPLETED' && styles.topZoneTextSuccess,
-                // 2. Error (red) - wrong side - with flash opacity
-                status === 'INCORRECT' && styles.topZoneTextError,
-                status === 'INCORRECT' && {
-                  opacity: errorFlashAnim,
-                },
-                // 3. Warning (yellow) - quality issues
-                (isBrightnessLow || isFrameBlurry) && styles.topZoneTextWarning,
-                // 4. Scanning (green) - all elements detected AND inside scan area
-                status === 'SCANNING' &&
-                  allElementsDetected &&
-                  elementsOutsideScanArea.length === 0 &&
-                  !isBrightnessLow &&
-                  !isFrameBlurry &&
-                  styles.topZoneTextScanning,
-                // 5. Default (white) - aligning (not all detected OR elements outside scan area)
-              ]}
-            >
-              {getStatusMessage(
-                nextStep,
-                status,
-                detectedDocumentType,
-                isBrightnessLow,
-                isFrameBlurry,
-                allElementsDetected,
-                elementsOutsideScanArea,
-                t
-              )}
-            </AnimatedText>
-          </View>
-          <View style={styles.leftZone} />
-          <View style={styles.rightZone} />
-          <View style={styles.bottomZone} />
-          <View
+                    : nextStep === 'SCAN_ID_BACK'
+                      ? `${t('identityDocumentCamera.backSide')} • ${t('identityDocumentCamera.stepProgress', { current: 3, total: 3 })}`
+                      : ''}
+              </TextView>
+            )}
+
+          <AnimatedText
             style={[
-              styles.scanArea,
-              {
-                borderColor:
-                  nextStep === 'COMPLETED'
-                    ? '#4CAF50'
-                    : status === 'INCORRECT'
-                      ? '#f44336'
-                      : status === 'SCANNING'
-                        ? '#2196F3'
-                        : isBrightnessLow || isFrameBlurry
-                          ? '#FFC107'
-                          : 'white',
-                borderWidth: status === 'SCANNING' ? 3 : 2,
+              styles.topZoneText,
+              // Priority order for coloring (later styles override earlier ones)
+              // 1. Success (green) - scan completed
+              nextStep === 'COMPLETED' && styles.topZoneTextSuccess,
+              // 2. Error (red) - wrong side - with flash opacity
+              status === 'INCORRECT' && styles.topZoneTextError,
+              status === 'INCORRECT' && {
+                opacity: errorFlashAnim,
               },
+              // 3. Warning (yellow) - quality issues
+              (isBrightnessLow || isFrameBlurry) && styles.topZoneTextWarning,
+              // 4. Scanning (green) - all elements detected AND inside scan area
+              status === 'SCANNING' &&
+                allElementsDetected &&
+                elementsOutsideScanArea.length === 0 &&
+                !isBrightnessLow &&
+                !isFrameBlurry &&
+                styles.topZoneTextScanning,
+              // 5. Default (white) - aligning (not all detected OR elements outside scan area)
             ]}
           >
-            {nextStep === 'COMPLETED' ? (
-              <LottieView
-                source={require('../../Shared/Animations/success.json')}
-                style={styles.animation}
-                loop={false}
-                autoPlay
-              />
-            ) : isBrightnessLow ? (
-              <LottieView
-                source={require('../../Shared/Animations/light.json')}
-                style={styles.animation}
-                loop={true}
-                autoPlay
-              />
-            ) : nextStep === 'SCAN_HOLOGRAM' && isTorchOn ? (
-              <LottieView
-                source={require('../../Shared/Animations/hologram-scan.json')}
-                style={styles.animation}
-                loop={true}
-                autoPlay
-              />
-            ) : null}
-          </View>
-          {isDebugEnabled() && (
-            <DebugOverlay
-              nextStep={nextStep}
-              status={status}
-              detectedDocumentType={detectedDocumentType}
-              isBrightnessLow={isBrightnessLow}
-              isFrameBlurry={isFrameBlurry}
-              isTorchOn={isTorchOn}
-              documentPlaneBounds={documentPlaneBounds}
-              secondaryFaceBounds={secondaryFaceBounds}
-              barcodeBounds={barcodeBounds}
-              mrzBounds={mrzBounds}
-              signatureBounds={signatureBounds}
-              currentFaceImage={currentFaceImage}
-              currentSecondaryFaceImage={currentSecondaryFaceImage}
-              currentHologramImage={currentHologramImage}
-              currentHologramMaskImage={_currentHologramMaskImage}
-              latestHologramFaceImage={latestHologramFaceImage}
-              hologramImageCount={hologramImageCount}
-              allElementsDetected={allElementsDetected}
-              elementsOutsideScanArea={elementsOutsideScanArea}
+            {getStatusMessage(
+              nextStep,
+              status,
+              detectedDocumentType,
+              isBrightnessLow,
+              isFrameBlurry,
+              allElementsDetected,
+              elementsOutsideScanArea,
+              t
+            )}
+          </AnimatedText>
+        </View>
+        <View style={styles.leftZone} />
+        <View style={styles.rightZone} />
+        <View style={styles.bottomZone} />
+        <View
+          style={[
+            styles.scanArea,
+            {
+              borderColor:
+                nextStep === 'COMPLETED'
+                  ? '#4CAF50'
+                  : status === 'INCORRECT'
+                    ? '#f44336'
+                    : status === 'SCANNING'
+                      ? '#2196F3'
+                      : isBrightnessLow || isFrameBlurry
+                        ? '#FFC107'
+                        : 'white',
+              borderWidth: status === 'SCANNING' ? 3 : 2,
+            },
+          ]}
+        >
+          {nextStep === 'COMPLETED' ? (
+            <LottieView
+              source={require('../../Shared/Animations/success.json')}
+              style={styles.animation}
+              loop={false}
+              autoPlay
+            />
+          ) : isBrightnessLow ? (
+            <LottieView
+              source={require('../../Shared/Animations/light.json')}
+              style={styles.animation}
+              loop={true}
+              autoPlay
             />
-          )}
-          {testMode && testModeData && (
-            <TestModePanel mrzText={testModeData.mrzText} />
-          )}
-        </>
-      )}
+          ) : nextStep === 'SCAN_HOLOGRAM' && isTorchOn ? (
+            <LottieView
+              source={require('../../Shared/Animations/hologram-scan.json')}
+              style={styles.animation}
+              loop={true}
+              autoPlay
+            />
+          ) : null}
+        </View>
+        {isDebugEnabled() && (
+          <DebugOverlay
+            nextStep={nextStep}
+            status={status}
+            detectedDocumentType={detectedDocumentType}
+            isBrightnessLow={isBrightnessLow}
+            isFrameBlurry={isFrameBlurry}
+            isTorchOn={isTorchOn}
+            documentPlaneBounds={documentPlaneBounds}
+            secondaryFaceBounds={secondaryFaceBounds}
+            barcodeBounds={barcodeBounds}
+            mrzBounds={mrzBounds}
+            signatureBounds={signatureBounds}
+            currentFaceImage={currentFaceImage}
+            currentSecondaryFaceImage={currentSecondaryFaceImage}
+            currentHologramImage={currentHologramImage}
+            currentHologramMaskImage={_currentHologramMaskImage}
+            latestHologramFaceImage={latestHologramFaceImage}
+            hologramImageCount={hologramImageCount}
+            allElementsDetected={allElementsDetected}
+            elementsOutsideScanArea={elementsOutsideScanArea}
+          />
+        )}
+        {testMode && testModeData && (
+          <TestModePanel mrzText={testModeData.mrzText} />
+        )}
+      </>
     </View>
   );
 };

package/src/Shared/Components/IdentityDocumentCamera.utils.ts

@@ -12,6 +12,15 @@ import {
 } from './IdentityDocumentCamera.constants';
 import { debugLog, isDebugEnabled } from '../Libs/debug.utils';
 
+/**
+ * Checks if a document code represents an ID card (TD1/TD2).
+ * Per ICAO 9303, valid ID card codes start with 'I', 'A', or 'C'.
+ */
+export function isIDCardDocumentCode(code: string | null | undefined): boolean {
+  if (!code) return false;
+  return code.startsWith('I') || code.startsWith('A') || code.startsWith('C');
+}
+
 /**
  * Frame-to-screen coordinate transform using FILL_CENTER scaling
  */
@@ -225,8 +234,8 @@ export function detectDocumentType(
     });
   }
 
-  // ID Back: no face + ID MRZ
-  if (faces.length === 0 && mrzFields?.documentCode === 'I') {
+  // ID Back: no face + ID MRZ (codes starting with I, A, or C per ICAO 9303)
+  if (faces.length === 0 && isIDCardDocumentCode(mrzFields?.documentCode)) {
     return 'ID_BACK';
   }
 
@@ -265,8 +274,8 @@ export function detectDocumentType(
       : faces;
 
     if (cardSizedFaces.length > 0) {
-      // If we have MRZ code 'I', it's definitely an ID card
-      if (mrzFields?.documentCode === 'I') {
+      // If we have an ID card MRZ code (I, A, or C), it's definitely an ID card
+      if (isIDCardDocumentCode(mrzFields?.documentCode)) {
         return 'ID_FRONT';
       }