# SDK

Para o cenário de uso em Web, o uso do SDK da Unico é o recomendado, pelos seguintes motivos:

* Maior segurança;
* Experiência integrada ao seu fluxo;
* Taxa maior de conversão quando usado o SDK;
* Facilidade na implementação.

{% hint style="warning" %}
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 IDPay.

*Ex: Implementar o iFrame do by Unico dentro de uma webview, implementar o iFrame através de uma tag de HTML, etc.*
{% endhint %}

## Orientações gerais

Para otimizar a performance da sua operação, melhorar a taxa de conversão e proporcionar uma experiência mais fluida para o usuário final, é obrigatório que a SDK da Unico seja sempre implementada em modo `full screen`(tela cheia) na sua aplicação. Confira como deve ser a implementação no exemplo abaixo:

<figure><img src="/files/nO0AFITzFMSBLwDX8OrP" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/7YeCfZj6O1Pk55P7hUn0" alt=""><figcaption></figcaption></figure>

## Como começar <a href="#como-comecar" id="como-comecar"></a>

Para utilizar o IDPay por meio do SDK do Unico IDPay, o primeiro passo é cadastrar os domínios que serão utilizados como host para exibir a experiência da jornada do usuário.

{% hint style="danger" %}
Sinalize o responsável pelo seu projeto de integração ou o time de suporte da Unico para realizar essa configuração.
{% endhint %}

Para iniciar o uso do SDK, devemos iniciar com a instalação da SDK web da Unico:

```javascript
$ npm install idpay-b2b-sdk
```

{% hint style="success" %}
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>.
{% endhint %}

## **Métodos disponíveis**

{% stepper %}
{% step %}

### **init(options)**

Esse método permite que o SDK seja inicializado, independentemente de um ID de transação, fazendo com que a experiência do usuário final seja mais fluida. Uma vez que quando o ID da transação e o token estiverem disponíveis, a aplicação já tenha sido pré-carregada através desse método. Se esse método não for chamado diretamente pela aplicação, o usuário final terá um carregamento longo na primeira abertura do SDK.

#### Parâmetros:

* *options*
  * Recebe um objeto com propriedades de configuração:
    * *type*
      * O tipo de fluxo que será inicializado. Hoje, disponibilizamos dois tipos de fluxos (IFRAME). Para novas aplicações, recomendamos o uso do tipo IFRAME, tornando a experiência para o usuário final muito mais fluida e com menos fricção, já que não será necessário sair da tela de checkout, e o carregamento da experiência poderá ser realizado previamente.

```javascript
import { IDPaySDK } from “idpay-b2b-sdk”;

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

{% endstep %}

{% step %}

### **open({ transactionId, token, onFinish? })**

Esse método realiza a abertura da experiência do IDPay de acordo com o fluxo escolhido previamente, na função de inicialização. Para o fluxo do tipo REDIRECT, essa função faz um simples redirecionamento para a rota do fluxo de captura do IDPay. 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 IDPay.

#### Parâmetros:

* *options*
  * Recebe um objeto com propriedades de configuração:
    * *transactionId*
      * Recebe o ID da transação criada. Esse ID é importante para conseguirmos obter os detalhes da transação e realizarmos todo o fluxo da maneira correta (pode ser obtido na criação da transação via API).
    * *token*
      * Recebe o token da transação criada. Esse token é importante para conseguirmos autenticar a transação e garantir que somente domínios autorizados utilizem-na (pode ser obtido na criação da transação via API).
    * *opcional onFinish(transaction, type)*
      * Recebe uma função de callback que será executada no término do fluxo de captura do IDPay, passando dois argumentos:
        * O objeto da transação com os seguintes dados: **{ captureConcluded, concluded, id }**
          * O tipo da resposta que pode ser **FINISH**, para casos onde o fluxo foi finalizado com sucesso, ou **ERROR**, para casos onde o fluxo foi interrompido por um erro¹.

\[1] em casos de erro no fluxo, a transação não terá seu status alterado e um callback via webhook, caso configurado, não será realizado.

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

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

const onFinish = (transaction, type) => {
  console.log('response', transaction, type);
}

IDPaySDK.open({
  transactionId,
  token,
  onFinish
});

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

{% endstep %}
{% endstepper %}

### Segurança[​](https://developers.unico.io/docs/idPay/sdk-guides/languages/Web/iframe#seguran%C3%A7a) <a href="#seguranca" id="seguranca"></a>

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**

[**​**](https://developers.unico.io/docs/idPay/sdk-guides/languages/Web/iframe#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**[**​**](https://developers.unico.io/docs/idPay/sdk-guides/languages/Web/iframe#solu%C3%A7%C3%A3o-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**[**​**](https://developers.unico.io/docs/idPay/sdk-guides/languages/Web/iframe#como-funciona)[PreviousWeb](https://app.gitbook.com/o/oXwaJDbmuu5wv042bkqn/s/mbfp7FKwpg3cwSHRBJ6w/~/changes/88/integracao/controlando-a-experiencia/web)

* **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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://devcenter.unico.io/unico-idpay/integracao/controlando-a-experiencia/web/sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.