--- 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/dual-api/developers/sdks-and-tools/web/web-integration/ locale: pt-BR generated_by: markdown-export --- 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. :::tip[Escolhendo sua abordagem de integração] - **Web SDK** (pacote `unico-webframe`): use quando o seu back-end já controla o fluxo de verificação de identidade e precisa apenas do componente de captura no lado do cliente. Retorna `base64` + JWT criptografado diretamente para o seu callback; você gerencia as chamadas de API. - **Web App Integration** (pacote `idpay-b2b-sdk`): use quando quiser que a Unico orquestre toda a jornada (fluxos multi-etapa, captura de documentos + Prova de Vida). O pacote `idpay-b2b-sdk` viabiliza o modelo **SDK de Jornadas** (iFrame) incorporado; o modelo **Acesso direto** (redirecionamento) não precisa de biblioteca. ::: ## 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 | | ------------------- | --------------------------------------------------------------------------------------------------------------- | | **Acesso direto** | Aplicações mobile que já utilizam WebView, ou fluxos web em que a jornada pode acontecer fora da página principal | | **SDK de Jornadas** | 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 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. ```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 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. ```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 ``` ### 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 `idpay-b2b-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. ```bash npm install idpay-b2b-sdk ``` 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. :::tip[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 | ```javascript import { ByUnicoSDK } from 'idpay-b2b-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. :::warning 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. ```javascript 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: ```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 ``` #### Apps de exemplo | Linguagem / Framework | Descrição | Repositório | | --------------------- | ------------ | ---------- | | Angular | PoC em Angular que implementa o SDK de Jornadas | [GitHub — unico-cbu-poc-angular](https://github.com/unico-labs/unico-cbu-poc-angular) | | JS Vanilla | PoC em JS Vanilla que implementa o SDK de Jornadas | [GitHub — unico-cbu-poc-js](https://github.com/unico-labs/unico-cbu-poc-js) | | React | PoC em React que implementa o SDK de Jornadas | [GitHub — unico-cbu-poc-react](https://github.com/unico-labs/unico-cbu-poc-react) | | Vue JS | PoC em Vue JS que implementa o SDK de Jornadas | [GitHub — unico-cbu-poc-vuejs](https://github.com/unico-labs/unico-cbu-poc-vuejs) | #### Segurança :::note[Escopo desta seção] Esta justificativa de segurança aplica-se especificamente à **Web App Integration** (`idpay-b2b-sdk`). O **Web SDK** (`unico-webframe`) utiliza um modelo diferente: ele é executado inteiramente no contexto da página e [requer um CSP](/dual-api/developers/sdks-and-tools/web/web-sdk/installation). Estes são dois produtos distintos com arquiteturas de segurança diferentes. ::: 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. #### Não mantenha o DevTools aberto durante os testes de captura O aplicativo da Unico usa o Capture SDK (unico-webframe) para a captura facial, que 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. :::warning[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 `