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 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.
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
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.
Inicialização da sessão
Usuário final abre a aplicação ou a página.
Aplicativo do cliente solicita recursos estáticos do Web SDK (JS, CSS) e recursos dinâmicos do Adaptador do Web SDK e os baixa.
(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_tokenpara o Aplicativo do cliente.Aplicativo do cliente chama
OzLiveness.open()no Adaptador do Web SDK, passando osession_token.(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.
Adaptador do Web SDK chama o Adaptador do Web SDK para inicializar uma sessão e recebe os dados da sessão em resposta.
Adaptador do Web SDK exibe a tela de captura para o Usuário final.
Verificação de Liveness / análise
Usuário final inicia o processo de captura (vídeo).
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).
Aplicativo do cliente envia os dados capturados para o Back-end do cliente.
Back-end do cliente encaminha uma solicitação de análise para Oz Instant API.
(Opcional, recomendado – requer configuração) Oz Instant API armazena os dados da análise (imagens, metadados) em S3.
Oz Instant API retorna o resultado da análise para o Back-end do cliente.
(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:
recuperando a imagem de S3 para uso interno.
Back-end do cliente retorna o resultado da análise para o Aplicativo do cliente.
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 capturamodo, 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).
Inicialização da sessão
Usuário final abre a aplicação ou a página.
Aplicativo do cliente solicita recursos estáticos do Web SDK (JS, CSS) e recursos dinâmicos do Adaptador do Web SDK e os baixa.
(Opcional, recomendado – OzCapsula) A
session_tokené obtido conforme descrito em Token de sessão. Comapi_use_session_token: "client", o Aplicativo do cliente o solicita do Back-end do cliente, que o solicita de Oz API e o retorna.Aplicativo do cliente chama
OzLiveness.open()no Adaptador do Web SDK, passando osession_tokense foi obtido na etapa 3.(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.
Adaptador do Web SDK chama o Adaptador do Web SDK para inicializar uma sessão e recebe os dados da sessão em resposta.
Adaptador do Web SDK exibe a tela de captura para o Usuário final.
Verificação de Liveness
Usuário final inicia o processo de captura (vídeo).
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.
Adaptador do Web SDK encaminha uma solicitação de análise para Oz Instant API.
(Opcional, recomendado – requer configuração) Oz Instant API armazena os dados da solicitação (imagens, metadados) em S3.
Oz Instant API retorna o resultado de Liveness para o Adaptador do Web SDK.
Adaptador do Web SDK passa o resultado para o Adaptador do Web SDK.
Adaptador do Web SDK retorna o resultado de Liveness para o Aplicativo do cliente.
(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.
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 segueapi_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.
Inicialização da sessão
Usuário final abre a aplicação ou a página.
Aplicativo do cliente solicita recursos estáticos do Web SDK (JS, CSS) e recursos dinâmicos do Adaptador do Web SDK e os baixa.
(Opcional, recomendado – OzCapsula) A
session_tokené obtido conforme descrito em Token de sessão. Comapi_use_session_token: "client", o Aplicativo do cliente o solicita do Back-end do cliente, que o solicita de Oz API e o retorna.Aplicativo do cliente chama
OzLiveness.open()no Adaptador do Web SDK, passando osession_tokense foi obtido na etapa 3, e um identificador únicotransaction_id(e, opcionalmenteend_user_id) emmetapara que a pasta possa ser encontrada posteriormente no back-end:(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.
Adaptador do Web SDK chama o Adaptador do Web SDK para inicializar uma sessão e recebe os dados da sessão em resposta.
Adaptador do Web SDK exibe a tela de captura para o Usuário final.
Verificação de Liveness / análise
Usuário final inicia o processo de captura (vídeo).
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.
Web SDK faz upload dos dados capturados para o Oz API automaticamente – a Oz API cria uma pasta (marcada com o
transaction_idfornecido emmeta), armazena a mídia marcada e inicia as análises solicitadas.Oz API executa as análises assincronamente e persiste a pasta, a mídia e os resultados.
Quando a análise é concluída, o Adaptador do Web SDK dispara o
on_completecallback para notificar o Aplicativo do cliente.Aplicativo do cliente chama o Back-end do cliente, passando o
transaction_id.Back-end do cliente recupera o resultado diretamente de Oz API usando o
Folder LISTmétodo, correspondendo aostransaction_idmetadados 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 efolder_id.Back-end do cliente toma todas as demais decisões do fluxo do processo.
(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).Back-end do cliente retorna o resultado para o Aplicativo do cliente.
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
normalmodo, 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 LISTmétodo, correspondendo aostransaction_idmetadados 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 umresolution_endpointwebhook 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?
