ℹ️ Conteúdo em atualização

Estamos revisando estes procedimentos. Pessoas técnicas podem encontrar ajustes em códigos de erro ou mapeamentos de payload; valide com os logs e o OpenAPI mais recente. Pessoas não técnicas podem continuar usando o passo a passo e acionar o time de suporte caso algo pareça diferente do descrito.

📋 Acordos WebView Biometria

Este documento descreve os acordos e padrões para integração da WebView de biometria, incluindo tipos de eventos, padrões de comunicação e configurações de inicialização.

Tipos de Evento

A WebView de biometria trabalha com três tipos principais de eventos:

Nome do Evento	Descrição
OnFinished	Evento disparado pela WebView. Indica que a operação foi concluída, independente da regra de negócio retornada pela API de validação de biometria. Também pode ser acionada ao fechar a aplicação.
OnError	Evento disparado pela WebView. Indica que houve um erro (não relacionado a regras de negócio).
OnInit	Evento disparado pelo app. Serve para fazer configurações iniciais na WebView. Deve ser chamado logo ao inicializar a WebView.

Tipos de Decisão

No evento OnFinished é retornado um enum de decisão, que pode ser originado pela API ou pelo próprio front:

Decisão	Descrição
APPROVED	Aprovado na API de biometria
DENIED	Negado na API de biometria
CLOSE	Usuário solicitou o fechamento da webview

Padrão de Eventos

Todos os eventos são disparados através de postMessage. Para escutá-los, é necessário utilizar addEventListener('message', msg => ...). As propriedades relevantes do evento (type e detail) ficam em msg.data.

Exemplo de Estrutura de Evento

{
  type: 'OnFinished',
  detail: {
    decision: 'APPROVED',
    base64: '...',
    jwt: '...',
  },
}

Padrão de Retorno dos Eventos

OnFinished

{
  decision: string, // retorna a decisão da API de biometria
  jwt: string,      // imagem criptografada
  base64: string,   // imagem no formato base64
}

OnError

{
  code: number,
  message: string,
}

Inicializando a WebView nos Apps

Para inicializar a WebView, o app deve disparar o evento OnInit com os seguintes parâmetros:

window.postMessage({
  type: "OnInit",
  detail: {
    authorization: string,  // token de autorização
    token: string,          // token com as informações do cliente
    theme: {
      primaryColor,         // cor primária dos botões
      buttonTextColor,      // cor do texto dos botões (somente Serasa por enquanto)
    },
    isOperador?: boolean,   // opcional, serve para mudar os textos da Home
  },
});

Validação de Inicialização

Caso o evento OnInit não seja disparado pelo app, ou seja disparado sem um dos tokens obrigatórios (authorization e token), a WebView irá disparar um evento de erro no seguinte padrão:

{
  type: "OnError",
  detail: {
    message: "Parâmetros de inicialização não informados"
  }
}

Observações Importantes

• O campo theme é opcional e permite personalizar as cores da interface
• O parâmetro isOperador é opcional e altera os textos exibidos na tela inicial
• Ambos os tokens (authorization e token) são obrigatórios para o funcionamento correto da WebView