Integração Web App

Esta página abrange as duas abordagens de integração no lado do cliente para o contrato Web & SDK: redirecionar o usuário para uma jornada hospedada pela Unico e incorporar a jornada via iFrame SDK.

Redirecionando o usuário

Após criar um processo, a resposta inclui uma URL que aponta para a jornada hospedada pela Unico. Use essa URL para encaminhar o usuário à experiência de captura. Há duas formas de gerenciar essa transição:

1. Redirecionamento padrão

Redirecione o usuário diretamente para a URL da jornada. Quando o usuário concluir o processo, a Unico o redireciona de volta para a URL especificada durante a criação do processo.

2. Nova aba com window.open()

Abra a jornada em uma nova aba do navegador para que o usuário permaneça em um contexto separado. Monitore a mudança de URL para a sua URL de retorno e feche a aba quando o processo for concluído.

Para detalhes sobre a API window.open(), consulte a documentação do MDN.

iFrame

aviso

Integrações que não seguem os padrões desta documentação podem causar interrupções inesperadas e não serão cobertas pelo suporte da Unico.

Exemplos de abordagens não suportadas: incorporar o SDK dentro de um WebView ou carregar o iFrame diretamente via tag HTML.

Como começar

Passo 1 — Instalação

O SDK by Unico utiliza o mesmo pacote do IDPay:

npm install idpay-b2b-sdk

dica

Instale sem fixar uma versão específica para que o seu gerenciador de pacotes sempre obtenha automaticamente as últimas versões minor e patch.

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 assets, criando uma experiência mais fluida para o usuário final. Chame o quanto antes no seu fluxo.

Parâmetro	Obrigatório	Descrição
type	Sim	Defina como 'IFRAME' para fluxos by Unico
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 "idpay-b2b-sdk";

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

Passo 3 — Chame open(options)

Exibe o iFrame pré-carregado e inicia o fluxo de mensagens entre sua página e a jornada Unico.

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

O callback onFinish recebe um objeto de processo com o ID da transação, uma URL de redirecionamento e o tipo de conclusão.

ByUnicoSDK.open({
  transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  onFinish: (process) => {
    console.log('Process finished', process);
    // process.transaction.redirectUrl — use this to navigate the user
  },
});

// 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:

Segurança

Opte pela solução de iFrame com token de autenticação em vez de CSP

Após análise cuidadosa, a abordagem escolhida usa iframes com tokens de autenticação em vez de implementar uma Content Security Policy (CSP). Essa decisão foi motivada pelos requisitos de segurança e pela flexibilidade necessária para atender às demandas dos clientes.

Contexto e desafios com CSP

Content Security Policy é uma ferramenta poderosa para proteger aplicações web contra ataques XSS e de injeção de código. No entanto, configurar uma política CSP exige a definição de uma lista estrita de domínios confiáveis. Essa abordagem é eficaz quando os domínios são fixos e previsíveis — mas para clientes que usam domínios dinâmicos e variáveis, essa configuração rígida apresenta desafios significativos.

Vulnerabilidade com domínios dinâmicos

Domínios dinâmicos representam um risco de segurança substancial ao usar CSP. Quando um cliente possui domínios que mudam com frequência ou são criados dinamicamente, a política CSP precisa ser constantemente atualizada para incluir os novos domínios. Isso não apenas aumenta a carga de manutenção, mas também expõe cada domínio listado na política como uma superfície de ataque potencial se não for gerenciado adequadamente.

Solução com iFrame e token de autenticação

Para mitigar esses riscos e atender à flexibilidade exigida pelos clientes, a solução escolhida combina iframes com tokens de autenticação, fornecendo uma camada adicional de segurança sem exigir uma lista estática de domínios.

Como funciona:

• Autenticação segura — cada iFrame é carregado com um token de autenticação único por transação, garantindo que apenas usuários autorizados possam acessar o conteúdo. O token é verificado em tempo real.
• Isolamento de conteúdo — o iFrame é executado em um contexto de navegação separado, reduzindo o risco de interferência entre diferentes origens e mitigando possíveis ataques.
• Flexibilidade para domínios dinâmicos — ao não depender de uma política CSP estática, a solução se adapta a domínios dinâmicos dos clientes sem exigir atualizações constantes de política.