Liveness (selfie biométrica)

Captura de selfie biométrica com verificação de liveness integrada. O SDK guia o usuário até que um frame biometricamente válido seja obtido via SmartFrames e retorna a imagem como Base64 + JWT.

Capacidade

Este tipo de captura utiliza a capacidade de Liveness. Para uma visão conceitual de como o Liveness funciona, consulte a página da capacidade Liveness.

Como funciona

O SDK gerencia toda a sessão de captura:

1. Abre a câmera com a sobreposição SmartFrame.
2. Orienta o usuário a posicionar o rosto dentro do frame.
3. Valida o liveness — a sessão só é concluída quando o usuário está fisicamente presente.
4. Retorna um objeto com base64 (prévia) e encrypted (JWT para a API) via o callback success.

Modo de câmera (smart vs normal)

O Web expõe dois modos de câmera via SelfieCameraTypes:

• SelfieCameraTypes.NORMAL — modo de câmera padrão (captura manual).
• SelfieCameraTypes.SMART — modo de câmera inteligente com captura automática e orientação por silhueta.

Ao usar SMART, você também deve carregar os modelos de visão computacional via setModelsPath durante a inicialização.

Iniciando uma captura de liveness

Passo 1 — Implementar o objeto callback

O Web SDK utiliza um objeto callback — passado para open() — para tratar eventos de sucesso e erro. Ambos os handlers são obrigatórios:

Handler	Quando é chamado
on.success(obj)	Captura concluída com sucesso — recebe um objeto com base64 e encrypted
on.error(error)	Ocorreu um erro durante a sessão — recebe um ErrorBio

const callback = {
  on: {
    success: (obj) => {
      console.log(obj.base64);
      console.log(obj.encrypted);
    },
    error: (error) => {
      console.error(error);
    }
  }
};

callback obrigatório

O objeto callback é obrigatório. Se não for implementado corretamente (cobrindo os eventos success e error), o SDK lança uma exceção que, se não tratada, é exibida no console do usuário.

Passo 2 — Construir a câmera e preparar a sessão de selfie

Construa a instância da câmera e chame prepareSelfieCamera passando o UnicoConfig e o SelfieCameraTypes desejado:

Expiração do token

O intervalo entre a geração do encrypted e o envio para a API não deve exceder 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);
});

dica

Para otimizar a inicialização da câmera, você pode separar as chamadas para prepareSelfieCamera() e open() — mantendo o passo de preparação aquecido enquanto o usuário navega até a tela de captura.

Passo 3 — (opcional) Usar dentro de um iFrame

O Web SDK suporta Liveness Interativo embutido em um iFrame via prepareSelfieCameraForIFrame():

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

Implemente o elemento <iframe> com as permissões necessárias:

<iframe allow="fullscreen;camera;geolocation" allowFullScreen src="your_app_url"></iframe>

O método deve corresponder ao contexto

prepareSelfieCameraForIFrame() só funciona dentro de um iFrame — usá-lo fora resulta no erro 73724. Da mesma forma, usar prepareSelfieCamera() dentro de um iFrame também resulta no erro 73724.

Tela cheia no iPhone

Para realizar a captura, a página deve estar em modo tela cheia para que o SDK possa redimensionar automaticamente. A Apple restringe o uso de APIs de tela cheia especificamente no iPhone (iPads são aceitáveis). Para capturas no iPhone, configure manualmente o posicionamento do iFrame.

Para o tratamento completo do resultado, consulte Recebendo o resultado.