@hexar/biometric-identity-sdk-react-native 1.2.0 → 1.3.0

package/dist/components/BiometricIdentityFlow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BiometricIdentityFlow.d.ts","sourceRoot":"","sources":["../../src/components/BiometricIdentityFlow.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAmD,MAAM,OAAO,CAAC;AACxE,OAAO,EAOL,SAAS,EACV,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,cAAc,EAKd,iBAAiB,EAElB,MAAM,oCAAoC,CAAC;AA8B5C,MAAM,WAAW,0BAA0B;IACzC,oBAAoB,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACzD,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IACzC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,MAAM,CAAC,EAAE;QACP,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,OAAO,CAAC,EAAE,SAAS,CAAC;KACrB,CAAC;CACH;AAED,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,EAAE,CAAC,0BAA0B,CAuatE,CAAC;AA+NF,eAAe,qBAAqB,CAAC"}
+{"version":3,"file":"BiometricIdentityFlow.d.ts","sourceRoot":"","sources":["../../src/components/BiometricIdentityFlow.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAmD,MAAM,OAAO,CAAC;AACxE,OAAO,EAOL,SAAS,EACV,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,cAAc,EAKd,iBAAiB,EAElB,MAAM,oCAAoC,CAAC;AA+B5C,MAAM,WAAW,0BAA0B;IACzC,oBAAoB,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACzD,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IACzC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,MAAM,CAAC,EAAE;QACP,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,OAAO,CAAC,EAAE,SAAS,CAAC;KACrB,CAAC;CACH;AAED,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,EAAE,CAAC,0BAA0B,CAictE,CAAC;AA+NF,eAAe,qBAAqB,CAAC"}

package/dist/components/BiometricIdentityFlow.js

@@ -67,11 +67,13 @@ const ValidationProgress_1 = require("./ValidationProgress");
 const ResultScreen_1 = require("./ResultScreen");
 const ErrorScreen_1 = require("./ErrorScreen");
 const InstructionsScreen_1 = require("./InstructionsScreen");
+const FacePositioningGuide_1 = require("./FacePositioningGuide");
 const BiometricIdentityFlow = ({ onValidationComplete, onError, theme, language, customTranslations, smartLivenessMode = true, routeBack, styles: customStyles, }) => {
     const { sdk, state, isInitialized, isUsingBackend, challenges, uploadFrontID, uploadBackID, storeVideoRecording, fetchChallenges, validateIdentity, reset, } = (0, useBiometricSDK_1.useBiometricSDK)();
     const [showCamera, setShowCamera] = (0, react_1.useState)(false);
     const [cameraMode, setCameraMode] = (0, react_1.useState)('front');
     const [showInstructions, setShowInstructions] = (0, react_1.useState)(true);
+    const [showFacePositioningGuide, setShowFacePositioningGuide] = (0, react_1.useState)(false);
     const [currentChallenges, setCurrentChallenges] = (0, react_1.useState)([]);
     const [isLoadingChallenges, setIsLoadingChallenges] = (0, react_1.useState)(false);
     const onValidationCompleteRef = (0, react_1.useRef)(onValidationComplete);
@@ -117,7 +119,15 @@ const BiometricIdentityFlow = ({ onValidationComplete, onError, theme, language,
      */
     const handleCaptureStart = (0, react_1.useCallback)(async (mode) => {
         setCameraMode(mode);
-        if (mode === 'video' && smartLivenessMode && isUsingBackend) {
+        if (mode === 'video') {
+            setShowFacePositioningGuide(true);
+            // Challenges will be loaded when guide is dismissed and we show camera
+        }
+        if (mode !== 'video') {
+            setShowCamera(true);
+            return;
+        }
+        if (smartLivenessMode && isUsingBackend) {
             setIsLoadingChallenges(true);
             try {
                 const challenges = await fetchChallenges('active');
@@ -186,8 +196,11 @@ const BiometricIdentityFlow = ({ onValidationComplete, onError, theme, language,
             });
             setCurrentChallenges(translatedChallenges);
         }
-        setShowCamera(true);
     }, [smartLivenessMode, isUsingBackend, fetchChallenges, sdk]);
+    const handleFacePositioningContinue = (0, react_1.useCallback)(() => {
+        setShowFacePositioningGuide(false);
+        setShowCamera(true);
+    }, []);
     /**
      * Handle capture completion
      */
@@ -287,6 +300,9 @@ const BiometricIdentityFlow = ({ onValidationComplete, onError, theme, language,
     if (showInstructions) {
         return (react_1.default.createElement(InstructionsScreen_1.InstructionsScreen, { theme: theme, language: language, onStart: () => setShowInstructions(false), routeBack: routeBack, styles: customStyles }));
     }
+    if (showFacePositioningGuide) {
+        return (react_1.default.createElement(FacePositioningGuide_1.FacePositioningGuide, { theme: theme, language: language, onContinue: handleFacePositioningContinue, onCancel: () => setShowFacePositioningGuide(false), styles: customStyles }));
+    }
     if (showCamera) {
         if (cameraMode === 'video') {
             return (react_1.default.createElement(VideoRecorder_1.VideoRecorder, { theme: theme, language: language, challenges: currentChallenges, smartMode: smartLivenessMode, sessionId: sdk.getSessionId() || undefined, onComplete: handleCaptureComplete, onCancel: () => setShowCamera(false), onFetchChallenges: async () => {

package/dist/components/FacePositioningGuide.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Face Positioning Guide Component
+ * Shared view that instructs users to keep their face inside the oval
+ * for better approval rate. Used before video capture in both
+ * BiometricIdentityFlow and ProfilePictureCapture.
+ */
+import React from 'react';
+import { ViewStyle } from 'react-native';
+import { ThemeConfig, SupportedLanguage } from '@hexar/biometric-identity-sdk-core';
+export interface FacePositioningGuideProps {
+    theme?: ThemeConfig;
+    language?: SupportedLanguage;
+    onContinue: () => void;
+    onCancel?: () => void;
+    styles?: {
+        container?: ViewStyle;
+        content?: ViewStyle;
+    };
+}
+export declare const FacePositioningGuide: React.FC<FacePositioningGuideProps>;
+export default FacePositioningGuide;
+//# sourceMappingURL=FacePositioningGuide.d.ts.map

package/dist/components/FacePositioningGuide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FacePositioningGuide.d.ts","sourceRoot":"","sources":["../../src/components/FacePositioningGuide.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAOL,SAAS,EACV,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAA2B,MAAM,oCAAoC,CAAC;AAE7G,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE;QACP,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,OAAO,CAAC,EAAE,SAAS,CAAC;KACrB,CAAC;CACH;AAED,eAAO,MAAM,oBAAoB,EAAE,KAAK,CAAC,EAAE,CAAC,yBAAyB,CAqEpE,CAAC;AA0HF,eAAe,oBAAoB,CAAC"}

package/dist/components/FacePositioningGuide.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * Face Positioning Guide Component
+ * Shared view that instructs users to keep their face inside the oval
+ * for better approval rate. Used before video capture in both
+ * BiometricIdentityFlow and ProfilePictureCapture.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FacePositioningGuide = void 0;
+const react_1 = __importDefault(require("react"));
+const react_native_1 = require("react-native");
+const biometric_identity_sdk_core_1 = require("@hexar/biometric-identity-sdk-core");
+const FacePositioningGuide = ({ theme, language, onContinue, onCancel, styles: customStyles, }) => {
+    if (language) {
+        (0, biometric_identity_sdk_core_1.setLanguage)(language);
+    }
+    const strings = (0, biometric_identity_sdk_core_1.getStrings)();
+    const liveness = strings.liveness;
+    const guide = liveness?.facePositioningGuide;
+    const title = guide?.title ?? 'Position your face';
+    const description = guide?.description ?? 'Keep your face inside the oval for the best approval rate. Positioning your face outside the frame may reduce your chances of approval.';
+    const tip = guide?.tip ?? 'Face inside = better approval • Face outside = lower chances';
+    const continueLabel = guide?.continue ?? strings.common?.continue ?? 'Continue';
+    const primaryColor = theme?.primaryColor ?? '#6366F1';
+    const textColor = theme?.textColor ?? '#000000';
+    const secondaryTextColor = theme?.secondaryTextColor ?? '#6B7280';
+    const backgroundColor = theme?.backgroundColor ?? '#FFFFFF';
+    const styles = createStyles({
+        primaryColor,
+        textColor,
+        secondaryTextColor,
+        backgroundColor,
+    });
+    return (react_1.default.createElement(react_native_1.SafeAreaView, { style: [styles.container, customStyles?.container] },
+        onCancel && (react_1.default.createElement(react_native_1.TouchableOpacity, { style: styles.cancelButton, onPress: onCancel },
+            react_1.default.createElement(react_native_1.Text, { style: [styles.cancelText, { color: textColor }] }, strings.common?.cancel ?? 'Cancel'))),
+        react_1.default.createElement(react_native_1.ScrollView, { contentContainerStyle: [styles.scrollContent, customStyles?.content], showsVerticalScrollIndicator: false },
+            react_1.default.createElement(react_native_1.Text, { style: [styles.title, { color: textColor }] }, title),
+            react_1.default.createElement(react_native_1.Text, { style: [styles.description, { color: secondaryTextColor }] }, description),
+            react_1.default.createElement(react_native_1.View, { style: styles.ovalWrapper },
+                react_1.default.createElement(react_native_1.View, { style: [styles.oval, { borderColor: primaryColor }] },
+                    react_1.default.createElement(FaceIcon, { color: secondaryTextColor }))),
+            react_1.default.createElement(react_native_1.View, { style: [styles.tipBox, { borderColor: primaryColor + '30', backgroundColor: primaryColor + '08' }] },
+                react_1.default.createElement(react_native_1.Text, { style: [styles.tipText, { color: secondaryTextColor }] }, tip)),
+            react_1.default.createElement(react_native_1.TouchableOpacity, { style: [styles.continueButton, { backgroundColor: primaryColor }], onPress: onContinue, activeOpacity: 0.85 },
+                react_1.default.createElement(react_native_1.Text, { style: styles.continueButtonText }, continueLabel)))));
+};
+exports.FacePositioningGuide = FacePositioningGuide;
+/** Simple geometric face icon (head + eyes) when react-native-svg is not used */
+const FaceIcon = ({ color }) => (react_1.default.createElement(react_native_1.View, { style: faceIconStyles.container },
+    react_1.default.createElement(react_native_1.View, { style: [faceIconStyles.head, { backgroundColor: color }] }),
+    react_1.default.createElement(react_native_1.View, { style: faceIconStyles.eyes },
+        react_1.default.createElement(react_native_1.View, { style: [faceIconStyles.eye, { backgroundColor: color }] }),
+        react_1.default.createElement(react_native_1.View, { style: [faceIconStyles.eye, { backgroundColor: color }] }))));
+const faceIconStyles = react_native_1.StyleSheet.create({
+    container: {
+        alignItems: 'center',
+        justifyContent: 'center',
+    },
+    head: {
+        width: 80,
+        height: 100,
+        borderRadius: 50,
+        opacity: 0.4,
+    },
+    eyes: {
+        flexDirection: 'row',
+        justifyContent: 'space-between',
+        width: 44,
+        marginTop: -70,
+        opacity: 0.5,
+    },
+    eye: {
+        width: 12,
+        height: 12,
+        borderRadius: 6,
+    },
+});
+const createStyles = (vars) => react_native_1.StyleSheet.create({
+    container: {
+        flex: 1,
+        backgroundColor: vars.backgroundColor,
+        zIndex: 9999,
+    },
+    cancelButton: {
+        alignSelf: 'flex-start',
+        paddingVertical: 12,
+        paddingHorizontal: 16,
+        marginTop: 8,
+    },
+    cancelText: {
+        fontSize: 16,
+        fontWeight: '500',
+    },
+    scrollContent: {
+        paddingHorizontal: 24,
+        paddingBottom: 40,
+        alignItems: 'center',
+    },
+    title: {
+        fontSize: 24,
+        fontWeight: '700',
+        marginBottom: 12,
+        textAlign: 'center',
+    },
+    description: {
+        fontSize: 16,
+        lineHeight: 24,
+        textAlign: 'center',
+        marginBottom: 28,
+        paddingHorizontal: 8,
+    },
+    ovalWrapper: {
+        marginBottom: 24,
+    },
+    oval: {
+        width: 260,
+        height: 320,
+        borderRadius: 160,
+        borderWidth: 3,
+        alignItems: 'center',
+        justifyContent: 'center',
+        overflow: 'hidden',
+    },
+    tipBox: {
+        paddingVertical: 14,
+        paddingHorizontal: 20,
+        borderRadius: 12,
+        borderWidth: 1,
+        marginBottom: 32,
+        alignSelf: 'stretch',
+    },
+    tipText: {
+        fontSize: 14,
+        fontWeight: '600',
+        textAlign: 'center',
+    },
+    continueButton: {
+        paddingVertical: 16,
+        paddingHorizontal: 32,
+        borderRadius: 12,
+        alignItems: 'center',
+        alignSelf: 'stretch',
+        shadowColor: '#000',
+        shadowOffset: { width: 0, height: 2 },
+        shadowOpacity: 0.1,
+        shadowRadius: 4,
+        elevation: 3,
+    },
+    continueButtonText: {
+        color: '#FFFFFF',
+        fontSize: 18,
+        fontWeight: '700',
+    },
+});
+exports.default = exports.FacePositioningGuide;

package/dist/components/ProfilePictureCapture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProfilePictureCapture.d.ts","sourceRoot":"","sources":["../../src/components/ProfilePictureCapture.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmD,MAAM,OAAO,CAAC;AAUxE,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAmC,cAAc,EAAsB,MAAM,oCAAoC,CAAC;AAGzJ,MAAM,WAAW,8BAA8B;IAC7C,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,CAAC,MAAM,EAAE,8BAA8B,KAAK,IAAI,CAAC;IAC7D,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IACzC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAED,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,EAAE,CAAC,0BAA0B,CAkUtE,CAAC;AAsEF,eAAe,qBAAqB,CAAC"}
+{"version":3,"file":"ProfilePictureCapture.d.ts","sourceRoot":"","sources":["../../src/components/ProfilePictureCapture.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmD,MAAM,OAAO,CAAC;AAWxE,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAmC,cAAc,EAAsB,MAAM,oCAAoC,CAAC;AAGzJ,MAAM,WAAW,8BAA8B;IAC7C,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,CAAC,MAAM,EAAE,8BAA8B,KAAK,IAAI,CAAC;IAC7D,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IACzC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAED,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,EAAE,CAAC,0BAA0B,CA8UtE,CAAC;AAsEF,eAAe,qBAAqB,CAAC"}

package/dist/components/ProfilePictureCapture.js

@@ -37,10 +37,12 @@ exports.ProfilePictureCapture = void 0;
 const react_1 = __importStar(require("react"));
 const react_native_1 = require("react-native");
 const VideoRecorder_1 = require("./VideoRecorder");
+const FacePositioningGuide_1 = require("./FacePositioningGuide");
 const biometric_identity_sdk_core_1 = require("@hexar/biometric-identity-sdk-core");
 const useBiometricSDK_1 = require("../hooks/useBiometricSDK");
 const ProfilePictureCapture = ({ onComplete, onError, onCancel, theme, language, }) => {
     const { sdk, isInitialized, isUsingBackend, sessionId, fetchChallenges, } = (0, useBiometricSDK_1.useBiometricSDK)();
+    const [showFacePositioningGuide, setShowFacePositioningGuide] = (0, react_1.useState)(true);
     const [isValidating, setIsValidating] = (0, react_1.useState)(false);
     const [currentChallenges, setCurrentChallenges] = (0, react_1.useState)([]);
     const [isLoadingChallenges, setIsLoadingChallenges] = (0, react_1.useState)(false);
@@ -278,13 +280,16 @@ const ProfilePictureCapture = ({ onComplete, onError, onCancel, theme, language,
                         "%")),
                 react_1.default.createElement(react_native_1.Text, { style: [styles.progressBottomText, { color: theme?.secondaryTextColor || '#64748b' }] }, strings.validation.almostDone || strings.common.loading || 'Esto puede tardar unos segundos...'))));
     }
-    // Wait for initialization and challenge loading before showing VideoRecorder
+    // Wait for initialization and challenge loading before showing guide or VideoRecorder
     if (!isInitialized || (isUsingBackend && isLoadingChallenges)) {
         return (react_1.default.createElement(react_native_1.SafeAreaView, { style: [styles.container, { backgroundColor: theme?.backgroundColor || '#FFFFFF' }] },
             react_1.default.createElement(react_native_1.View, { style: styles.loadingContainer },
                 react_1.default.createElement(react_native_1.ActivityIndicator, { size: "large", color: theme?.primaryColor || '#4f46e5' }),
                 react_1.default.createElement(react_native_1.Text, { style: [styles.loadingText, { color: theme?.textColor || '#1e1b4b' }] }, strings.liveness.preparing || 'Preparing...'))));
     }
+    if (showFacePositioningGuide) {
+        return (react_1.default.createElement(FacePositioningGuide_1.FacePositioningGuide, { theme: theme, language: language, onContinue: () => setShowFacePositioningGuide(false), onCancel: onCancel }));
+    }
     return (react_1.default.createElement(VideoRecorder_1.VideoRecorder, { theme: theme, language: language, smartMode: true, challenges: currentChallenges, sessionId: sdk.getSessionId() || undefined, onComplete: handleVideoComplete, onCancel: handleVideoCancel, onFetchChallenges: handleFetchChallenges }));
 };
 exports.ProfilePictureCapture = ProfilePictureCapture;

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { ValidationProgress } from './components/ValidationProgress';
 export { ResultScreen } from './components/ResultScreen';
 export { ErrorScreen } from './components/ErrorScreen';
 export { InstructionsScreen } from './components/InstructionsScreen';
+export { FacePositioningGuide } from './components/FacePositioningGuide';
 export { useBiometricSDK } from './hooks/useBiometricSDK';
 export * from '@hexar/biometric-identity-sdk-core';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,OAAO,EAAE,MAAM,oCAAoC,CAAC;AAG7D,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,YAAY,EAAE,8BAA8B,EAAE,MAAM,oCAAoC,CAAC;AACzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAGrE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG1D,cAAc,oCAAoC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,OAAO,EAAE,MAAM,oCAAoC,CAAC;AAG7D,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,YAAY,EAAE,8BAA8B,EAAE,MAAM,oCAAoC,CAAC;AACzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAGzE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG1D,cAAc,oCAAoC,CAAC"}

package/dist/index.js

@@ -21,7 +21,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useBiometricSDK = exports.InstructionsScreen = exports.ErrorScreen = exports.ResultScreen = exports.ValidationProgress = exports.ProfilePictureCapture = exports.VideoRecorder = exports.CameraCapture = exports.default = exports.BiometricIdentityFlow = void 0;
+exports.useBiometricSDK = exports.FacePositioningGuide = exports.InstructionsScreen = exports.ErrorScreen = exports.ResultScreen = exports.ValidationProgress = exports.ProfilePictureCapture = exports.VideoRecorder = exports.CameraCapture = exports.default = exports.BiometricIdentityFlow = void 0;
 // Main component
 var BiometricIdentityFlow_1 = require("./components/BiometricIdentityFlow");
 Object.defineProperty(exports, "BiometricIdentityFlow", { enumerable: true, get: function () { return BiometricIdentityFlow_1.BiometricIdentityFlow; } });
@@ -42,6 +42,8 @@ var ErrorScreen_1 = require("./components/ErrorScreen");
 Object.defineProperty(exports, "ErrorScreen", { enumerable: true, get: function () { return ErrorScreen_1.ErrorScreen; } });
 var InstructionsScreen_1 = require("./components/InstructionsScreen");
 Object.defineProperty(exports, "InstructionsScreen", { enumerable: true, get: function () { return InstructionsScreen_1.InstructionsScreen; } });
+var FacePositioningGuide_1 = require("./components/FacePositioningGuide");
+Object.defineProperty(exports, "FacePositioningGuide", { enumerable: true, get: function () { return FacePositioningGuide_1.FacePositioningGuide; } });
 // Hooks
 var useBiometricSDK_1 = require("./hooks/useBiometricSDK");
 Object.defineProperty(exports, "useBiometricSDK", { enumerable: true, get: function () { return useBiometricSDK_1.useBiometricSDK; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexar/biometric-identity-sdk-react-native",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "React Native wrapper for Biometric Identity SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,7 +11,7 @@
     "clean": "rm -rf dist"
   },
   "peerDependencies": {
-    "@hexar/biometric-identity-sdk-core": ">=1.1.7",
+    "@hexar/biometric-identity-sdk-core": ">=1.2.0",
     "react": ">=18.0.0",
     "react-native": ">=0.70.0",
     "react-native-permissions": ">=4.0.0",

package/src/components/BiometricIdentityFlow.tsx

@@ -52,6 +52,7 @@ import { ValidationProgress } from './ValidationProgress';
 import { ResultScreen } from './ResultScreen';
 import { ErrorScreen } from './ErrorScreen';
 import { InstructionsScreen } from './InstructionsScreen';
+import { FacePositioningGuide } from './FacePositioningGuide';
 
 export interface BiometricIdentityFlowProps {
   onValidationComplete: (result: ValidationResult) => void;
@@ -94,6 +95,7 @@ export const BiometricIdentityFlow: React.FC<BiometricIdentityFlowProps> = ({
   const [showCamera, setShowCamera] = useState(false);
   const [cameraMode, setCameraMode] = useState<'front' | 'back' | 'video'>('front');
   const [showInstructions, setShowInstructions] = useState(true);
+  const [showFacePositioningGuide, setShowFacePositioningGuide] = useState(false);
   const [currentChallenges, setCurrentChallenges] = useState<ChallengeAction[]>([]);
   const [isLoadingChallenges, setIsLoadingChallenges] = useState(false);
   
@@ -147,8 +149,18 @@ export const BiometricIdentityFlow: React.FC<BiometricIdentityFlowProps> = ({
    */
   const handleCaptureStart = useCallback(async (mode: 'front' | 'back' | 'video') => {
     setCameraMode(mode);
-    
-    if (mode === 'video' && smartLivenessMode && isUsingBackend) {
+
+    if (mode === 'video') {
+      setShowFacePositioningGuide(true);
+      // Challenges will be loaded when guide is dismissed and we show camera
+    }
+
+    if (mode !== 'video') {
+      setShowCamera(true);
+      return;
+    }
+
+    if (smartLivenessMode && isUsingBackend) {
       setIsLoadingChallenges(true);
       try {
         const challenges = await fetchChallenges('active');
@@ -215,10 +227,13 @@ export const BiometricIdentityFlow: React.FC<BiometricIdentityFlowProps> = ({
       });
       setCurrentChallenges(translatedChallenges);
     }
-    
-    setShowCamera(true);
   }, [smartLivenessMode, isUsingBackend, fetchChallenges, sdk]);
 
+  const handleFacePositioningContinue = useCallback(() => {
+    setShowFacePositioningGuide(false);
+    setShowCamera(true);
+  }, []);
+
   /**
    * Handle capture completion
    */
@@ -341,6 +356,18 @@ export const BiometricIdentityFlow: React.FC<BiometricIdentityFlowProps> = ({
     );
   }
 
+  if (showFacePositioningGuide) {
+    return (
+      <FacePositioningGuide
+        theme={theme}
+        language={language}
+        onContinue={handleFacePositioningContinue}
+        onCancel={() => setShowFacePositioningGuide(false)}
+        styles={customStyles}
+      />
+    );
+  }
+
   if (showCamera) {
     if (cameraMode === 'video') {
       return (

package/src/components/FacePositioningGuide.tsx

@@ -0,0 +1,222 @@
+/**
+ * Face Positioning Guide Component
+ * Shared view that instructs users to keep their face inside the oval
+ * for better approval rate. Used before video capture in both
+ * BiometricIdentityFlow and ProfilePictureCapture.
+ */
+
+import React from 'react';
+import {
+  View,
+  Text,
+  StyleSheet,
+  TouchableOpacity,
+  ScrollView,
+  SafeAreaView,
+  ViewStyle,
+} from 'react-native';
+import { ThemeConfig, SupportedLanguage, getStrings, setLanguage } from '@hexar/biometric-identity-sdk-core';
+
+export interface FacePositioningGuideProps {
+  theme?: ThemeConfig;
+  language?: SupportedLanguage;
+  onContinue: () => void;
+  onCancel?: () => void;
+  styles?: {
+    container?: ViewStyle;
+    content?: ViewStyle;
+  };
+}
+
+export const FacePositioningGuide: React.FC<FacePositioningGuideProps> = ({
+  theme,
+  language,
+  onContinue,
+  onCancel,
+  styles: customStyles,
+}) => {
+  if (language) {
+    setLanguage(language);
+  }
+  const strings = getStrings();
+  const liveness = strings.liveness as Record<string, unknown> | undefined;
+  const guide = liveness?.facePositioningGuide as { title?: string; description?: string; tip?: string; continue?: string } | undefined;
+  const title = guide?.title ?? 'Position your face';
+  const description = guide?.description ?? 'Keep your face inside the oval for the best approval rate. Positioning your face outside the frame may reduce your chances of approval.';
+  const tip = guide?.tip ?? 'Face inside = better approval • Face outside = lower chances';
+  const continueLabel = guide?.continue ?? strings.common?.continue ?? 'Continue';
+
+  const primaryColor = theme?.primaryColor ?? '#6366F1';
+  const textColor = theme?.textColor ?? '#000000';
+  const secondaryTextColor = theme?.secondaryTextColor ?? '#6B7280';
+  const backgroundColor = theme?.backgroundColor ?? '#FFFFFF';
+
+  const styles = createStyles({
+    primaryColor,
+    textColor,
+    secondaryTextColor,
+    backgroundColor,
+  });
+
+  return (
+    <SafeAreaView style={[styles.container, customStyles?.container]}>
+      {onCancel && (
+        <TouchableOpacity style={styles.cancelButton} onPress={onCancel}>
+          <Text style={[styles.cancelText, { color: textColor }]}>
+            {strings.common?.cancel ?? 'Cancel'}
+          </Text>
+        </TouchableOpacity>
+      )}
+      <ScrollView
+        contentContainerStyle={[styles.scrollContent, customStyles?.content]}
+        showsVerticalScrollIndicator={false}
+      >
+        <Text style={[styles.title, { color: textColor }]}>{title}</Text>
+        <Text style={[styles.description, { color: secondaryTextColor }]}>
+          {description}
+        </Text>
+
+        {/* Oval frame with face icon inside */}
+        <View style={styles.ovalWrapper}>
+          <View style={[styles.oval, { borderColor: primaryColor }]}>
+            <FaceIcon color={secondaryTextColor} />
+          </View>
+        </View>
+
+        <View style={[styles.tipBox, { borderColor: primaryColor + '30', backgroundColor: primaryColor + '08' }]}>
+          <Text style={[styles.tipText, { color: secondaryTextColor }]}>{tip}</Text>
+        </View>
+
+        <TouchableOpacity
+          style={[styles.continueButton, { backgroundColor: primaryColor }]}
+          onPress={onContinue}
+          activeOpacity={0.85}
+        >
+          <Text style={styles.continueButtonText}>{continueLabel}</Text>
+        </TouchableOpacity>
+      </ScrollView>
+    </SafeAreaView>
+  );
+};
+
+/** Simple geometric face icon (head + eyes) when react-native-svg is not used */
+const FaceIcon: React.FC<{ color: string }> = ({ color }) => (
+  <View style={faceIconStyles.container}>
+    <View style={[faceIconStyles.head, { backgroundColor: color }]} />
+    <View style={faceIconStyles.eyes}>
+      <View style={[faceIconStyles.eye, { backgroundColor: color }]} />
+      <View style={[faceIconStyles.eye, { backgroundColor: color }]} />
+    </View>
+  </View>
+);
+
+const faceIconStyles = StyleSheet.create({
+  container: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  head: {
+    width: 80,
+    height: 100,
+    borderRadius: 50,
+    opacity: 0.4,
+  },
+  eyes: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    width: 44,
+    marginTop: -70,
+    opacity: 0.5,
+  },
+  eye: {
+    width: 12,
+    height: 12,
+    borderRadius: 6,
+  },
+});
+
+const createStyles = (vars: {
+  primaryColor: string;
+  textColor: string;
+  secondaryTextColor: string;
+  backgroundColor: string;
+}) =>
+  StyleSheet.create({
+    container: {
+      flex: 1,
+      backgroundColor: vars.backgroundColor,
+      zIndex: 9999,
+    },
+    cancelButton: {
+      alignSelf: 'flex-start',
+      paddingVertical: 12,
+      paddingHorizontal: 16,
+      marginTop: 8,
+    },
+    cancelText: {
+      fontSize: 16,
+      fontWeight: '500',
+    },
+    scrollContent: {
+      paddingHorizontal: 24,
+      paddingBottom: 40,
+      alignItems: 'center',
+    },
+    title: {
+      fontSize: 24,
+      fontWeight: '700',
+      marginBottom: 12,
+      textAlign: 'center',
+    },
+    description: {
+      fontSize: 16,
+      lineHeight: 24,
+      textAlign: 'center',
+      marginBottom: 28,
+      paddingHorizontal: 8,
+    },
+    ovalWrapper: {
+      marginBottom: 24,
+    },
+    oval: {
+      width: 260,
+      height: 320,
+      borderRadius: 160,
+      borderWidth: 3,
+      alignItems: 'center',
+      justifyContent: 'center',
+      overflow: 'hidden',
+    },
+    tipBox: {
+      paddingVertical: 14,
+      paddingHorizontal: 20,
+      borderRadius: 12,
+      borderWidth: 1,
+      marginBottom: 32,
+      alignSelf: 'stretch',
+    },
+    tipText: {
+      fontSize: 14,
+      fontWeight: '600',
+      textAlign: 'center',
+    },
+    continueButton: {
+      paddingVertical: 16,
+      paddingHorizontal: 32,
+      borderRadius: 12,
+      alignItems: 'center',
+      alignSelf: 'stretch',
+      shadowColor: '#000',
+      shadowOffset: { width: 0, height: 2 },
+      shadowOpacity: 0.1,
+      shadowRadius: 4,
+      elevation: 3,
+    },
+    continueButtonText: {
+      color: '#FFFFFF',
+      fontSize: 18,
+      fontWeight: '700',
+    },
+  });
+
+export default FacePositioningGuide;

package/src/components/ProfilePictureCapture.tsx

@@ -8,6 +8,7 @@ import {
   Animated,
 } from 'react-native';
 import { VideoRecorder, VideoRecordingResult } from './VideoRecorder';
+import { FacePositioningGuide } from './FacePositioningGuide';
 import { ThemeConfig, SupportedLanguage, getStrings, setLanguage, logger, BiometricError, BiometricErrorCode } from '@hexar/biometric-identity-sdk-core';
 import { useBiometricSDK } from '../hooks/useBiometricSDK';
 
@@ -42,6 +43,7 @@ export const ProfilePictureCapture: React.FC<ProfilePictureCaptureProps> = ({
     fetchChallenges,
   } = useBiometricSDK();
 
+  const [showFacePositioningGuide, setShowFacePositioningGuide] = useState(true);
   const [isValidating, setIsValidating] = useState(false);
   const [currentChallenges, setCurrentChallenges] = useState<any[]>([]);
   const [isLoadingChallenges, setIsLoadingChallenges] = useState(false);
@@ -323,7 +325,7 @@ export const ProfilePictureCapture: React.FC<ProfilePictureCaptureProps> = ({
     );
   }
 
-  // Wait for initialization and challenge loading before showing VideoRecorder
+  // Wait for initialization and challenge loading before showing guide or VideoRecorder
   if (!isInitialized || (isUsingBackend && isLoadingChallenges)) {
     return (
       <SafeAreaView style={[styles.container, { backgroundColor: theme?.backgroundColor || '#FFFFFF' }]}>
@@ -337,6 +339,17 @@ export const ProfilePictureCapture: React.FC<ProfilePictureCaptureProps> = ({
     );
   }
 
+  if (showFacePositioningGuide) {
+    return (
+      <FacePositioningGuide
+        theme={theme}
+        language={language}
+        onContinue={() => setShowFacePositioningGuide(false)}
+        onCancel={onCancel}
+      />
+    );
+  }
+
   return (
     <VideoRecorder
       theme={theme}

package/src/index.ts

@@ -16,6 +16,7 @@ export { ValidationProgress } from './components/ValidationProgress';
 export { ResultScreen } from './components/ResultScreen';
 export { ErrorScreen } from './components/ErrorScreen';
 export { InstructionsScreen } from './components/InstructionsScreen';
+export { FacePositioningGuide } from './components/FacePositioningGuide';
 
 // Hooks
 export { useBiometricSDK } from './hooks/useBiometricSDK';