For the complete documentation index, see llms.txt. This page is also available as Markdown.

Exemplos de fluxos de integração para Web SDK

O Web SDK é executado no navegador e faz a captura de mídia. Este guia cobre ambos os modos de API e, dentro de Instant API, ambas as topologias de integração. Os fluxos diferem em dois eixos: qual Oz API submete a análise (Instant, sem estado vs. completa, persistente) e quem submete a solicitação (o Back-end do cliente ou o Web SDK Adapter).

A opção padrão recomendada é o modo de captura com Instant API: o Back-end do cliente submete a solicitação de análise, dando a você controle total sobre o fluxo de dados e o armazenamento, e a Instant API sem estado não mantém dados no lado do servidor. Os outros modos estão documentados abaixo como alternativas.

A architecture é a chave de configuração que seleciona a topologia:

Modo
API
Quem submete à API
Persistência
Fonte do melhor frame

modo de captura (padrão)

Instant (sem estado)

Back-end do cliente

Somente S3 (opcional)

Base64 da resposta, ou S3

leve

Instant (sem estado)

Adaptador do Web SDK

Somente S3 (opcional)

Base64 da resposta, ou S3

normal

Completo, persistente (com estado)

Adaptador do Web SDK

Pasta, mídia e resultados armazenados e recuperáveis

Base64 da resposta, ou mídia persistida da Oz API

normal é o valor padrão da architecture própria chave; defina architecture para modo de captura a integração descrita aqui, como recomendado.

Participantes

Esses participantes aparecem nos fluxos abaixo. Cada fluxo reutiliza essas definições e observa quaisquer desvios.

Participante
Descrição
Proprietário

Usuário final

Usuário final que interage com a aplicação

–

Aplicativo do cliente

Aplicação frontend voltada ao cliente

Cliente

Back-end do cliente

Serviço de back-end próprio do cliente

Cliente

Plugin do Oz Web SDK (frontend)

Componente de captura de frontend, gerado dinamicamente pelo Adaptador do Web SDK sob solicitação do usuário

Oz (implantado no lado do cliente)

Adaptador do Oz Web SDK (back-end)

Componente de back-end do Web SDK

Oz (implantado no lado do cliente)

Oz API

Serviço de análise completo, persistente (com estado) para verificações de Liveness/biométricas. Cria pastas e armazena mídia, análises e resultados.

Oz (implantado no lado do cliente)

Oz Instant API

Serviço de análise sem estado para verificações de Liveness/biométricas. Sem banco de dados; S3 é a única opção de persistência.

Oz (implantado no lado do cliente)

S3

Armazenamento de objetos para dados da solicitação e imagens

Cliente

Receptor de Telemetria Oz

Hospedado na nuvem telemetria serviço de coleta

Oz (nuvem)

Token de sessão (OzCapsula)

OzCapsula requer um session_token. Ele é solicitado à Oz API em GET /api/authorize/session_token (ou, com API 6.6.2 e versões mais recentes, POST como alternativa) – a mesma chamada e o mesmo resultado independentemente do modo da API (completa ou Instant). Quando usado, o session_token é incorporado ao contêiner e validado no lado do servidor pela Oz API. Certifique-se de ter definido api_use_session_token: "client" no arquivo de configuração.

O token tem tempo limitado (padrão: 900 segundos para API completa, 120 segundos para Instant API). Ele deve ser solicitado toda vez que o Aplicativo do cliente chama o Web SDK: logo após a chamada do SDK e o mais próximo possível do momento em que o usuário inicia a captura. Solicitá-lo cedo demais arrisca expirar antes que a solicitação de análise chegue à API, resultando em um contêiner rejeitado. O session_token é obrigatório quando OzCapsula é usado.

A modo de captura modo (Instant API) – recomendado

A configuração padrão recomendada. O Plugin do Web SDK executa apenas a captura e retorna os dados brutos capturados para o Aplicativo do cliente, que os envia para Oz Instant API pelo Back-end do cliente. Isso dá ao cliente controle total sobre o fluxo de solicitação de análise e o tratamento dos dados, e a Instant API sem estado não mantém dados no lado do servidor. O token é obtido pelo Back-end do cliente.

Diagrama de sequência

Inicialização da sessão

  1. Usuário final abre a aplicação ou a página.

  2. Aplicativo do cliente solicita recursos estáticos do Web SDK (JS, CSS) e recursos dinâmicos do Adaptador do Web SDK e os baixa.

  3. (Opcional, recomendado – OzCapsula) Aplicativo do cliente solicita um token de sessão do Back-end do cliente, que o solicita de Oz API e retorna o session_token para o Aplicativo do cliente.

  4. Aplicativo do cliente chama OzLiveness.open() no Adaptador do Web SDK, passando o session_token.

  5. (Opcional, ativado por padrão) A Adaptador do Web SDK começa a enviar dados recorrentes de telemetria para o Adaptador do Web SDK durante toda a sessão do usuário.

  6. Adaptador do Web SDK chama o Adaptador do Web SDK para inicializar uma sessão e recebe os dados da sessão em resposta.

  7. Adaptador do Web SDK exibe a tela de captura para o Usuário final.

Verificação de Liveness / análise

  1. Usuário final inicia o processo de captura (vídeo).

  2. Adaptador do Web SDK retorna os dados capturados (como uma requisição multipart ou um contêiner binário OzCapsula) para o Aplicativo do cliente (não para o Adaptador).

  3. Aplicativo do cliente envia os dados capturados para o Back-end do cliente.

  4. Back-end do cliente encaminha uma solicitação de análise para Oz Instant API.

  5. (Opcional, recomendado – requer configuração) Oz Instant API armazena os dados da análise (imagens, metadados) em S3.

  6. Oz Instant API retorna o resultado da análise para o Back-end do cliente.

  7. (Opcional – salvamento do melhor frame para uso interno) Back-end do cliente obtém a imagem do melhor frame por um de dois métodos:

  8. Back-end do cliente retorna o resultado da análise para o Aplicativo do cliente.

  9. Aplicativo do cliente exibe o resultado da análise para o Usuário final.

Finalização da telemetria

Após o término da sessão do usuário, o Adaptador do Web SDK envia os dados acumulados de telemetria para o Receptor de Telemetria Oz (serviço em nuvem da Oz). Esta etapa é opcional, mas ativada por padrão.

Pontos-chave

  • Web SDK é fornecido como uma única imagem Docker contendo tanto o Plugin (frontend) quanto o Adaptador (back-end).

  • No modo de captura modo, o Web SDK lida apenas com a captura – todas as solicitações de análise passam pelo Back-end do cliente, dando ao cliente controle total sobre o fluxo de dados e o armazenamento.

  • Aquisição do token de serviço passa pelo Back-end do cliente (recomendado).

  • Oz Instant API é um serviço separado sem estado serviço responsável pela análise biométrica.

  • Recuperação do melhor frame suporta duas opções: decodificar da resposta da API (base64) ou buscar de S3.

  • Telemetria a coleta é opcional (ativada por padrão) e envia dados de uso anonimizados para a nuvem da Oz.

  • Armazenamento em S3 é opcional, mas recomendado para persistir dados de análise e permitir a recuperação subsequente pelos sistemas do cliente.

A leve modo (Instant API)

Uma alternativa a modo de captura na mesma Instant API sem estado. Difere de modo de captura em quem submete a análise: o Adaptador do Web SDK submete diretamente à Oz Instant API e retorna o resultado final, em vez de encaminhar pelo Back-end do cliente. O tratamento do token segue api_use_session_token (o Aplicativo do cliente obtém o token).

Diagrama de sequência

Inicialização da sessão

  1. Usuário final abre a aplicação ou a página.

  2. Aplicativo do cliente solicita recursos estáticos do Web SDK (JS, CSS) e recursos dinâmicos do Adaptador do Web SDK e os baixa.

  3. (Opcional, recomendado – OzCapsula) A session_token é obtido conforme descrito em Token de sessão. Com api_use_session_token: "client", o Aplicativo do cliente o solicita do Back-end do cliente, que o solicita de Oz API e o retorna.

  4. Aplicativo do cliente chama OzLiveness.open() no Adaptador do Web SDK, passando o session_token se foi obtido na etapa 3.

  5. (Opcional, ativado por padrão, requer configuração) A Adaptador do Web SDK começa a enviar dados recorrentes de telemetria para o Adaptador do Web SDK durante toda a sessão do usuário.

  6. Adaptador do Web SDK chama o Adaptador do Web SDK para inicializar uma sessão e recebe os dados da sessão em resposta.

  7. Adaptador do Web SDK exibe a tela de captura para o Usuário final.

Verificação de Liveness

  1. Usuário final inicia o processo de captura (vídeo).

  2. Adaptador do Web SDK envia os dados capturados (como uma requisição multipart ou um contêiner binário OzCapsula) para o Adaptador do Web SDK.

  3. Adaptador do Web SDK encaminha uma solicitação de análise para Oz Instant API.

  4. (Opcional, recomendado – requer configuração) Oz Instant API armazena os dados da solicitação (imagens, metadados) em S3.

  5. Oz Instant API retorna o resultado de Liveness para o Adaptador do Web SDK.

  6. Adaptador do Web SDK passa o resultado para o Adaptador do Web SDK.

  7. Adaptador do Web SDK retorna o resultado de Liveness para o Aplicativo do cliente.

  8. (Opcional – rotina adicional de verificação interna) Aplicativo do cliente consulta sua própria Back-end do cliente, que recupera dados/imagens de S3 para fins de verificação interna.

  9. Aplicativo do cliente exibe o resultado de Liveness para o Usuário final.

Finalização da telemetria

Após o término da sessão do usuário, o Adaptador do Web SDK envia os dados acumulados de telemetria para o Receptor de Telemetria Oz (serviço em nuvem da Oz). Esta etapa é opcional, mas ativada por padrão.

Pontos-chave

  • Web SDK é fornecido como uma única imagem Docker contendo tanto o Plugin (frontend) quanto o Adaptador (back-end).

  • OzCapsula é suportado (use_wasm_container: true; o tratamento do token segue api_use_session_token.

  • Aquisição do token de serviço passa pelo Back-end do cliente (recomendado).

  • Oz Instant API é um serviço separado sem estado serviço responsável pela análise biométrica.

  • Telemetria a coleta é opcional (ativada por padrão) e envia dados de uso anonimizados para a nuvem da Oz.

  • Armazenamento em S3 é opcional, mas recomendado para persistir dados da solicitação e permitir a verificação subsequente pelos próprios sistemas do cliente.

A normal modo (API completa)

Uma alternativa que se destina à Oz API completa, persistente (com estado), em vez de Instant API. Assim como leve, o Adaptador do Web SDK submete a solicitação e retorna o resultado final; ao contrário dos modos Instant, a Oz API cria uma pasta e armazena a mídia, as análises e os resultados, que permanecem recuperáveis depois.

Diagrama de sequência

Inicialização da sessão

  1. Usuário final abre a aplicação ou a página.

  2. Aplicativo do cliente solicita recursos estáticos do Web SDK (JS, CSS) e recursos dinâmicos do Adaptador do Web SDK e os baixa.

  3. (Opcional, recomendado – OzCapsula) A session_token é obtido conforme descrito em Token de sessão. Com api_use_session_token: "client", o Aplicativo do cliente o solicita do Back-end do cliente, que o solicita de Oz API e o retorna.

  4. Aplicativo do cliente chama OzLiveness.open() no Adaptador do Web SDK, passando o session_token se foi obtido na etapa 3, e um identificador único transaction_id (e, opcionalmente end_user_id) em meta para que a pasta possa ser encontrada posteriormente no back-end:

  5. (Opcional, ativado por padrão) A Adaptador do Web SDK começa a enviar dados recorrentes de telemetria para o Adaptador do Web SDK durante toda a sessão do usuário.

  6. Adaptador do Web SDK chama o Adaptador do Web SDK para inicializar uma sessão e recebe os dados da sessão em resposta.

  7. Adaptador do Web SDK exibe a tela de captura para o Usuário final.

Verificação de Liveness / análise

  1. Usuário final inicia o processo de captura (vídeo).

  2. Adaptador do Web SDK envia os dados capturados (como uma requisição multipart ou um contêiner binário OzCapsula) para o Adaptador do Web SDK.

  3. Web SDK faz upload dos dados capturados para o Oz API automaticamente – a Oz API cria uma pasta (marcada com o transaction_id fornecido em meta), armazena a mídia marcada e inicia as análises solicitadas.

  4. Oz API executa as análises assincronamente e persiste a pasta, a mídia e os resultados.

  5. Quando a análise é concluída, o Adaptador do Web SDK dispara o on_complete callback para notificar o Aplicativo do cliente.

  6. Aplicativo do cliente chama o Back-end do cliente, passando o transaction_id.

  7. Back-end do cliente recupera o resultado diretamente de Oz API usando o Folder LIST método, correspondendo aos transaction_id metadados da pasta: /api/folders/?meta_data=transaction_id==unique_id1&with_analyses=true. Para acelerar a solicitação, adicione um filtro de tempo: /api/folders/?meta_data=transaction_id==unique_id1&with_analyses=true&time_created.min=([CURRENT_TIME]-1hour). Na resposta, ele encontra os resultados da análise e folder_id.

  8. Back-end do cliente toma todas as demais decisões do fluxo do processo.

  9. (Opcional – uso interno) Back-end do cliente obtém a imagem do melhor frame decodificando a imagem base64 da resposta (analyses[].results_media[].output_images[].image_b64) ou recuperando a mídia persistida do Oz API (original_url é uma URL real na API completa).

  10. Back-end do cliente retorna o resultado para o Aplicativo do cliente.

  11. Aplicativo do cliente exibe o resultado da análise para o Usuário final.

Finalização da telemetria

Após o término da sessão do usuário, o Adaptador do Web SDK envia os dados acumulados de telemetria para o Receptor de Telemetria Oz (serviço em nuvem da Oz). Esta etapa é opcional, mas ativada por padrão.

Pontos-chave

  • Web SDK é fornecido como uma única imagem Docker contendo tanto o Plugin (frontend) quanto o Adaptador (back-end).

  • No normal modo, o O Web SDK faz upload para a Oz API automaticamente após a captura – o caminho de upload não passa pelo Back-end do cliente.

  • OzCapsula é suportado (use_wasm_container: true) e faz upload do contêiner para a Oz API completa. OzCapsula é opcional; sem ele, a mídia capturada regular é enviada.

  • Aquisição do token de serviço passa pelo Back-end do cliente (recomendado).

  • Oz API aqui está o completa, persistente (com estado) serviço: a pasta, a mídia e os resultados são armazenados e permanecem recuperáveis depois.

  • As análises são executadas assincronamente. Por segurança, o Back-end do cliente recupera os resultados diretamente da Oz API (via o Folder LIST método, correspondendo aos transaction_id metadados da pasta) e toma todas as decisões do fluxo do processo no back-end, em vez de agir sobre o resultado no contexto do navegador. Consulta periódica ou um resolution_endpoint webhook podem ser usados para determinar quando os resultados estão prontos.

  • Recuperação do melhor frame suporta duas opções: decodificar da resposta da API (base64) ou recuperar a mídia persistida da Oz API.

  • Telemetria a coleta é opcional (ativada por padrão) e envia dados de uso anonimizados para a nuvem da Oz.

Atualizado

Isto foi útil?