Como integrar Oz Liveness à sua aplicação Web

Oz Liveness Web SDK implementa a interface de usuário pronta para uso para captura facial, essencial para uma experiência do cliente fluida e resultados de liveness precisos. O SDK detecta ataques de apresentação e de injeção.

Este guia orienta você em sua primeira verificação de liveness usando Web SDK e Oz API. Aqui, cobrimos o modelo SaaS.

O fluxo descrito combina:

• Modo de captura – o Web SDK (ou Mobile SDK) captura o vídeo de Liveness no navegador/app e o backend do cliente o encaminha para a Oz API. Os resultados da captura não são enviados diretamente do SDK para a Oz API; o backend do cliente atua como intermediário.

• OzCapsula – um contêiner binário criptografado proprietário. O SDK empacota a mídia capturada nele; apenas a Oz API pode descriptografá-lo e processá-lo. No dispositivo, ele é um blob opaco – não é possível decodificá-lo ou inspecioná-lo, apenas encaminhá-lo como está.

Cada etapa é marcada:

• [Oz SDK] – chame nossa API do SDK.

• [Seu código] – chame seu próprio backend ou seu próprio código.

{{host}} nos exemplos abaixo é a URL base da sua implantação da Oz API, fornecida durante a configuração da implantação.

Requisitos

Componente	Versão mínima
Oz API	6.6.1
Web SDK	1.9.10

É necessário um Web Adapter dedicado. Expanda a seção abaixo se ele ainda não tiver sido configurado para sua empresa.

Como obter o Web Adapter

Informe os nomes de domínio das páginas a partir das quais você chamará o Web SDK e o e-mail para acesso de administrador, por exemplo:

Nomes de domínio a partir dos quais o Web SDK será chamado: www.yourbrand.com www.yourbrand2.com E-mail para acesso de administrador: [e-mail]

Em resposta, você receberá URLs e credenciais para integração e uso posteriores. Ao usar a API SaaS, você os obtém de nós:

Login: [e-mail] Senha: … API: https://<link>.ozforensics.com/ Web Console: https://<link>.ozforensics.com Web Adapter: https://<link>.ozforensics.com/your_company_name/

Esses parâmetros são obrigatórios para o OzCapsula funcionar. Defina-os no arquivo de configuração da sua API.

OZ_SESSION_TOKEN_LIFETIME=<your_ttl_for_session_token>
OZ_JWT_PRIVATE_KEY_PATH=<jwt_private_key_path>
OZ_JWT_PUBLIC_KEY_PATH=<jwt_public_key_path>
OZ_MALEWICZ_ANALYSIS_ENABLED=true

Instruções

1

(Oz SDK) Incorpore o plugin

A Oz fornece a URL do plugin (servida pelo adaptador hospedado pela Oz). Adicione-a à sua página:

<script src="https://path-to-websdk/plugin_liveness.php"></script>

2

(seu código) Obtenha um session_token do seu backend

O OzCapsula usa um session_token. O token é obrigatório para o OzCapsula.

Seu backend solicita um session_token da Oz API. Solicite-o antes de cada sessão de captura, o mais próximo possível do momento em que o usuário iniciar a captura.

Endpoint:

GET {{host}}/api/authorize/session_token

Solicitação:

curl --location -g '{{host}}/api/authorize/session_token' \\
--header 'X-Forensic-Access-Token: {{access_token}}' ## opcional, depende das configurações da instalação

O mecanismo de autorização para chamadas à Oz API (access_token) depende das configurações da sua instalação: ao usar a Instant API, você pode integrá-la ao seu próprio esquema de autorização. Se um access token for exigido no seu caso, consulte Autenticação. Nunca exponha o token de acesso no navegador. Além disso, observe que o token de acesso e o session_token são tokens diferentes emitidos para finalidades diferentes.

Resposta:

{
  "session_token": "<session_token>"
}

Esse token é de curta duração (validade padrão: 900 segundos para API Full, 120 segundos para Instant API). Solicite um por sessão de captura e passe-o ao SDK imediatamente – não armazene em cache nem reutilize tokens entre sessões.

3

(Oz SDK) Inicie o plugin com o session_token

OzLiveness.open({
  lang: 'en',
  action: ['video_selfie_blank'],  // liveness passivo
  session_token: session_token,    // session_token da Etapa 2
  on_capture_complete: function (action, ozCapsula) {
    // ozCapsula = o contêiner OzCapsula (Blob) — Etapa 4
    sendToYourBackend(ozCapsula);
  },
  on_error: function (err) { /* tratar */ }
});

4

(Oz SDK) Obtenha o contêiner OzCapsula

Quando a captura é concluída, o SDK dispara o on_capture_complete retorno de chamada. O contêiner é entregue como o segundo argumento – um Blob com o tipo MIME application/octet-stream.

O contêiner é um blob criptografado opaco. Você não pode decodificá-lo, inspecioná-lo ou extrair imagens / quadros / metadados individuais dele no dispositivo. Ele deve ser encaminhado como está para o seu backend. Se precisar de acesso às imagens capturadas (por exemplo, a melhor captura), recupere-as da resposta de análise da Oz API no lado do servidor.

Envie-o para o seu backend como application/octet-stream.

5

(seu código) Envie o contêiner para a Oz API

Seu backend envia o contêiner em uma única solicitação síncrona POST solicitação.

Endpoint (Instant API):

POST {{host}}/api/instant/folders/

Endpoint (Full API):

POST {{host}}/api/folders/

Cabeçalhos:

• Content-Type: application/octet-stream (obrigatório).

• X-Forensic-Access-Token: {{access_token}}. (opcional, depende das configurações da instalação).

Corpo da solicitação: os bytes brutos do contêiner – sem envelope JSON, sem multipart, sem encapsulamento base64.

Solicitação (Instant API):

curl -X POST '{{host}}/api/instant/folders/' \\
  --header 'X-Forensic-Access-Token: {{access_token}}' ## opcional, depende das configurações da instalação
  -H 'Content-Type: application/octet-stream' \\
  --data-binary '@/path/to/container.dat'

Solicitação (Full API):

curl -X POST '{{host}}/api/folders/' \\
  --header 'X-Forensic-Access-Token: {{access_token}}' ## opcional, depende das configurações da instalação
  -H 'Content-Type: application/octet-stream' \\
  --data-binary '@/path/to/container.dat'

Em caso de sucesso: HTTP 201 com um objeto JSON de pasta descrevendo o resultado. Consulte a Etapa 6.

Em caso de erro no nível do contêiner: HTTP 400 – consulte Exceções.

Este guia cobre a análise de Liveness. Para executar uma análise de Face Matching dentro do fluxo do OzCapsula, consulte Como Executar uma Análise de Face Matching no Fluxo do OzCapsula.

6

(seu código) Trate a resposta

Seu backend agora tem a resposta – um objeto JSON de pasta descrevendo o resultado.

Tome a decisão de aceitar/rejeitar usando apenas estes dois campos de nível superior:

$.resolution_status   // "FINISHED" – análises concluídas; "FAILED" – erro no processamento da análise
$.system_resolution   // "SUCCESS", "DECLINED" ou "FAILED"

Interprete system_resolution:

• SUCCESS – todas as verificações foram aprovadas; aceite o usuário.

• DECLINED – uma ou mais verificações falharam; rejeite o usuário.

• FAILED – um erro de sistema impediu que pelo menos uma análise fosse concluída; não trate como aceitação ou rejeição.

Para veredictos por análise (por exemplo, para saber se liveness foi aprovado, mas biometria falhou), leia $.analyses[*].resolution_status com os valores descritos acima.

Lista de verificação

• Web SDK 1.9.10+, Oz API 6.6.1+.

• A Etapa 1 incorpora o plugin a partir da URL fornecida pela Oz.

• A Etapa 2 obtém um novo session_token do seu backend antes de cada captura.

• A Etapa 3 passa isso session_token para OzLiveness.open(...).

• A Etapa 4 pega o contêiner do segundo argumento de on_capture_complete; nenhuma tentativa é feita para decodificá-lo/inspecioná-lo no navegador.

• A Etapa 5 envia o contêiner para POST {{host}}/api/instant/folders/ (Instant API) ou POST {{host}}/api/folders/ (Full API) como bytes brutos com Content-Type: application/octet-stream.

• A decisão de aceitar/rejeitar usa apenas resolution_status e system_resolution.

• session_token nunca é armazenado em cache, reutilizado ou compartilhado entre sessões/usuários.

---

Com estas etapas, a integração básica do Web SDK em sua aplicação web está concluída. Será possível acessar a mídia gravada e os resultados da análise em Web Console via navegador ou programaticamente por meio de API (consulte as instruções aqui: recuperação de um vídeo MP4, obtenção de resultados da análise).

Na Guia do Desenvolvedor do Web Plugin, podem ser encontradas instruções para as próximas etapas comuns:

• Personalização da aparência e do comportamento do plugin

• Adição de um pacote de idioma personalizado

• Ajuste do comportamento do plugin

• Parâmetros e callbacks do plugin

• Recomendações de segurança

Encontre um exemplo para Oz Liveness Web SDK aqui. Para fazer funcionar, substitua <web-adapter-url> pelo URL do Web Adapter que você recebeu de nós.

Para Angular e React, substitua https://<link>.ozforensics.com em index.html.

• Exemplo de Angular

• Exemplo de React

• Vue sample

• Svelte sample