--- title: Integração Web App description: Como integrar o contrato Web & SDK no lado do cliente — fluxos de redirecionamento e configuração do iFrame SDK. canonical: https://developer.unico.io/pt-BR/developers/sdks-and-tools/web/ locale: pt-BR generated_by: markdown-export --- - [/pt-BR/](/pt-BR/) - [SDKs e Ferramentas](/pt-BR/developers/sdks-and-tools/overview) - Integração Web App **Nesta página# Integração Web App 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. ModeloIdeal 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 nativosSe a sua aplicação é um app mobile nativo, recomendamos usar o SDK da plataforma em que ele foi construído ([Android](/pt-BR/developers/sdks-and-tools/android/requirements), [iOS](/pt-BR/developers/sdks-and-tools/ios/requirements) ou [Flutter](/pt-BR/developers/sdks-and-tools/flutter/requirements)) em vez de uma integração web. SDK de JornadasAcesso diretoA 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çãoO 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-sdkEste 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](/pt-BR/developers/sdks-and-tools/web/resources/release-notes) 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 atualizadoManter-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âmetroObrigatórioDescrição`token`SimToken do processo retornado pela API de Criar Processo`env`NãoDefina 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âmetroObrigatórioDescrição`transactionId`SimID do processo retornado pela API de Criar Processo`token`SimToken do processo retornado pela API de Criar Processo`onFinish`SimCallback executado quando a jornada termina ou é fechada`onWidgetVisibilityChange`NãoCallback executado quando o estado de visibilidade do widget mudaA 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. avisoO 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:CampoTipoDescrição`type`stringComo a jornada terminou: `'FINISH'` (concluída) ou `'CLOSE'` (usuário fechou antes de finalizar)`transaction`object | undefinedPresente quando `type` é `'FINISH'`; `undefined` quando `type` é `'CLOSE'``transaction.id`stringIdentificador do processo (o mesmo `transactionId` informado)`transaction.​redirectUrl`stringURL para redirecionar o usuário após a jornadaTratar 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 / FrameworkDescriçãoRepositórioNode.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](https://github.com/unico-labs/reference-apps/tree/main/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.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](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) 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 suportadasOs 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 `