Integração Web App

Markdown

Esta página descreve como funcionam as jornadas da Unico e quais são os modelos disponíveis para integrá-las a uma aplicação.

Uma jornada é o conjunto de passos que o usuário percorre para concluir uma verificação de identidade. Por exemplo: capturar uma foto do documento e fazer a captura facial (Prova de Vida).

A Unico cuida de toda essa experiência. O esforço de integração é mínimo: a jornada é criada via CreateProcess, o usuário é direcionado para ela e, ao final, o resultado é recebido. Tudo o que acontece no meio do caminho (telas, instruções, validações) já está pronto e é mantido pela Unico.

Dois modelos de integração

Cada cliente tem necessidades diferentes. A Unico oferece dois modelos para levar o usuário até a jornada.

Modelo	Ideal para
SDK de Jornadas	Aplicações web que precisam de uma experiência integrada e fluida, mantendo o usuário no mesmo ambiente
Acesso direto	Fluxos web em que a jornada pode acontecer fora da página principal, ou apps que já incorporam uma WebView. Apps nativos devem preferir o SDK da plataforma

Apps nativos

Se a sua aplicação é um app mobile nativo, recomendamos usar o SDK da plataforma em que ele foi construído (Android, iOS ou Flutter) em vez de uma integração web.

SDK de Jornadas

A jornada acontece dentro da própria aplicação, sem tirar o usuário do seu contexto. O SDK de Jornadas é instalado na aplicação e usado para abrir a jornada quando necessário.

É o caminho recomendado para uma experiência mais integrada e fluida, mantendo o usuário sempre no mesmo ambiente, o que tende a reduzir a fricção e o abandono ao longo do fluxo.

A Unico disponibiliza uma biblioteca JavaScript compatível com os navegadores modernos, permitindo integrar a jornada em praticamente qualquer aplicação com poucas linhas de código.

Compatibilidade

A biblioteca foi pensada para se encaixar em qualquer projeto sem atrito, independentemente da stack utilizada:

• Qualquer aplicação web. Distribuída no formato UMD, funciona quando importada por bundlers modernos (como webpack ou Vite). Compatível com qualquer framework (React, Angular, Vue) ou com JavaScript puro.
• Navegadores modernos. A biblioteca já inclui os polyfills necessários para recursos como Promises e async/await, ampliando a compatibilidade também com versões mais antigas dos navegadores.
• APIs web padrão. A jornada roda apoiada em recursos nativos do navegador, sem depender de plugins ou bibliotecas externas no projeto.

Como o SDK funciona internamente

Ao abrir uma jornada, o SDK insere um iFrame na página e assume o controle de toda a experiência visual a partir daí. As telas, os scripts e os assets de cada etapa rodam dentro desse iFrame, do momento em que o usuário começa até a conclusão do processo.

Essa decisão de arquitetura é intencional: o isolamento do iFrame garante que a jornada da Unico não interfere com o estilo nem com o comportamento da aplicação. Nenhum script vaza para o contexto externo, nenhuma regra de CSS colide com os estilos da aplicação. O resultado é uma experiência consistente para o usuário final e um impacto mínimo no produto do cliente.

Como a Unico é responsável por criar e gerenciar o iFrame, as melhorias na jornada (sejam de performance, experiência ou validação) chegam automaticamente para todos os usuários, sem necessidade de nenhuma alteração na aplicação integrada. A integração sempre rodará com as melhores otimizações disponíveis, sem precisar acompanhar ou reagir a cada evolução da plataforma.

Como começar

Passo 1: Instalação

O pacote unico-journey-sdk é compartilhado entre as jornadas de pagamento do IDPay e as jornadas de verificação de identidade. Para casos de uso de identidade, importe a classe ByUnicoSDK conforme demonstrado nas etapas abaixo.

  npm install unico-journey-sdk

Anteriormente idpay-b2b-sdk

Este pacote era publicado anteriormente como idpay-b2b-sdk. É o mesmo SDK com um novo nome e mantém a mesma linha de versões. Apenas a 2.3.0 e posteriores estão disponíveis sob o novo nome. Consulte as Notas de Versão para o histórico completo.

A forma recomendada de instalar o SDK de Jornadas é através de um gerenciador de dependências como npm ou yarn, a partir do pacote disponível no npm registry. Além de simplificar a instalação e o gerenciamento de dependências, essa abordagem oferece controle claro sobre a versão em uso e facilita a atualização sempre que uma nova versão for publicada.

O SDK segue o Versionamento Semântico (SemVer), o que significa que atualizações de patch e minor não introduzem quebras de compatibilidade. É seguro configurar o projeto para receber essas atualizações automaticamente. Mudanças que possam exigir adaptações na integração ficam reservadas para versões major e sempre vêm acompanhadas de um guia de migração.

Mantenha o SDK atualizado

Manter-se na versão mais recente é especialmente importante por duas razões. A primeira é segurança: patches de segurança são publicados sempre que vulnerabilidades são identificadas ou quando surgem oportunidades de fortalecer o protocolo de comunicação. Rodar uma versão desatualizada significa abrir mão dessas correções e expor o fluxo a riscos desnecessários. A segunda é estabilidade: correções de bugs são distribuídas da mesma forma, e versões antigas podem apresentar comportamentos já resolvidos em versões mais recentes.

Antes de começar, registre seus domínios junto ao time de suporte da Unico. Todos os domínios devem usar HTTPS.

Passo 2: Chame init(options)

Inicializa o SDK e pré-carrega os scripts necessários para o funcionamento correto da jornada, criando uma experiência mais fluida para o usuário final. Chame o quanto antes no fluxo.

Parâmetro	Obrigatório	Descrição
token	Sim	Token do processo retornado pela API de Criar Processo
env	Não	Defina como 'uat' apenas para ambientes de teste

import { ByUnicoSDK } from 'unico-journey-sdk';

ByUnicoSDK.init({
  token,
  // env: 'uat' // somente para ambientes de teste
});

Passo 3: Chame open(options)

Exibe o iFrame e inicia a jornada para o usuário. A partir daí, tudo acontece automaticamente dentro do iFrame, sem necessidade de gerenciar nenhuma etapa intermediária.

Parâmetro	Obrigatório	Descrição
transactionId	Sim	ID do processo retornado pela API de Criar Processo
token	Sim	Token do processo retornado pela API de Criar Processo
onFinish	Sim	Callback executado quando a jornada termina ou é fechada
onWidgetVisibilityChange	Não	Callback executado quando o estado de visibilidade do widget muda

A próxima interação com a aplicação ocorre quando a jornada termina, seja porque o usuário a concluiu ou a fechou. Nesse momento, o SDK invoca o callback onFinish, passado como parâmetro no open. A partir daí, a aplicação pode chamar a API getProcess para consultar o resultado, ou aguardar uma notificação via Webhook caso prefira uma abordagem assíncrona.

Além de consultar o resultado, recomenda-se usar o onFinish para tratar o estado da aplicação no front-end:

• Evitar loops. Impedir a recriação imediata e desnecessária de processos caso o usuário acione novamente o fluxo logo após o término da jornada.
• Gestão de fluxo. Garantir que o usuário seja direcionado para a próxima etapa da aplicação, evitando que fique retido em uma tela sem saída após o encerramento da jornada.

aviso

O callback onFinish indica que o usuário concluiu a jornada, mas não garante a aprovação. O processo pode ter terminado com uma reprovação em alguma das regras de validação da Unico. Consultar via getProcess ou receber a notificação via Webhook não é opcional: são as únicas fontes do resultado real, e o comportamento da aplicação deve se basear nelas. O onFinish não deve ser usado isoladamente para determinar se um usuário foi aprovado.

O callback onFinish recebe um objeto que descreve como a jornada terminou:

Campo	Tipo	Descrição
type	string	Como a jornada terminou: 'FINISH' (concluída) ou 'CLOSE' (usuário fechou antes de finalizar)
transaction	object | undefined	Presente quando type é 'FINISH'; undefined quando type é 'CLOSE'
transaction.id	string	Identificador do processo (o mesmo transactionId informado)
transaction.​redirectUrl	string	URL para redirecionar o usuário após a jornada

Tratar o callback onWidgetVisibilityChange é opcional e pode não ser relevante para o seu caso de uso. Ele é invocado sempre que o estado de visibilidade do widget muda, e é útil apenas em um cenário específico: algumas jornadas exibem um fundo transparente, mantendo a página da aplicação visível ao fundo da experiência. Aplicações que exibem um modal próprio durante o fluxo de verificação (por exemplo, como parte de uma orquestração entre diferentes provedores de KYC) podem acabar exibindo esse modal atrás do widget da Unico, prejudicando a experiência visual. Nesse caso, o callback permite que a aplicação suprima quaisquer elementos visuais adicionais enquanto a jornada da Unico estiver ativa, e os restaure ao término. Se a sua aplicação não tiver nenhuma UI que possa sobrepor o widget, você pode omiti-lo com segurança.

ByUnicoSDK.open({
  transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  onFinish: ({ transaction, type }) => {
    if (type === 'FINISH') {
      // Jornada concluída (transaction = { id, redirectUrl }): continue seu fluxo aqui.
    }
    // type === 'CLOSE' → usuário fechou antes de finalizar;
  },
  // Opcional: necessário apenas se a sua aplicação exibe UI que possa sobrepor o widget.
  onWidgetVisibilityChange: (visible) => {
    // suprima ou restaure seu modal conforme a visibilidade do widget
  },
});

// Para fechar o SDK explicitamente a qualquer momento:
ByUnicoSDK.close();

O diagrama de sequência abaixo demonstra como usar o SDK e o resultado da API para configurar o iFrame:

Aplicativo de referência

Linguagem / Framework	Descrição	Repositório
Node.js (Express)	Aplicativo de referência em Node.js que implementa o fluxo completo da jornada do usuário com o SDK de Jornadas	GitHub — reference-apps/web

Segurança

A segurança neste modelo é construída em camadas, começando pelo protocolo de comunicação entre o SDK e a aplicação que roda dentro do iFrame.

Ao carregar a jornada, as duas partes realizam um handshake para estabelecer a comunicação. Nesse processo, a aplicação da Unico valida a origem da mensagem de injeção de dados recebida via postMessage contra uma lista fechada de domínios autorizados, segmentada por ambiente (UAT e PROD). Mensagens de origens não homologadas são descartadas imediatamente, impedindo que a jornada seja incorporada em páginas não autorizadas e eliminando a superfície de ataque para vulnerabilidades como clickjacking.

Além da validação de origem, o fluxo só avança com um token de transação válido: um JWT de uso único, emitido e assinado pelo backend da Unico. Isso garante que mesmo uma origem autorizada não consiga operar com um token expirado, reutilizado ou forjado.

Após o handshake, o token é injetado no iFrame e nenhuma informação sensível trafega mais entre as duas partes. Toda a comunicação restante serve apenas para controle de interface (abertura, fechamento e transições de tela), impedindo que dados do processo sejam interceptados ou vazados durante a jornada.

O isolamento do iFrame também protege a integridade dos scripts da Unico em tempo de execução. Como o código roda em um contexto separado da página, ele não pode ser acessado nem modificado por scripts externos, garantindo que a jornada execute exatamente como foi construída, sem interferências.

Por design, não adotamos CSP neste modelo de integração. Os domínios autorizados fazem parte da configuração de segurança de cada cliente, e sua exposição pública em headers poderia facilitar o mapeamento da infraestrutura por agentes mal-intencionados. Como a identificação do cliente só acontece no momento do init, não é possível injetar esses domínios dinamicamente nos cabeçalhos antes disso, tornando o CSP inviável sem abrir mão dessa privacidade. Todas as garantias de segurança são providas pelo protocolo de handshake descrito acima.

Solução de problemas específica do SDK

Esta seção reúne os problemas mais comuns encontrados durante a integração e as formas recomendadas de investigá-los.

Comportamento inesperado ou quebra no fluxo

Verifique se algum script da aplicação está manipulando diretamente o iFrame no DOM. O SDK cria e gerencia o iFrame no body da página, e qualquer modificação externa (de escopo, posicionamento ou atributos) pode interferir no ciclo de vida da jornada e causar comportamentos imprevisíveis.

Experiência visual diferente do esperado

Verifique se alguma folha de estilo global da aplicação está sobrescrevendo propriedades dentro do iFrame. O SDK cria o iFrame e todos os seus elementos internos com IDs dinâmicos e classes prefixadas com unico, o que reduz significativamente o risco de conflito por seletores de ID ou classe. Ainda assim, regras CSS de escopo amplo (como seletores de tag) podem atingir elementos dentro do iFrame e alterar a experiência visual entregue ao usuário.

Arquivos da biblioteca do SDK modificados diretamente

Verifique se algum arquivo da biblioteca foi modificado fora do gerenciador de dependências. A biblioteca deve ser gerenciada exclusivamente via npm ou yarn, sem alterações diretas nos arquivos instalados. Modificações manuais podem gerar comportamentos anômalos difíceis de reproduzir e impossibilitam o atendimento pelo suporte da Unico.

Acesso direto

O usuário é redirecionado para um link da Unico, onde a jornada acontece. Ao concluir, ele volta para a URL definida na criação do processo (parâmetro callbackUri).

É o caminho mais simples de adotar: não exige instalação de bibliotecas e funciona bem quando a jornada não precisa acontecer dentro da própria página da aplicação. Por outro lado, levar o usuário para fora do ambiente do cliente tende a gerar mais fricção e, consequentemente, uma taxa de abandono maior.

Após criar um processo, a resposta da API inclui a URL da jornada hospedada pela Unico. Há duas formas comuns de direcionar o usuário até ela:

• Redirecionamento padrão. O usuário é redirecionado diretamente para a URL da jornada. Ao concluir, a Unico o redireciona de volta para o callbackUri definido na criação do processo.
• Nova aba com window.open(). A jornada é aberta em uma nova aba do navegador, mantendo o usuário em um contexto separado. Nesse caso, é recomendado monitorar a mudança de URL para o callbackUri e fechar a aba assim que o processo for concluído. Consulte a documentação do MDN para detalhes sobre a API.

Em aplicações mobile, é comum utilizar uma WebView para abrir a jornada diretamente, sem necessidade de redirecionamento adicional. Nesse caso, o callbackUri também aceita um deeplink, permitindo que a conclusão da jornada dispare a abertura de uma tela específica no aplicativo nativo. Basta configurar o deeplink como destino de retorno e o próprio sistema operacional se encarrega de rotear o usuário para o lugar certo. Essa abordagem com WebView se encaixa em apps que já incorporam uma; um app totalmente nativo deve preferir o SDK da plataforma.

Não mantenha o DevTools aberto durante os testes de captura

A Unico usa diversos mecanismos para proteger suas jornadas, e um deles detecta o DevTools aberto como um possível sinal de fraude e bloqueia o envio. Feche o DevTools antes de rodar testes de captura de ponta a ponta.

Integrações não suportadas

Os modelos descritos nesta documentação (acesso direto e SDK de Jornadas) são as únicas formas de integração oficialmente suportadas pela Unico. Integrações que fujam desses padrões podem causar comportamentos inesperados, falhas no fluxo de segurança e interrupções na jornada, e não serão cobertas pelo suporte da Unico.

Alguns exemplos de abordagens não suportadas:

• Incorporar o SDK dentro de uma WebView em aplicações mobile. Nesses casos, o caminho correto é utilizar o modelo de acesso direto, abrindo o link da jornada diretamente na WebView, sem envolver o SDK de Jornadas.
• Carregar o iFrame diretamente via tag HTML <iframe>, sem passar pelo SDK de Jornadas. O iFrame é um detalhe de implementação interno do SDK e não deve ser instanciado manualmente. O caminho correto é utilizar o SDK de Jornadas, que gerencia o ciclo de vida do iFrame de forma segura e dentro dos padrões esperados.

Em caso de dúvida sobre se uma abordagem está dentro do padrão suportado, consulte a documentação ou entre em contato com o suporte antes de avançar com a implementação.