--- 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/human-token/integrations/web/web-integration/ locale: pt-BR generated_by: markdown-export --- 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 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 `callbackUri` definido 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 o `callbackUri` e fechar a aba quando o processo estiver completo. Consulte a [documentação MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) para detalhes sobre a API. ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant Frontend as Customer frontend application participant Hosted as Unico hosted frontend application Frontend->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>Frontend: return Unico process info Frontend->>Hosted: redirect user to process url Note over Hosted: User journey Hosted->>Frontend: redirect user to callback url critical Get process result Frontend->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` 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. ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant App as Customer mobile application participant Hosted as Unico hosted frontend application App->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>App: return Unico process info App->>Hosted: open the process url in a webview Note over Hosted: User journey Hosted->>App: redirect user to the deeplink (callback url) critical Get process result App->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` ### Journeys SDK 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. ```bash 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. :::tip[Mantendo o SDK atualizado] 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"); ``` :::info 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 | ```javascript 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. :::warning 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. ```javascript 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: ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant Frontend as Customer frontend application participant SDK as ByUnicoSDK Frontend->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>Frontend: return Unico process info Note over Frontend: Initialize the Unico journey as soon as it is determined that the KYC flow is required critical Unico journey initialization Frontend->>SDK: byUnicoSDK.init SDK-->>Frontend: validates customer domain and initialize end critical Unico journey exhibition Frontend->>SDK: byUnicoSDK.open SDK-->>Frontend: show byUnico experience end Note over SDK: User journey critical Unico journey completion SDK-->>Frontend: call onFinish end critical Get process result Frontend->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` #### Aplicações de exemplo | Linguagem / Framework | Descrição | Repositório | | --------------------- | ------------ | ---------- | | Angular | PoC em Angular que implementa o Journeys SDK | [GitHub — unico-cbu-poc-angular](https://github.com/unico-labs/unico-cbu-poc-angular) | | JS Vanilla | PoC em JS Vanilla que implementa o Journeys SDK | [GitHub — unico-cbu-poc-js](https://github.com/unico-labs/unico-cbu-poc-js) | | React | PoC em React que implementa o Journeys SDK | [GitHub — unico-cbu-poc-react](https://github.com/unico-labs/unico-cbu-poc-react) | | Vue JS | PoC em Vue JS que implementa o Journeys SDK | [GitHub — unico-cbu-poc-vuejs](https://github.com/unico-labs/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. :::warning[Integrações não suportadas] 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 `