Saltar al contenido principal

Liveness (selfie biométrica)

Captura de selfie biométrica con verificación de liveness integrada. El SDK guía al usuario hasta obtener un fotograma biométricamente válido mediante SmartFrames y devuelve la imagen en Base64 + JWT.

Capacidad

Este tipo de captura utiliza la capacidad Liveness. Para una descripción conceptual de cómo funciona Liveness, consulta la página de la capacidad Liveness.

Cómo funciona

El SDK gestiona la sesión de captura completa:

  1. Abre la cámara con la superposición SmartFrame.
  2. Guía al usuario para que posicione su rostro dentro del marco.
  3. Valida el liveness — la sesión solo se completa cuando el usuario está físicamente presente.
  4. Devuelve un objeto con base64 (vista previa) y encrypted (JWT para la API) a través del callback success.
Modo de cámara (smart vs normal)

Web expone dos modos de cámara a través de SelfieCameraTypes:

  • SelfieCameraTypes.NORMAL — modo de cámara estándar (captura manual).
  • SelfieCameraTypes.SMART — modo de cámara inteligente con captura automática y guía de silueta.

Al usar SMART, también debes cargar los modelos de visión computacional mediante setModelsPath durante la inicialización.

Iniciar una captura de liveness
Paso 1 — Implementar el objeto callback

El Web SDK utiliza un objeto callback — pasado a open() — para gestionar los eventos de éxito y error. Ambos manejadores son obligatorios:

ManejadorCuándo se llama
on.success(obj)La captura se completó correctamente — recibe un objeto con base64 y encrypted
on.error(error)Ocurrió un error durante la sesión — recibe un ErrorBio
const callback = {
  on: {
    success: (obj) => {
      console.log(obj.base64);
      console.log(obj.encrypted);
    },
    error: (error) => {
      console.error(error);
    }
  }
};
Callback obligatorio

El objeto callback es obligatorio. Si no se implementa correctamente (cubriendo tanto los eventos success como error), el SDK lanza una excepción que, si no se maneja, se muestra en la consola del usuario.

Paso 2 — Construir la cámara y preparar la sesión de selfie

Construye la instancia de la cámara y llama a prepareSelfieCamera pasando el UnicoConfig y el SelfieCameraTypes deseado:

Expiración del token

El intervalo entre la generación de encrypted y su envío a la API no debe superar 10 minutos.

const unicoCamera = unicoCameraBuilder.build();

const config = new UnicoConfig()
  .setHostname("<YOUR_HOSTNAME>")
  .setHostKey("<YOUR_HOST_KEY>");

unicoCamera.prepareSelfieCamera(
  config,
  SelfieCameraTypes.SMART
).then(cameraOpener => {
  cameraOpener.open(callback);
}).catch(error => {
  console.error(error);
});
consejo

Para optimizar el inicio de la cámara, puedes separar las llamadas a prepareSelfieCamera() y open() — manteniendo el paso de preparación activo mientras el usuario navega hasta la pantalla de captura.

Paso 3 — (opcional) Usar dentro de un iFrame

El SDK Web admite Interactive Liveness integrado en un iFrame a través de prepareSelfieCameraForIFrame():

unicoCamera.prepareSelfieCameraForIFrame(
  config,
  SelfieCameraTypes.SMART
).then(cameraOpener => {
  cameraOpener.open(callback);
}).catch(error => {
  console.error(error);
});

Implementa el elemento <iframe> con los permisos requeridos:

<iframe allow="fullscreen;camera;geolocation" allowFullScreen src="your_app_url"></iframe>
El método debe coincidir con el contexto

prepareSelfieCameraForIFrame() solo funciona dentro de un iFrame — usarlo fuera resulta en el error 73724. Del mismo modo, usar prepareSelfieCamera() dentro de un iFrame también resulta en el error 73724.

Pantalla completa en iPhone

Para realizar la captura, la página debe estar en modo de pantalla completa para que el SDK pueda redimensionarse automáticamente. Apple restringe el uso de las APIs de pantalla completa específicamente en iPhones (los iPad son aceptables). Para capturas en iPhones, configura manualmente el posicionamiento del iFrame.

Para el manejo completo del resultado, consulta Recibir el resultado.

Última actualización el