SDK

O uso de integrações que não estejam em conformidade com os padrões estabelecidos nesta documentação pode resultar em interrupções inesperadas no funcionamento do sistema, as quais não serão cobertas ou suportadas pelo by Unico.

Ex: Implementar o SDK (iFrame) dentro de uma webview, implementar iFrame através de uma tag de HTML, etc.

Como começar

Para utilizar o by Unico por meio do SDK do by Unico, o primeiro passo é cadastrar os domínios, sempre utilizando o protocolo HTTPS, que serão utilizados como host para exibir o iFrame da jornada do usuário no by Unico.

Sinalize o responsável pelo seu projeto de integração ou o time de suporte da Unico para realizar essa configuração.

Para começar a usar o SDK, é necessário realizar a instalação do SDK Web da Unico. Vale destacar que o "by Unico" utiliza o mesmo SDK empregado no IDPay:

$ npm install idpay-b2b-sdk

Quando instalar o pacote do SDK da Unico, implemente sem especificar a versão que está utilizando e de modo que seu gerenciador de dependências atualize sempre os minors e patches para a versão mais recente.

Para verificar versões anteriores, acesse https://www.npmjs.com/package/idpay-b2b-sdk?activeTab=versions.

Métodos disponíveis

1

init(options)

Esse método inicializa o SDK, fazendo um pré-carregamento de assets, criando a experiência mais fluida para o usuário final. Nesse momento é preciso enviar o token recebido como resultado do CreateProcess.

Parâmetros:

• options - é um objeto com as seguintes propriedades de configuração:

  • type

    • O tipo de fluxo que será inicializado. No by Unico utilizamos a opção "IFRAME".

  • token

    • Recebe o token do processo criado. Esse token é importante para conseguirmos autenticar a jornada e garantir que somente domínios autorizados utilizem-na (pode ser obtido na criação do processo via API).

import { ByUnicoSDK } from “idpay-b2b-sdk”;

ByUnicoSDK.init({
  type: 'IFRAME',
  env: 'uat'// Só irá ser preenchido se for ambiente de testes.
  token,
});

2

open(options)

Esse método realiza a abertura da experiência do by Unico. Para o fluxo do tipo IFRAME, essa função exibe o iframe já pré-carregado, e inicia o fluxo de mensageria entre a página do cliente e a experiência do by Unico.

Parâmetros:

options - é um objeto com propriedades de configuração:

• processId

  • Recebe o ID do processo criado. Esse ID é importante para conseguirmos obter os detalhes do processo e realizarmos todo o fluxo da maneira correta (pode ser obtido na criação do processo via API).

• token

  • Recebe o token do processo criado. Esse token é importante para conseguirmos autenticar a jornada e garantir que somente domínios autorizados utilizem-na (pode ser obtido na criação do processo via API).

• onFinish(process)

  • Recebe uma função de callback que será executada no término da jornada do by Unico, passando como argumento o objeto do processo com os seguintes dados: { captureConcluded, concluded, id }

const processId = '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf';
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';

const process = {
  id: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  concluded: true,
  captureConcluded: true
};

const onFinishCallback = process => {
  console.log('Process', process);
}

ByUnicoSDK.open({
  transactionId: processId,
  token: token,
  onFinish: onFinishCallback
});

// Você também pode encerrar o SDK explicitamente através do método abaixo
ByUnicoSDK.close();

O diagrama de sequência abaixo demonstra como utilizar o SDK e o resultado da API do by Unico para configurar o iFrame:

Segurança​

Escolha pela Solução de Iframe com Auth Token em vez de CSP

​Após uma análise cuidadosa das necessidades e desafios que enfrentamos, decidimos adotar uma solução baseada em iframes com tokens de autenticação ao invés de implementar uma política de Content Security Policy (CSP). Essa escolha foi motivada por diversas considerações relacionadas à segurança e à flexibilidade necessárias para atender às demandas dos nossos clientes.

Contexto e Desafios com CSP

​O Content Security Policy (CSP) é uma ferramenta poderosa para proteger aplicações web contra diversos tipos de ataques, como Cross-Site Scripting (XSS) e injeção de código. No entanto, ao configurar uma política CSP, é necessário definir uma lista rígida de domínios confiáveis. Essa abordagem é eficaz quando os domínios são fixos e previsíveis. No entanto, para nossos clientes, que frequentemente utilizam domínios dinâmicos e variáveis, essa configuração rígida apresenta desafios significativos.

Vulnerabilidade com Domínios Dinâmicos

Os domínios dinâmicos representam um risco substancial para a segurança ao usar CSP. Quando um cliente possui domínios que mudam com frequência ou são criados dinamicamente, seria necessário atualizar constantemente a política CSP para incluir esses novos domínios. Isso não só aumenta o esforço de manutenção, mas também expõe os domínios aos quais a política CSP se aplica. Cada domínio adicionado à política CSP é potencialmente um ponto de vulnerabilidade se não for adequadamente gerenciado.

Solução com Iframe e Auth Token

Para mitigar esses riscos e atender à flexibilidade exigida pelos nossos clientes, optamos por utilizar iframes combinados com tokens de autenticação. Esta solução oferece uma camada adicional de segurança e evita a necessidade de expor ou gerenciar uma lista extensa e dinâmica de domínios.

Como funciona​

• Autenticação Segura: Cada iframe é carregado com um token de autenticação exclusivo para cada transação, garantindo que apenas usuários autorizados possam acessar o conteúdo. Esse token é verificado em tempo real, proporcionando uma camada adicional de segurança e controle.

• Isolamento de Conteúdo: O uso de iframes permite isolar o conteúdo em um contexto separado, reduzindo o risco de interferência entre diferentes origens e mitigando potenciais ataques.

• Flexibilidade para Domínios Dinâmicos: Ao não depender de uma política CSP estática, nossa solução se adapta facilmente aos domínios dinâmicos dos clientes, sem a necessidade de atualização constante das políticas de segurança.