# Integração

> Entenda como o SDK do Proteside funciona no checkout antes de instalar.

URL: https://docs.proteside.com/pt-BR/docs/integration

O Proteside é um SDK client-side que roda nas páginas de pagamento da sua loja. Ele mantém o inventário dos scripts
que executam no navegador do cliente, detecta adulterações (skimming, troca de chave Pix, sequestro de formulário,
exfiltração de dados) e envia as evidências para o dashboard. Essas evidências apoiam os controles do PCI DSS 4.0,
requisitos 6.4.3 e 11.6.1.

Esta seção explica a instalação no checkout e o comportamento do SDK no navegador. Para usar o dashboard no dia a dia,
veja o [Guia do usuário](https://docs.proteside.com/pt-BR/docs/guide). Se você ainda está avaliando o produto, comece por
[Como o Proteside funciona](https://proteside.com/como-funciona).

## Como funciona
A instalação é um único bloco de código colado no `<head>` do checkout. Por dentro, ele tem duas partes com papéis
diferentes:

1. **Bootstrapper (inline e síncrono).** Um `<script>` pequeno, colado direto no HTML, que precisa ser o **primeiro
   script do `<head>`**. Ele não faz nenhuma requisição de rede. O bootstrapper começa a observar a página
   imediatamente, antes de qualquer outro script, e barra scripts proibidos pelas suas regras antes de entrarem na
   página.
2. **SDK `shield.js` (assíncrono, servido pela CDN).** Carregado de `https://cdn.proteside.com/v1/shield.js` com
   `async`, sem bloquear a renderização. Ele lê a chave do atributo `data-key`, busca a configuração da loja e inicia
   os módulos de detecção.
3. **Configuração remota.** Ao iniciar, o SDK busca em `app.proteside.com` o que você definiu no dashboard: modo de
   proteção, regras, recebedores confiáveis, origens de iframe esperadas e ajustes finos. As alterações chegam ao
   checkout em poucos minutos.
4. **Envio de eventos.** As detecções e a telemetria vão em lotes pequenos para `app.proteside.com`. O dashboard
   transforma os eventos relevantes em alertas, atualiza o inventário de **Scripts** e a **Saúde do SDK**.

> **Por que duas partes?**
>
> Um script carregado com `async` executa depois de outros scripts da página. Só um trecho inline e síncrono, colocado
> antes de todos, garante cobertura completa desde o início do carregamento. Por isso o bootstrapper nunca deve ser
> trocado por um `<script src>` externo.

## O que o Proteside detecta
* **Scripts novos ou alterados** depois que a página carregou, classificados como próprios, de terceiros conhecidos
  ou desconhecidos.
* **Scripts bloqueados** pelas suas regras e containers do Google Tag Manager fora da lista permitida.
* **Keyloggers:** um script passa a capturar o que é digitado em um campo sensível.
* **Exfiltração:** dados sensíveis do cliente são enviados a um destino não confiável.
* **Adulteração do pagamento:** troca do código Pix copia e cola, de endereço cripto, de VPA UPI, de banco do boleto
  ou do valor; troca do conteúdo copiado para a área de transferência.
* **Sequestro de formulário e de iframe:** mudança do `action` de um formulário, troca do iframe do provedor de
  pagamento, iframes inesperados e elementos sobrepostos aos campos de pagamento.
* **Service workers** não autorizados.
* **Headers de segurança** da página de pagamento (CSP, HSTS e outros), para detectar mudanças.

A lista completa, com severidades, está em [Eventos e detecções](https://docs.proteside.com/pt-BR/docs/integration/events).

## O que o Proteside não coleta
O SDK foi desenhado para não transportar dados de pagamento:

* nunca lê o valor digitado em campos de formulário nem registra teclas;
* nunca envia número de cartão, CVV, chave Pix, código copia e cola, endereço cripto ou linha digitável;
* nunca envia o conteúdo copiado para a área de transferência, o corpo das requisições ou o código dos scripts (só
  hashes, tamanhos e nomes de padrões encontrados);
* não grava cookies nem `localStorage`.

Há pontos que você precisa conhecer, como o envio da URL completa da página. Veja
[Privacidade e LGPD](https://docs.proteside.com/pt-BR/docs/integration/privacy).

## Do primeiro pageview ao dashboard
O que acontece quando um cliente abre o checkout com o snippet instalado:

1. O navegador executa o bootstrapper (menos de 1 ms) e continua carregando a página normalmente.
2. O `shield.js` chega da CDN e busca a configuração da loja.
3. O SDK envia um `PAGEVIEW`. Logo após o carregamento, o SDK estabelece a referência da página. Scripts presentes
   nesse momento entram no inventário e precisam da sua revisão em **Scripts**.
4. Scripts que o dashboard ainda não conhece aparecem em **Scripts** com o status **Precisa revisão**.
5. A partir daí, qualquer script novo ou comportamento suspeito vira uma detecção.
6. Os eventos são enviados em lotes pequenos e quando o cliente sai da página. O indicador **Proteside ativo** no
   topo do dashboard e a página **Saúde do SDK** passam a refletir o tráfego real.

> **Nota**
>
> A decisão sobre cada script do inventário (autorizar ou bloquear) é sua, na página [Scripts](https://docs.proteside.com/pt-BR/docs/guide/scripts).

## Próximos passos
- [Instalação do snippet](https://docs.proteside.com/pt-BR/docs/integration/install): Onde obter o snippet e onde colar.
- [Instalação por plataforma](https://docs.proteside.com/pt-BR/docs/integration/platforms): HTML, Next.js, Nuxt, WordPress e outras plataformas.
- [Verificar a instalação](https://docs.proteside.com/pt-BR/docs/integration/verify): Confirme que o SDK está ativo.
- [Configuração](https://docs.proteside.com/pt-BR/docs/integration/configuration): Atributos, configuração remota e modos de proteção.
- [Integridade de pagamento e Pix](https://docs.proteside.com/pt-BR/docs/integration/payment-integrity): Recebedores confiáveis e validação do pagamento.
- [API JavaScript](https://docs.proteside.com/pt-BR/docs/integration/javascript-api): Métodos de window.Proteside.
- [Eventos e detecções](https://docs.proteside.com/pt-BR/docs/integration/events): Tipos de evento, severidade e alertas.
- [CSP e headers](https://docs.proteside.com/pt-BR/docs/integration/csp): Content Security Policy e relação com o PCI DSS.
- [Privacidade e LGPD](https://docs.proteside.com/pt-BR/docs/integration/privacy): O que é coletado e o que nunca é.
- [Desempenho e compatibilidade](https://docs.proteside.com/pt-BR/docs/integration/performance): Tamanho, carregamento e navegadores.
- [Selo Proteside](https://docs.proteside.com/pt-BR/docs/integration/badge): Selo estático opcional para o checkout.
- [Solução de problemas](https://docs.proteside.com/pt-BR/docs/integration/troubleshooting): Erros comuns e como resolver.
