Integração Web App
Esta página descreve como as jornadas da Unico funcionam e os modelos de integração disponíveis para incorporá-las em uma aplicação.
Uma jornada é o conjunto de etapas que o usuário percorre para concluir uma verificação de identidade. Por exemplo: capturar a foto de um documento e realizar uma captura facial (liveness).
A Unico gerencia toda a experiência. O esforço de integração é mínimo: a jornada é criada via CreateProcess, o usuário é direcionado a ela e o resultado é recebido no final. Tudo o que está entre isso — telas, instruções, validações — já está construído e mantido pela Unico.
Dois modelos de integração
Cada cliente tem necessidades diferentes. A Unico oferece dois modelos para direcionar o usuário à jornada.
| Modelo | Melhor para |
|---|---|
| Acesso direto | Aplicações mobile que já utilizam WebView, ou fluxos web onde a jornada pode acontecer fora da página principal |
| Journeys SDK | Aplicações web que precisam de uma experiência integrada e fluida, mantendo o usuário no mesmo ambiente |
- Acesso direto
- Journeys SDK
O usuário é redirecionado para um link hospedado pela Unico, onde a jornada acontece. Ao concluir,
ele é retornado à URL definida durante a criação do processo (o parâmetro callbackUri).
Esta é a abordagem mais simples de adotar: não requer instalação de biblioteca 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 introduzir mais fricção e, consequentemente, uma maior taxa de desistência.
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:
- Redirecionamento padrão. O usuário é redirecionado diretamente para a URL da jornada. Ao concluir,
a Unico o redireciona de volta para o
callbackUridefinido durante a 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. Neste caso, é recomendado monitorar uma mudança de URL para ocallbackUrie fechar a aba quando o processo estiver completo. Consulte a documentação MDN para detalhes sobre a API.
Em aplicações mobile, é comum usar 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 na aplicação nativa.
Basta configurar o deeplink como destino de retorno e o sistema operacional cuida de direcionar
o usuário ao local correto.
A jornada acontece dentro da própria aplicação, sem tirar o usuário de seu contexto. O Journeys SDK é instalado na aplicação e utilizado para abrir a jornada quando necessário.
Este é o caminho recomendado para uma experiência mais integrada e fluida, mantendo o usuário no mesmo ambiente durante todo o processo, o que tende a reduzir fricção e desistência ao longo do fluxo.
A Unico fornece uma biblioteca JavaScript compatível com navegadores modernos, permitindo que a jornada seja integrada em praticamente qualquer aplicação com apenas algumas linhas de código.
Compatibilidade
A biblioteca é projetada para se adaptar a qualquer projeto sem fricção, independentemente da stack em uso:
- Qualquer aplicação web. Distribuída em formato UMD, funciona quando importada por bundlers modernos (como webpack ou Vite). Compatível com qualquer framework (React, Angular, Vue) ou JavaScript puro.
- Navegadores modernos. A biblioteca já inclui os polyfills necessários para recursos como
Promises e
async/await, estendendo a compatibilidade também para versões mais antigas de navegadores. - APIs web padrão. A jornada funciona com capacidades nativas do navegador, sem dependência de plugins ou bibliotecas externas no projeto.
Como o SDK funciona internamente
Quando uma jornada é aberta, o SDK insere um iFrame na página e assume o controle de toda a experiência visual a partir desse ponto. As telas, scripts e assets de cada etapa são executados dentro desse iFrame, desde o momento em que o usuário inicia até a conclusão do processo.
Essa decisão arquitetural é intencional: o isolamento do iFrame garante que a jornada da Unico não interfira nos estilos ou no comportamento da aplicação. Nenhum script vaza para o contexto externo, nenhuma regra CSS colide com os estilos da própria aplicação. O resultado é uma experiência consistente para o usuário final e impacto mínimo no produto do cliente.
Como a Unico é responsável por criar e gerenciar o iFrame, melhorias na jornada — seja em desempenho, experiência ou validação — são entregues automaticamente a todos os usuários, sem necessidade de mudanças na aplicação integrada. A integração sempre rodará com as melhores otimizações disponíveis, sem precisar acompanhar ou reagir a cada atualização da plataforma.
Primeiros passos
Passo 1 — Instalação
O pacote idpay-b2b-sdk é compartilhado entre jornadas de pagamento do IDPay e jornadas de verificação
de identidade. Para casos de uso de identidade, importe a classe ByUnicoSDK conforme mostrado nos passos abaixo.
npm install idpay-b2b-sdk
A forma recomendada de instalar o Journeys SDK é através de um gerenciador de pacotes 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 fornece controle claro sobre a versão em uso e facilita a atualização quando uma nova versão é publicada.
O SDK segue o Semantic Versioning (SemVer), o que significa que atualizações de patch e minor não introduzem breaking changes. É seguro configurar o projeto para receber essas atualizações automaticamente. Mudanças que podem exigir atualizações de integração são reservadas para versões major e sempre vêm com um guia de migração.
Manter-se na versão mais recente é especialmente importante por dois motivos. O primeiro é segurança: patches de segurança são publicados sempre que vulnerabilidades são identificadas ou surgem oportunidades de fortalecer o protocolo de comunicação. Rodar uma versão desatualizada significa perder essas correções e expor o fluxo a riscos desnecessários. O segundo é estabilidade: correções de bugs são distribuídas da mesma forma, e versões mais antigas podem apresentar comportamentos que já foram resolvidos em versões mais recentes.
Antes de começar, registre seus domínios com a equipe de suporte da Unico. Todos os domínios devem usar HTTPS.
Passo 2 — Configurar CSP e Permissions-Policy
Se sua página já envia headers Content-Security-Policy ou Permissions-Policy, adicione as seguintes diretivas para que o iFrame, scripts e acesso à câmera do SDK funcionem corretamente.
Content-Security-Policy:
frame-src https://*.unico.io https://*.unico.app;
script-src https://idpay.unico.io;
style-src https://idpay.unico.io;
connect-src https://api.cadastro.unico.app;
Permissions-Policy:
camera=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
geolocation=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
Se sua página não envia headers CSP ou Permissions-Policy, você pode pular este passo — o navegador não aplica restrições por padrão.
Passo 3 — Chamar 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 isso o mais cedo possível no fluxo.
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
token | Sim | Token do processo retornado pela API Create Process |
env | Não | Defina como 'uat' apenas para ambientes de teste |
import { ByUnicoSDK } from 'idpay-b2b-sdk';
ByUnicoSDK.init({
token,
// env: 'uat' // only for test environments
});
Passo 4 — Chamar open(options)
Exibe o iFrame e inicia a jornada para o usuário. A partir desse ponto, 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 Create Process |
token | Sim | Token do processo retornado pela API Create Process |
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
completou ou a fechou. Nesse ponto, o SDK invoca o callback onFinish, passado como parâmetro
em open. A partir daí, a aplicação pode chamar a API getProcess para verificar o resultado,
ou aguardar uma notificação de Webhook se uma abordagem assíncrona for preferida.
Além de consultar o resultado, é recomendado usar onFinish para lidar com o estado do
front-end da aplicação:
- Evitar loops. Prevenir a recriação imediata e desnecessária de processos caso o usuário dispare o fluxo novamente logo após o término da jornada.
- Gerenciamento do fluxo. Garantir que o usuário seja direcionado à próxima etapa da aplicação, evitando uma tela sem saída após o fechamento da jornada.
O callback onFinish sinaliza que o usuário completou a jornada, mas não garante aprovação.
O processo pode ter terminado com falha em uma das regras de validação da Unico.
Consultar via getProcess ou receber a notificação do Webhook não é opcional: essas são as
únicas fontes do resultado real, e o comportamento da aplicação deve se basear nelas. onFinish
não deve ser utilizado isoladamente para determinar se um usuário foi aprovado.
O callback onFinish recebe um objeto descrevendo como a jornada terminou:
| Campo | Tipo | Descrição |
|---|---|---|
type | string | Como a jornada terminou: 'FINISH' (concluída) ou 'CLOSE' (usuário fechou antes de concluir) |
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 atrás da experiência. Aplicações que exibem um modal customizado durante o fluxo de verificação
(por exemplo, como parte de uma orquestração entre múltiplos provedores de KYC) podem acabar exibindo
esse modal por trás do widget da Unico, degradando 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 quando ela terminar. Se sua aplicação não possui 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') {
// Journey completed (transaction = { id, redirectUrl }) — continue your flow here.
}
// type === 'CLOSE' → user closed before finishing;
},
// Optional: only needed if your app shows UI that could overlap the widget.
onWidgetVisibilityChange: (visible) => {
// suppress or restore your modal based on widget visibility
},
});
// To close the SDK explicitly at any point:
ByUnicoSDK.close();
O diagrama de sequência abaixo demonstra como usar o SDK e o resultado da API para configurar o iFrame:
Aplicações de exemplo
| Linguagem / Framework | Descrição | Repositório |
|---|---|---|
| Angular | PoC em Angular que implementa o Journeys SDK | GitHub — unico-cbu-poc-angular |
| JS Vanilla | PoC em JS Vanilla que implementa o Journeys SDK | GitHub — unico-cbu-poc-js |
| React | PoC em React que implementa o Journeys SDK | GitHub — unico-cbu-poc-react |
| Vue JS | PoC em Vue JS que implementa o Journeys SDK | GitHub — unico-cbu-poc-vuejs |
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.
Quando a jornada é carregada, ambas as 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 aprovadas são descartadas imediatamente, impedindo que a jornada seja embarcada 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ó prossegue 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 flui 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 runtime. Como o código roda em um contexto separado da página, ele não pode ser acessado ou modificado por scripts externos, garantindo que a jornada execute exatamente como foi construída, sem interferência.
CSP e Permissions-Policy
Se sua página envia headers Content-Security-Policy ou Permissions-Policy, certifique-se de que as seguintes diretivas estejam presentes para que o iFrame, scripts e acesso à câmera do SDK funcionem corretamente.
Content-Security-Policy:
frame-src https://*.unico.io https://*.unico.app;
script-src https://idpay.unico.io;
style-src https://idpay.unico.io;
connect-src https://api.cadastro.unico.app;
Permissions-Policy:
camera=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
geolocation=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
Se sua página não envia esses headers, o navegador não aplica restrições por padrão e nenhuma configuração é necessária.
Solução de problemas específicos do SDK
Esta seção cobre os problemas mais comuns encontrados durante a integração e as formas recomendadas de investigá-los.
Comportamento inesperado ou fluxo quebrado
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 — seja no escopo,
posicionamento ou atributos — pode interferir no ciclo de vida da jornada e causar comportamento
imprevisível.
Experiência visual diferente do esperado
Verifique se alguma folha de estilos 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 via seletores de ID ou classe. Ainda assim,
regras CSS amplas — como seletores de tag — podem alcançar 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 pacotes. A biblioteca deve ser gerenciada exclusivamente via npm ou yarn, sem edições diretas nos arquivos instalados. Modificações manuais podem produzir comportamento anômalo difícil de reproduzir e impedirão que o suporte da Unico consiga auxiliar.
Não mantenha o DevTools aberto durante testes de captura
A aplicação da Unico usa o Capture SDK (unico-webframe) para captura facial, que detecta o DevTools aberto como um sinal potencial de fraude e bloqueia o envio. Feche o DevTools antes de executar testes de captura de ponta a ponta.
Os modelos descritos nesta documentação — acesso direto e Journeys SDK — são as únicas abordagens de integração oficialmente suportadas pela Unico. Integrações que desviem desses padrões podem causar comportamento inesperado, falhas em fluxos de segurança e interrupções na jornada, e não serão cobertas pelo suporte da Unico.
Exemplos de abordagens não suportadas:
- Incorporar o SDK dentro de uma WebView em aplicações mobile. Nesses casos, a abordagem correta é usar o modelo de acesso direto, abrindo o link da jornada diretamente na WebView sem envolver o Journeys SDK.
- Carregar o iFrame diretamente via tag HTML
<iframe>, sem passar pelo Journeys SDK. O iFrame é um detalhe de implementação interna do SDK e não deve ser instanciado manualmente. A abordagem correta é usar o Journeys SDK, que gerencia o ciclo de vida do iFrame de forma segura e dentro dos padrões esperados.
Se houver qualquer 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 prosseguir com a implementação.