@aws-amplify/ui-react-liveness 3.4.6 → 3.5.0

package/dist/esm/components/FaceLivenessDetector/service/machine/machine.mjs

@@ -19,6 +19,17 @@ import { TelemetryReporter } from '../utils/TelemetryReporter/TelemetryReporter.
 const CAMERA_ID_KEY = 'AmplifyLivenessCameraId';
 const DEFAULT_FACE_FIT_TIMEOUT = 7000;
 let responseStream;
+// Helper function to get selected device info
+const getSelectedDeviceInfo = (context) => {
+    const selected = context.videoAssociatedParams?.selectableDevices?.find((d) => d.deviceId === context.videoAssociatedParams?.selectedDeviceId);
+    return selected
+        ? {
+            deviceId: selected.deviceId,
+            groupId: selected.groupId,
+            label: selected.label ?? '',
+        }
+        : undefined;
+};
 const responseStreamActor = async (callback) => {
     try {
         const stream = await responseStream;
@@ -79,6 +90,9 @@ const responseStreamActor = async (callback) => {
         }
     }
 };
+function getLastSelectedCameraId() {
+    return localStorage.getItem(CAMERA_ID_KEY);
+}
 function setLastSelectedCameraId(deviceId) {
     localStorage.setItem(CAMERA_ID_KEY, deviceId);
 }
@@ -631,6 +645,9 @@ const livenessMachine = createMachine({
                 if (event.data.message.includes('15 fps')) {
                     errorState = LivenessErrorState.CAMERA_FRAMERATE_ERROR;
                 }
+                else if (event.data.message.includes(LivenessErrorState.DEFAULT_CAMERA_NOT_FOUND_ERROR)) {
+                    errorState = LivenessErrorState.DEFAULT_CAMERA_NOT_FOUND_ERROR;
+                }
                 else {
                     errorState = LivenessErrorState.CAMERA_ACCESS_ERROR;
                 }
@@ -640,15 +657,26 @@ const livenessMachine = createMachine({
                     state: errorState,
                     error: error,
                 };
-                context.componentProps.onError?.(livenessError);
+                context.componentProps.onError?.(livenessError, getSelectedDeviceInfo(context));
                 return errorState;
             },
         }),
         callMobileLandscapeWarningCallback: assign({
             errorState: () => LivenessErrorState.MOBILE_LANDSCAPE_ERROR,
         }),
+        getSelectedDeviceInfo: (context) => getSelectedDeviceInfo(context),
         callUserCancelCallback: (context) => {
-            context.componentProps.onUserCancel?.();
+            const { onUserCancel } = context.componentProps ?? {};
+            if (!onUserCancel) {
+                return;
+            }
+            try {
+                onUserCancel();
+            }
+            catch (callbackError) {
+                // eslint-disable-next-line no-console
+                console.error('Error in onUserCancel callback:', callbackError);
+            }
         },
         callUserTimeoutCallback: (context) => {
             const error = new Error(context.errorMessage ?? 'Client Timeout');
@@ -657,14 +685,14 @@ const livenessMachine = createMachine({
                 state: context.errorState,
                 error: error,
             };
-            context.componentProps.onError?.(livenessError);
+            context.componentProps.onError?.(livenessError, getSelectedDeviceInfo(context));
         },
         callErrorCallback: (context, event) => {
             const livenessError = {
                 state: context.errorState,
                 error: event.data?.error || event.data,
             };
-            context.componentProps.onError?.(livenessError);
+            context.componentProps.onError?.(livenessError, getSelectedDeviceInfo(context));
         },
         cleanUpResources: (context) => {
             const { freshnessColorEl } = context.freshnessColorAssociatedParams;
@@ -775,10 +803,42 @@ const livenessMachine = createMachine({
     services: {
         async checkVirtualCameraAndGetStream(context) {
             const { videoConstraints } = context.videoAssociatedParams;
-            // Get initial stream to enumerate devices with non-empty labels
-            const initialStream = await navigator.mediaDevices.getUserMedia({
-                video: { ...videoConstraints },
+            const { componentProps } = context;
+            let targetDeviceId;
+            let cameraNotFound = false;
+            if (componentProps?.config?.deviceId) {
+                targetDeviceId = componentProps.config.deviceId;
+            }
+            else {
+                targetDeviceId = getLastSelectedCameraId() ?? undefined;
+            }
+            const initialStream = await navigator.mediaDevices
+                .getUserMedia({
+                video: {
+                    ...videoConstraints,
+                    ...(targetDeviceId
+                        ? { deviceId: { exact: targetDeviceId } }
+                        : {}),
+                },
                 audio: false,
+            })
+                .catch((error) => {
+                if (error instanceof DOMException &&
+                    (error.name === 'NotFoundError' ||
+                        error.name === 'OverconstrainedError')) {
+                    // Mark camera as not found when a specific target device (either provided via props
+                    // or previously selected/saved as default) cannot be accessed.
+                    if (targetDeviceId && !cameraNotFound) {
+                        cameraNotFound = true;
+                    }
+                    return navigator.mediaDevices.getUserMedia({
+                        video: {
+                            ...videoConstraints,
+                        },
+                        audio: false,
+                    });
+                }
+                throw error;
             });
             const devices = await navigator.mediaDevices.enumerateDevices();
             const realVideoDevices = devices
@@ -792,7 +852,7 @@ const livenessMachine = createMachine({
                 .getTracks()
                 .filter((track) => {
                 const settings = track.getSettings();
-                return settings.frameRate >= 15;
+                return (settings.frameRate ?? 0) >= 15;
             });
             if (tracksWithMoreThan15Fps.length < 1) {
                 throw new Error('No camera found with more than 15 fps');
@@ -811,11 +871,16 @@ const livenessMachine = createMachine({
                 });
             }
             setLastSelectedCameraId(deviceId);
-            return {
+            const result = {
                 stream: realVideoDeviceStream,
                 selectedDeviceId: initialStreamDeviceId,
                 selectableDevices: realVideoDevices,
             };
+            // If a specific camera was requested but not found, trigger a specific error
+            if (cameraNotFound) {
+                throw new Error(LivenessErrorState.DEFAULT_CAMERA_NOT_FOUND_ERROR);
+            }
+            return result;
         },
         // eslint-disable-next-line @typescript-eslint/require-await
         async openLivenessStreamConnection(context) {
@@ -1068,11 +1133,22 @@ const livenessMachine = createMachine({
             livenessStreamProvider.dispatchStreamEvent({ type: 'streamStop' });
         },
         async getLiveness(context) {
-            const { onAnalysisComplete } = context.componentProps;
-            // Get liveness result
-            await onAnalysisComplete();
+            const { onAnalysisComplete } = context.componentProps ?? {};
+            if (!onAnalysisComplete) {
+                return;
+            }
+            try {
+                const deviceInfo = getSelectedDeviceInfo(context);
+                await onAnalysisComplete(deviceInfo);
+            }
+            catch (callbackError) {
+                // eslint-disable-next-line no-console
+                console.error('Error in onAnalysisComplete callback:', callbackError);
+                // Rethrow to allow the state machine to handle the error
+                throw callbackError;
+            }
         },
     },
 });
 
-export { livenessMachine };
+export { getSelectedDeviceInfo, livenessMachine };

package/dist/esm/components/FaceLivenessDetector/service/types/error.mjs

@@ -11,6 +11,7 @@ const LivenessErrorState = {
     FACE_DISTANCE_ERROR: 'FACE_DISTANCE_ERROR',
     MOBILE_LANDSCAPE_ERROR: 'MOBILE_LANDSCAPE_ERROR',
     MULTIPLE_FACES_ERROR: 'MULTIPLE_FACES_ERROR',
+    DEFAULT_CAMERA_NOT_FOUND_ERROR: 'DEFAULT_CAMERA_NOT_FOUND_ERROR',
 };
 
 export { LivenessErrorState };

package/dist/esm/version.mjs

@@ -1,3 +1,3 @@
-const VERSION = '3.4.6';
+const VERSION = '3.5.0';
 
 export { VERSION };

package/dist/index.js

@@ -92,6 +92,7 @@ const LivenessErrorState = {
     FACE_DISTANCE_ERROR: 'FACE_DISTANCE_ERROR',
     MOBILE_LANDSCAPE_ERROR: 'MOBILE_LANDSCAPE_ERROR',
     MULTIPLE_FACES_ERROR: 'MULTIPLE_FACES_ERROR',
+    DEFAULT_CAMERA_NOT_FOUND_ERROR: 'DEFAULT_CAMERA_NOT_FOUND_ERROR',
 };
 
 // Face distance is calculated as pupilDistance / ovalWidth.
@@ -1055,7 +1056,7 @@ function createRequestStreamGenerator(stream) {
     };
 }
 
-const VERSION = '3.4.6';
+const VERSION = '3.5.0';
 
 const BASE_USER_AGENT = `ui-react-liveness/${VERSION}`;
 const getLivenessUserAgent = () => {
@@ -1610,6 +1611,17 @@ const STATIC_VIDEO_CONSTRAINTS = {
 const CAMERA_ID_KEY = 'AmplifyLivenessCameraId';
 const DEFAULT_FACE_FIT_TIMEOUT = 7000;
 let responseStream;
+// Helper function to get selected device info
+const getSelectedDeviceInfo = (context) => {
+    const selected = context.videoAssociatedParams?.selectableDevices?.find((d) => d.deviceId === context.videoAssociatedParams?.selectedDeviceId);
+    return selected
+        ? {
+            deviceId: selected.deviceId,
+            groupId: selected.groupId,
+            label: selected.label ?? '',
+        }
+        : undefined;
+};
 const responseStreamActor = async (callback) => {
     try {
         const stream = await responseStream;
@@ -1670,6 +1682,9 @@ const responseStreamActor = async (callback) => {
         }
     }
 };
+function getLastSelectedCameraId() {
+    return localStorage.getItem(CAMERA_ID_KEY);
+}
 function setLastSelectedCameraId(deviceId) {
     localStorage.setItem(CAMERA_ID_KEY, deviceId);
 }
@@ -2222,6 +2237,9 @@ const livenessMachine = xstate.createMachine({
                 if (event.data.message.includes('15 fps')) {
                     errorState = LivenessErrorState.CAMERA_FRAMERATE_ERROR;
                 }
+                else if (event.data.message.includes(LivenessErrorState.DEFAULT_CAMERA_NOT_FOUND_ERROR)) {
+                    errorState = LivenessErrorState.DEFAULT_CAMERA_NOT_FOUND_ERROR;
+                }
                 else {
                     errorState = LivenessErrorState.CAMERA_ACCESS_ERROR;
                 }
@@ -2231,15 +2249,26 @@ const livenessMachine = xstate.createMachine({
                     state: errorState,
                     error: error,
                 };
-                context.componentProps.onError?.(livenessError);
+                context.componentProps.onError?.(livenessError, getSelectedDeviceInfo(context));
                 return errorState;
             },
         }),
         callMobileLandscapeWarningCallback: xstate.assign({
             errorState: () => LivenessErrorState.MOBILE_LANDSCAPE_ERROR,
         }),
+        getSelectedDeviceInfo: (context) => getSelectedDeviceInfo(context),
         callUserCancelCallback: (context) => {
-            context.componentProps.onUserCancel?.();
+            const { onUserCancel } = context.componentProps ?? {};
+            if (!onUserCancel) {
+                return;
+            }
+            try {
+                onUserCancel();
+            }
+            catch (callbackError) {
+                // eslint-disable-next-line no-console
+                console.error('Error in onUserCancel callback:', callbackError);
+            }
         },
         callUserTimeoutCallback: (context) => {
             const error = new Error(context.errorMessage ?? 'Client Timeout');
@@ -2248,14 +2277,14 @@ const livenessMachine = xstate.createMachine({
                 state: context.errorState,
                 error: error,
             };
-            context.componentProps.onError?.(livenessError);
+            context.componentProps.onError?.(livenessError, getSelectedDeviceInfo(context));
         },
         callErrorCallback: (context, event) => {
             const livenessError = {
                 state: context.errorState,
                 error: event.data?.error || event.data,
             };
-            context.componentProps.onError?.(livenessError);
+            context.componentProps.onError?.(livenessError, getSelectedDeviceInfo(context));
         },
         cleanUpResources: (context) => {
             const { freshnessColorEl } = context.freshnessColorAssociatedParams;
@@ -2366,10 +2395,42 @@ const livenessMachine = xstate.createMachine({
     services: {
         async checkVirtualCameraAndGetStream(context) {
             const { videoConstraints } = context.videoAssociatedParams;
-            // Get initial stream to enumerate devices with non-empty labels
-            const initialStream = await navigator.mediaDevices.getUserMedia({
-                video: { ...videoConstraints },
+            const { componentProps } = context;
+            let targetDeviceId;
+            let cameraNotFound = false;
+            if (componentProps?.config?.deviceId) {
+                targetDeviceId = componentProps.config.deviceId;
+            }
+            else {
+                targetDeviceId = getLastSelectedCameraId() ?? undefined;
+            }
+            const initialStream = await navigator.mediaDevices
+                .getUserMedia({
+                video: {
+                    ...videoConstraints,
+                    ...(targetDeviceId
+                        ? { deviceId: { exact: targetDeviceId } }
+                        : {}),
+                },
                 audio: false,
+            })
+                .catch((error) => {
+                if (error instanceof DOMException &&
+                    (error.name === 'NotFoundError' ||
+                        error.name === 'OverconstrainedError')) {
+                    // Mark camera as not found when a specific target device (either provided via props
+                    // or previously selected/saved as default) cannot be accessed.
+                    if (targetDeviceId && !cameraNotFound) {
+                        cameraNotFound = true;
+                    }
+                    return navigator.mediaDevices.getUserMedia({
+                        video: {
+                            ...videoConstraints,
+                        },
+                        audio: false,
+                    });
+                }
+                throw error;
             });
             const devices = await navigator.mediaDevices.enumerateDevices();
             const realVideoDevices = devices
@@ -2383,7 +2444,7 @@ const livenessMachine = xstate.createMachine({
                 .getTracks()
                 .filter((track) => {
                 const settings = track.getSettings();
-                return settings.frameRate >= 15;
+                return (settings.frameRate ?? 0) >= 15;
             });
             if (tracksWithMoreThan15Fps.length < 1) {
                 throw new Error('No camera found with more than 15 fps');
@@ -2402,11 +2463,16 @@ const livenessMachine = xstate.createMachine({
                 });
             }
             setLastSelectedCameraId(deviceId);
-            return {
+            const result = {
                 stream: realVideoDeviceStream,
                 selectedDeviceId: initialStreamDeviceId,
                 selectableDevices: realVideoDevices,
             };
+            // If a specific camera was requested but not found, trigger a specific error
+            if (cameraNotFound) {
+                throw new Error(LivenessErrorState.DEFAULT_CAMERA_NOT_FOUND_ERROR);
+            }
+            return result;
         },
         // eslint-disable-next-line @typescript-eslint/require-await
         async openLivenessStreamConnection(context) {
@@ -2659,9 +2725,20 @@ const livenessMachine = xstate.createMachine({
             livenessStreamProvider.dispatchStreamEvent({ type: 'streamStop' });
         },
         async getLiveness(context) {
-            const { onAnalysisComplete } = context.componentProps;
-            // Get liveness result
-            await onAnalysisComplete();
+            const { onAnalysisComplete } = context.componentProps ?? {};
+            if (!onAnalysisComplete) {
+                return;
+            }
+            try {
+                const deviceInfo = getSelectedDeviceInfo(context);
+                await onAnalysisComplete(deviceInfo);
+            }
+            catch (callbackError) {
+                // eslint-disable-next-line no-console
+                console.error('Error in onAnalysisComplete callback:', callbackError);
+                // Rethrow to allow the state machine to handle the error
+                throw callbackError;
+            }
         },
     },
 });

package/dist/types/components/FaceLivenessDetector/service/machine/machine.d.ts

@@ -1,4 +1,5 @@
-import type { LivenessContext, LivenessEvent } from '../types';
+import type { LivenessContext, LivenessEvent, DeviceInfo } from '../types';
+export declare const getSelectedDeviceInfo: (context: LivenessContext) => DeviceInfo | undefined;
 export declare const livenessMachine: import("xstate").StateMachine<LivenessContext, any, LivenessEvent, {
     value: any;
     context: LivenessContext;

package/dist/types/components/FaceLivenessDetector/service/types/error.d.ts

@@ -12,5 +12,6 @@ export declare const LivenessErrorState: {
     readonly FACE_DISTANCE_ERROR: "FACE_DISTANCE_ERROR";
     readonly MOBILE_LANDSCAPE_ERROR: "MOBILE_LANDSCAPE_ERROR";
     readonly MULTIPLE_FACES_ERROR: "MULTIPLE_FACES_ERROR";
+    readonly DEFAULT_CAMERA_NOT_FOUND_ERROR: "DEFAULT_CAMERA_NOT_FOUND_ERROR";
 };
 export type ErrorState = keyof typeof LivenessErrorState;

package/dist/types/components/FaceLivenessDetector/service/types/liveness.d.ts

@@ -1,5 +1,10 @@
 import type { AwsCredentialProvider } from './credentials';
 import type { ErrorState } from './error';
+export interface DeviceInfo {
+    deviceId: string;
+    groupId: string;
+    label: string;
+}
 /**
  * The props for the FaceLivenessDetectorCore which allows for full configuration of auth
  */
@@ -11,8 +16,9 @@ export interface FaceLivenessDetectorCoreProps {
     /**
      * Callback that signals when the liveness session has completed analysis.
      * At this point a request can be made to GetFaceLivenessSessionResults.
+     * @param deviceInfo Information about the selected device
      */
-    onAnalysisComplete: () => Promise<void>;
+    onAnalysisComplete: (deviceInfo?: DeviceInfo) => Promise<void>;
     /**
      * The AWS region to stream the video to, for current regional support see the documentation here: FIXME LINK
      */
@@ -22,9 +28,11 @@ export interface FaceLivenessDetectorCoreProps {
      */
     onUserCancel?: () => void;
     /**
-     * Callback called when there is error occured on any step
+     * Callback called when there is an error on any step
+     * @param livenessError The error that occurred
+     * @param deviceInfo Information about the selected device, if available
      */
-    onError?: (livenessError: LivenessError) => void;
+    onError?: (livenessError: LivenessError, deviceInfo?: DeviceInfo) => void;
     /**
      * Optional parameter for the disabling the Start/Get Ready Screen, default: false
      */
@@ -44,6 +52,10 @@ export type FaceLivenessDetectorProps = Omit<FaceLivenessDetectorCoreProps, 'con
     config?: FaceLivenessDetectorConfig;
 };
 export interface FaceLivenessDetectorCoreConfig {
+    /**
+     * Optional device ID to pre-select a camera
+     */
+    deviceId?: string;
     /**
      * overrides the Wasm backend binary CDN path
      * default is https://cdn.jsdelivr.net/npm/@tensorflow/tfjs-backend-wasm@3.11.0/dist/.

package/dist/types/components/FaceLivenessDetector/service/types/machine.d.ts

@@ -66,7 +66,7 @@ export interface LivenessContext {
     shouldDisconnect: boolean | undefined;
     videoAssociatedParams: VideoAssociatedParams | undefined;
 }
-export type LivenessEventTypes = 'BEGIN' | 'CONNECTION_TIMEOUT' | 'START_RECORDING' | 'TIMEOUT' | 'ERROR' | 'CANCEL' | 'SET_SESSION_INFO' | 'DISCONNECT_EVENT' | 'SET_DOM_AND_CAMERA_DETAILS' | 'UPDATE_DEVICE_AND_STREAM' | 'SERVER_ERROR' | 'RUNTIME_ERROR' | 'RETRY_CAMERA_CHECK' | 'MOBILE_LANDSCAPE_WARNING';
+export type LivenessEventTypes = 'BEGIN' | 'CONNECTION_TIMEOUT' | 'START_RECORDING' | 'TIMEOUT' | 'ERROR' | 'CANCEL' | 'SET_SESSION_INFO' | 'DISCONNECT_EVENT' | 'SET_DOM_AND_CAMERA_DETAILS' | 'UPDATE_DEVICE_AND_STREAM' | 'CAMERA_NOT_FOUND' | 'SERVER_ERROR' | 'RUNTIME_ERROR' | 'RETRY_CAMERA_CHECK' | 'MOBILE_LANDSCAPE_WARNING';
 export type LivenessEventData = Record<PropertyKey, any>;
 export interface LivenessEvent {
     type: LivenessEventTypes;

package/dist/types/components/FaceLivenessDetector/service/utils/liveness.d.ts

@@ -76,6 +76,7 @@ export declare const LivenessErrorStateStringMap: {
     CAMERA_ACCESS_ERROR: string;
     MOBILE_LANDSCAPE_ERROR: string;
     FRESHNESS_TIMEOUT: string;
+    DEFAULT_CAMERA_NOT_FOUND_ERROR: string;
 };
 interface FillOverlayCanvasFractionalInput {
     overlayCanvas: HTMLCanvasElement;

package/dist/types/components/FaceLivenessDetector/shared/Hint.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { IlluminationState, FaceMatchState } from '../service';
 import type { HintDisplayText } from '../displayText';
-export declare const selectErrorState: import("../hooks").LivenessSelectorFn<"CONNECTION_TIMEOUT" | "TIMEOUT" | "RUNTIME_ERROR" | "FRESHNESS_TIMEOUT" | "SERVER_ERROR" | "CAMERA_FRAMERATE_ERROR" | "CAMERA_ACCESS_ERROR" | "FACE_DISTANCE_ERROR" | "MOBILE_LANDSCAPE_ERROR" | "MULTIPLE_FACES_ERROR" | undefined>;
+export declare const selectErrorState: import("../hooks").LivenessSelectorFn<"CONNECTION_TIMEOUT" | "TIMEOUT" | "RUNTIME_ERROR" | "FRESHNESS_TIMEOUT" | "SERVER_ERROR" | "CAMERA_FRAMERATE_ERROR" | "CAMERA_ACCESS_ERROR" | "FACE_DISTANCE_ERROR" | "MOBILE_LANDSCAPE_ERROR" | "MULTIPLE_FACES_ERROR" | "DEFAULT_CAMERA_NOT_FOUND_ERROR" | undefined>;
 export declare const selectFaceMatchState: import("../hooks").LivenessSelectorFn<FaceMatchState | undefined>;
 export declare const selectIlluminationState: import("../hooks").LivenessSelectorFn<IlluminationState | undefined>;
 export declare const selectIsFaceFarEnoughBeforeRecording: import("../hooks").LivenessSelectorFn<boolean | undefined>;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "3.4.6";
+export declare const VERSION = "3.5.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-amplify/ui-react-liveness",
-  "version": "3.4.6",
+  "version": "3.5.0",
   "main": "dist/index.js",
   "module": "dist/esm/index.mjs",
   "exports": {
@@ -48,8 +48,8 @@
     "react-dom": "^16.14 || ^17 || ^18 || ^19"
   },
   "dependencies": {
-    "@aws-amplify/ui": "6.12.0",
-    "@aws-amplify/ui-react": "6.13.0",
+    "@aws-amplify/ui": "6.13.0",
+    "@aws-amplify/ui-react": "6.13.2",
     "@aws-sdk/client-rekognitionstreaming": "3.828.0",
     "@aws-sdk/util-format-url": "3.609.0",
     "@smithy/eventstream-serde-browser": "^4.0.4",
@@ -85,4 +85,4 @@
       "limit": "225 kB"
     }
   ]
-}
+}