# BioDoc Liveness

# Liveness 1.0

# Como aplicar

Para aplicar o Liveness 1.0, basta ativar o parâmetro correspondente no menu "Empresas" da empresa ou do local de captura desejado. Nenhuma configuração adicional é necessária para ativação.

# Como funciona

O Liveness 1.0 realiza uma série de verificações automáticas para garantir que a imagem capturada seja de uma pessoa real e que o processo de captura foi realizado de forma adequada. Veja abaixo o fluxo detalhado:

  1. Validação Inicial Após receber o JSON da imagem em formato Base64, o sistema faz uma verificação inicial para garantir que não haja erros, como:

    • Ausência de dados obrigatórios;
    • Inserção incorreta de Base64;
    • Problemas na requisição.

  2. Pré-Análise (Opcional) Por padrão, o sistema realiza uma pré-análise da imagem. Se essa opção estiver ativada, o sistema gera:

    • Uma imagem sem fundo (background removido);
    • Uma imagem com os rostos detectados.

  3. Verificação de Rostos A primeira análise busca confirmar a presença de rostos na imagem. Se nenhum rosto for detectado, o sistema retornará um erro, informando a ausência de faces.

  4. Verificação dos Olhos A segunda análise avalia se os olhos do usuário estão visíveis ou bloqueados de alguma forma.

  5. Detecção de Foto de Foto O sistema verifica se um celular está presente na captura. Se for detectado o uso de um celular na foto (tentativa de "foto de foto"), um erro é retornado.

  6. Verificação de Iluminação A imagem é analisada quanto à quantidade de iluminação, comparando com um limite mínimo pré-definido com base em testes. Se a iluminação for insuficiente, o sistema retornará um erro.

  7. Verificação de Distância O sistema calcula a distância do usuário até a câmera, levando em consideração as dimensões da imagem. Diferentes tipos de câmeras (como de celular) possuem distâncias focais distintas, por isso um limite é ajustado conforme o tipo de dispositivo detectado.

  8. Verificação de Liveness Por fim, o sistema realiza a verificação de liveness. A imagem é processada por um modelo de machine learning treinado para detectar se a face capturada é real ou uma tentativa de fraude.

    • Se a verificação for bem-sucedida, o sistema retorna um JSON com o resultado "real" e a pontuação de confiança (0 a 100).
    • Caso contrário, o sistema retornará a mensagem "FACE VIVA NÃO DETECTADA. Por favor, centralize o rosto na câmera", junto com a pontuação de confiança do modelo.

Se o parâmetro de pré-análise estiver desativado, as cinco etapas anteriores são ignoradas, e o sistema faz apenas a análise de liveness diretamente.

# Como ele trabalha

O Liveness 1.0 funciona recebendo uma imagem em formato Base64 via JSON. A imagem passa por várias etapas de verificação, que incluem desde a análise da presença de rostos até a validação de condições de iluminação e distância. O ponto final é a verificação de liveness, que utiliza um modelo treinado para confirmar se a face capturada pertence a uma pessoa viva.

Este processo garante que a imagem capturada esteja livre de fraudes, como o uso de fotos ou vídeos falsos, e que o usuário está fisicamente presente no momento da verificação.



# Liveness 2.0

O BioDoc Liveness 2.0 oferece uma verificação facial avançada, confirmando que o usuário está presente fisicamente em frente à câmera e prevenindo tentativas de fraude, como o uso de fotos ou vídeos falsos. Essa solução realiza uma análise em tempo real por meio de um vídeo selfie e fornece uma pontuação de confiança (de 0 a 100), além de gerar uma imagem de referência para comparações faciais futuras.

# Especificações mínimas recomendadas

# Dispositivos

  • O dispositivo deve ter uma câmera frontal.
  • Taxa de atualização mínima da tela do dispositivo: 60 Hz.
  • Tamanho mínimo da tela: 4 polegadas.
  • O dispositivo não deve estar com jailbreak ou root.

# Especificações da câmera

  • Câmera colorida: a câmera frontal deve ser capaz de gravar em cores.
  • Não é permitido o uso de câmera virtual ou software de câmera.
  • Capacidade mínima de gravação: 15 quadros por segundo.
  • Resolução mínima de gravação de vídeo: 320x240px.
  • Ao usar uma webcam em um desktop para a verificação do Liveness 2.0, é importante montar a webcam no topo da mesma tela onde o processo de verificação será iniciado.

# Integrando Liveness 2.0

Quando a resposta do endpoint /card/integration/mainimage tiver com os seguintes dados:

{
  "livenessActive": true,
  "livenessVersion": "2.0"
}

Você deve seguir os seguintes passos:

# 1. Integração via URL (web)

  • Importar a URL [link do ambiente]/#/integration/liveness dentro de um iframe na aplicação.

Sandbox

https://web.sandbox.biodoc.com.br/#/integration/liveness?

Produção

https://web.biodoc.com.br/#/integration/liveness?

# Parâmetros de querystring para URL Padrão

Os parâmetros necessários deverão ser enviados através de querystring junto a URL de Integração.

Parâmetro Descrição Formato
token Token de integração da empresa que está realizando o atendimento. string
card Número do cartão do beneficiário. string
name Nome do beneficiário. string
autoStart Define se a verificação liveness irá iniciar automáticamente ou se será necessário ativá-lo manualmente com o botão "realizar captura" boolean
url URL de retorno da resposta do BioDoc para seu sistema autorizador. Você pode incluir parâmetros necessários para identificação do atendimento no retorno da API. Exemplo: "https://autorizador/123456", onde o parâmetro 123456 pode ser o cartão do beneficiário. string
operation Define o tipo de interação que será executada pelo Liveness string
message Permite que o usuário adicione uma justificativa obrigatória para a operação de troca de imagem ("IMAGE_UPDATE"). string
details Campo livre para enviar informações pertinentes que queira salvar junto aos dados do atendimento. Esperamos um JSON com chave/valor. string

ENUM DE OPERATION

VERIFICATION = Verificação de biometria (default);

IMAGE_UPDATE = Atualização de imagem principal;

REGISTRATION = Cadastro de biometria;

# Exemplo de Integração via URL Padrão através de um iFrame

Atente a um detalhe importante: é necessário inserir o atributo "allow='camera" para que o navegador permita o uso do dispositivo na janela de iFrame.

<!-- Exemplo da integração via URL Padrão através de um iFrame -->
<iframe
  src="https://web.sandbox.biodoc.com.br/#/integration/liveness?token=SEUTOKEN&card=1234567891234567&name=TESTE USUÁRIO&autoStart=true&url=https://autorizador/1234567891234567/&operation=VERIFICATION"
  allow="camera"
></iframe>

# Retorno

O BioDoc irá retornar as informações da verificação redirecionando a página para a URL de retorno informada com os parâmetros via querystring.

// Redirecionamento da página para a URL de Retorno com os parâmetros de retorno
window.location.href(
  "https://autorizador/123456?date=DATA DA VERIFICAÇÃO&response=CÓDIGO DA RESPOSTA&message=MENSAGEM DE RETORNO&card=CARTÃO DO BENEFICIÁRIO"
);

# Parâmetros de Retorno

Parâmetro Descrição Formato
confidence Resultado de 0 a 100 avaliando a probabilidade da imagem ser uma foto de uma face viva string
date Data da Operação timestamp / string
response Código de Resultado da Operação number
message Mensagem de Retorno da Operação string
card Cartão do cartão do beneficiário do atendimento string

Os Códigos de Resultado da Verificação são:

Código de Resposta Descrição
200 Face Reconhecida - Autorizado
201 Face Cadastrada

Caso não seja aprovada a operação, não será feito o redirecionamento para a URL de callback.

# 2. Integração via web-view (mobile - React Native)

  • Importar a URL [link do ambiente]/#/integration/liveness dentro de um web-view na aplicação.

Sandbox

https://web.sandbox.biodoc.com.br/#/integration/liveness?

Produção

https://web.biodoc.com.br/#/integration/liveness?

# Parâmetros de querystring para URL Padrão

Os parâmetros necessários deverão ser enviados através de querystring junto a URL de Integração.

Parâmetro Descrição Formato
token Token de integração da empresa que está realizando o atendimento. string
card Número do cartão do beneficiário. string
name Nome do beneficiário. string
autoStart Define se a verificação liveness irá iniciar automáticamente ou se será necessário ativá-lo manualmente com o botão "realizar captura" boolean
url URL de retorno da resposta do BioDoc para seu sistema autorizador. Você pode incluir parâmetros necessários para identificação do atendimento no retorno da API. Exemplo: "https://autorizador/123456", onde o parâmetro 123456 pode ser o cartão do beneficiário. string
operation Define o tipo de interação que será executada pelo Liveness string
message Permite que o usuário adicione uma justificativa obrigatória para a operação de troca de imagem ("IMAGE_UPDATE"). string
details Campo livre para enviar informações pertinentes que queira salvar junto aos dados do atendimento. Esperamos um JSON com chave/valor. string

ENUM DE OPERATION

VERIFICATION = Verificação de biometria (default);

IMAGE_UPDATE = Atualização de imagem principal;

REGISTRATION = Cadastro de biometria;

  • Para Expo, importar as seguintes bibliotecas:
    • expo-camera
    • react-native-webview
// Exemplo da integração via EXPO
import { useState, useEffect } from "react";
import { SafeAreaView, Text } from "react-native";

// ... outros imports

import { useRouter } from "expo-router";

import * as Linking from "expo-linking";

import { WebView } from "react-native-webview";

const RenderedComponent = () => {
  const router = useRouter();
  const [deepLink, setDeepLink] = useState<string | null>(null);

  useEffect(() => {
    // permitir o uso da camera aqui.

    const handleDeepLink = async () => {
      const url = await Linking.createURL("path-inside-app", {});
      setDeepLink(url);
    };
    if (deepLink) return;
    handleDeepLink();

    const subscription = Linking.addEventListener("url", (event) => {
      const { searchParams } = new URL(event.url);

      /*
       * Observação: Aqui é implementada a navegabilidade em acordo ao suportado na documentação.
       * Também é totalmente moldável a critério do desenvolvedor, em caso queria usar como trigger para outra ação.
       */

      router.push({
        pathname: "/path-inside-app",
        params: Object.fromEntries(searchParams),
      });
    });
    return () => subscription.remove();
  }, []);

  if (!deepLink) return <Text>Problemas ao rederizar o deeplink.</Text>;

  return (
    <SafeAreaView>
      <WebView
        allowsInlineMediaPlayback // IOS camera permission
        javaScriptEnabled // Android camera permission
        mediaPlaybackRequiresUserAction={false} // Bypass para acesso à camera (via browser)
        onShouldStartLoadWithRequest={(request) => {
          if (!request.url.startsWith(deepLink.split("//")[0])) return true;

          /*
           * Observação: O redirecionamento de telas pode ser implementado aqui, conforme a regra de negócio.
           * Contudo recomenda-se usar um event-listener da lib "expo-linking" para melhor distribuição de responsabilidades (para uso de boas práticas como custom-hooks).
           *
           * Observação: Para deeplink é necessário o uso desse interceptor uma vez que o browser incapsulado não necessariamente roda em ambiente local.
           * Para maior embasamento técnico e redução de exploits, podemos acompanhar o artigo: https://medium.com/@justmobilesec/deep-links-webviews-exploitations-part-ii-5c0b118ec6f1
           *
           * -> As politicas nessa função expressas podem ser alteradas a depender da regra de negócio da atual aplicação.
           */

          Linking.openURL(request.url).then(); // **Obs.: aqui o uso de miro-promisse pode ser trabalhado de outra forma.
          return false;
        }}
        source={{
          uri:
            "http://web.sandbox.biodoc.com.br/#/integration/liveness?token=SEUTOKEN&cardId=1234567891234567&cardName=TESTE USUÁRIO&autoStart=true&url=https://autorizador/1234567891234567/&operation=VERIFICATION",
        }}
      />
    </SafeAreaView>
  );
};

export default RenderedComponent;
  • Liberar permissões de acesso à câmera do autorizador ao renderizar o iframe:
    • Liberar o acesso na raiz do projeto no arquivo app.json.
      • Para fazer o redirect interno na aplicação, deve-se configurar o scheme. Recomendamos que o nome seja único, evitando duplicações dentro do sistema operacional. Exemplo: myuniqueschemebiodocintegration.
      • Para Android, a permissão de acesso à câmera deve ser adicionada no campo "permissions".
      • Para iOS, a permissão de acesso à câmera deve ser adicionada no campo "infoPlist".

# Parâmetros de Retorno

Parâmetro Descrição Formato
confidence Resultado de 0 a 100 avaliando a probabilidade da imagem ser uma foto de uma face viva string
date Data da Operação timestamp / string
response Código de Resultado da Operação number
message Mensagem de Retorno da Operação string
card Cartão do cartão do beneficiário do atendimento string

Os Códigos de Resultado da Verificação são:

Código de Resposta Descrição
200 Face Reconhecida - Autorizado
201 Face Cadastrada

Caso não seja aprovada a operação, não será feito o redirecionamento para a URL de callback.

← Verificação por imagem - 1:N (Ainda não disponível) →