Integração

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.

Como funcionaCopiar link da seção

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. Ele instala pontos de observação em fetch, XMLHttpRequest, navigator.sendBeacon, addEventListener, área de transferência, service workers e WebSocket. Também intercepta a inserção de novos <script src>, para barrar scripts proibidos pelas suas regras antes de eles entrarem na página. Tudo o que acontece antes de o SDK carregar fica guardado em memória.
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, inicia os módulos de detecção e processa o que o bootstrapper guardou.
3. Configuração remota. Ao iniciar, o SDK busca em https://app.proteside.com/api/sdk/config o que você definiu no dashboard: modo de proteção, regras, recebedores confiáveis, origens de iframe esperadas e ajustes finos. Se a resposta não chegar em 2 segundos, o SDK segue com os padrões locais.
4. Envio de eventos. As detecções e a telemetria vão em lotes para https://app.proteside.com/api/sdk/events. O dashboard transforma os eventos relevantes em alertas, atualiza o inventário de Scripts e a Saúde do SDK.

O que o Proteside detectaCopiar link da seção

• 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: scripts que passam a escutar teclas em campos de cartão ou outros campos sensíveis.
• Exfiltração: envio de número de cartão, CPF, CNPJ, e-mail ou chave Pix para domínios não confiáveis, por fetch, XHR, beacon ou imagem; conexões WebSocket para destinos desconhecidos.
• 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.

O que o Proteside não coletaCopiar link da seção

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.

Do primeiro pageview ao dashboardCopiar link da seção

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 (até 2 s).
3. O SDK envia um PAGEVIEW e começa a calibração: por 30 segundos (ajustável de 10 a 120 s), ele aprende os scripts, os listeners de campos sensíveis e os domínios de rede legítimos daquela página.
4. Logo no início, o SDK envia o inventário de scripts da página, com o hash do conteúdo quando ele é legível. Scripts que o dashboard ainda não conhece aparecem em Scripts com o status Precisa revisão.
5. Ao fim da calibração, qualquer script novo ou comportamento suspeito vira uma detecção.
6. Os eventos são enviados em lotes a cada 5 segundos, aproximadamente, 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.

Próximos passosCopiar link da seção