Configuração
Atributos do snippet, configuração remota, modos monitor e bloqueio, pausa e canais.
Quase toda a configuração do SDK é feita no dashboard e chega ao navegador pela configuração remota. O snippet só carrega a chave da loja e, quando há, as regras inline. Esta página mostra de onde vem cada ajuste e o que ele faz de fato no checkout.
Atributos do snippet
O shield.js lê os atributos data-* da própria tag <script>:
Propriedade
Tipo
Não existem outros atributos. O modo de proteção e o canal não são definidos por atributo: o modo vem do
dashboard e o canal é a própria URL do shield.js. O atributo data-safe-url, de versões antigas do snippet, é
ignorado.
Configuração remota
Ao iniciar, o SDK busca a configuração da loja em app.proteside.com. Quando as camadas divergem, vale esta ordem de
prioridade:
- Configuração remota (o que está salvo no dashboard);
- Snippet (atributos
data-*e regras inline); - Padrões do SDK.
Chave inválida, erro ou falta de rede nunca quebram a página. As alterações chegam ao checkout em poucos minutos. Para conferir uma mudança, aguarde alguns minutos e recarregue o checkout.
O que vem do dashboard
A maior parte fica em Configurações → Proteção do pagamento, organizada em quatro passos:

| Passo e ajuste no dashboard | Efeito no SDK |
|---|---|
| Quem pode receber o seu dinheiro → Recebedores confiáveis | Chaves Pix, contas, carteiras cripto e bancos de boleto da loja. Veja Integridade de pagamento e Pix. |
| Como o SDK deve reagir → Modo de proteção | Monitorar ou Bloquear. Veja abaixo. |
| Como o SDK deve reagir → Opções para a equipe técnica → Modo desenvolvedor | Pausa o SDK. Veja Pausa e modo desenvolvedor. |
| Como o SDK deve reagir → Opções para a equipe técnica → Canal de release do SDK | Só informativo para o SDK. O canal efetivo é a URL colada no snippet. Veja Canais. |
| O que é normal no seu checkout → Origens de iframe esperadas | Hosts dos iframes legítimos de pagamento. Com a lista preenchida, o SDK alerta iframes de provedores fora dela, iframes sobrepostos aos esperados e campos de cartão digitáveis fora do iframe. |
| O que é normal no seu checkout → Containers GTM permitidos | Com a lista preenchida, containers fora dela são barrados. Veja o aviso abaixo. |
| O que é normal no seu checkout → Service workers permitidos (avançado) | Com a lista preenchida, service workers fora dela são reportados e, no modo Bloquear, removidos. |
| Meios de pagamento detectados | Só leitura. O SDK reconhece sozinho os meios de pagamento da página; não há nada para marcar. |
| Campos extras para vigiar → Seletores extras (opcional) | Campos sensíveis com nome fora do padrão. Os seletores somam à detecção automática; nada é desligado. |
O aviso de ordem de instalação não é mais configurado nesta tela. O próprio alerta INSTALLATION_ORDER_WARNING
oferece a opção Não avisar mais nesta loja. Veja Solução de problemas.
As regras de Regras (bloquear ou permitir por Domínio ou URL do script) também chegam pela configuração remota.
Bloqueio por endereço
O bloqueio no navegador vale para scripts carregados por endereço; scripts inline devem ser removidos na origem. Para impedir um script, use uma regra por Domínio ou URL do script.
Campos sensíveis
O SDK reconhece os campos de cartão mais comuns; marque outros com data-proteside-sensitive ou configure em
Proteção do pagamento.
Para incluir um campo próprio sem mexer no dashboard, marque-o com o atributo data-proteside-sensitive:
<input id="cpf" name="cpf" data-proteside-sensitive />No dashboard, use Campos extras para vigiar → Seletores extras (opcional), com um seletor CSS por linha. O que você adicionar soma à detecção automática: a lista não substitui os campos que o SDK já reconhece.
Modo monitor e modo bloqueio
O modo é escolhido em Proteção do pagamento → Como o SDK deve reagir → Modo de proteção e chega ao SDK pela configuração remota.
O que acontece em qualquer modo
Regras e lista de GTM bloqueiam também no modo Monitorar
As regras de bloqueio (por domínio ou URL) e a lista de Containers GTM permitidos bloqueiam scripts nos dois modos. O modo decide só as reações automáticas do SDK ao que não tem regra. Se você quer só observar, não crie regras de bloqueio e deixe a lista de GTM vazia.
- Um script que casa com uma regra de bloqueio é barrado antes de entrar na página, e o SDK envia
SCRIPT_BLOCKED. Scripts escritos no HTML da página devem ser removidos na origem. - Com a lista de GTM preenchida, containers fora dela são barrados. O SDK envia
GTM_CONTAINER_BLOCKED. - Uma regra Permitir que case com o script anula as regras de bloqueio.
cdn.proteside.comeapp.proteside.comnunca são bloqueados.
A lista de GTM também pode barrar GA4 e Google Ads
A lista aceita só IDs no formato GTM-XXXXXXX. Com ela preenchida, tags do Google Analytics 4 (G-…) e do Google
Ads (AW-…) também podem ser barradas, inclusive quando disparadas pelo próprio GTM, e não há como incluir esses IDs
na lista. Antes de ativar a lista, confirme se a loja usa essas tags e teste o checkout.
O que muda no modo Bloquear
Além de alertar, o SDK tenta neutralizar a adulteração:
| Detecção | Ação no modo Bloquear |
|---|---|
SCRIPT_INJECTION de script desconhecido | Remove a tag do script depois de detectar. |
FORM_ACTION_HIJACK | Restaura o action original do formulário. |
OVERLAY_DETECTED | Remove o elemento sobreposto. |
PIX_TAMPERED, UPI_TAMPERED, QR_TAMPERED, BOLETO_TAMPERED, CRYPTO_ADDRESS_SWAP (texto alterado) | Reescreve o texto com o valor original capturado. |
| Recebedor fora da lista de confiáveis | Troca o texto lido por ⚠︎ e marca o elemento com data-proteside-blocked="untrusted_recipient". |
CLIPBOARD_HIJACK | Regrava a área de transferência com o valor original. |
SERVICE_WORKER_BLOCKED | Remove o registro do service worker. |
Para um script indesejado, crie também uma regra de bloqueio em Regras. Detecções de envio de dados exigem ação imediata a partir do alerta.
No modo Bloquear, uma regra errada pode quebrar o checkout. Comece em Monitorar, revise os alertas por algumas semanas e teste o modo Bloquear em uma página de baixo tráfego antes de ativar em toda a loja.
Pausa e modo desenvolvedor
O SDK fica pausado quando:
- o Modo desenvolvedor está ligado em Proteção do pagamento → Como o SDK deve reagir → Opções para a equipe técnica;
- a assinatura não está vigente ou a loja não está ativa.
Pausado, o SDK não executa proteções e a Saúde do SDK mostra SDK pausado (modo desenvolvedor).
Regras inline continuam valendo no modo desenvolvedor
As regras gravadas no snippet continuam valendo com o modo desenvolvedor ligado: os scripts que casam com elas continuam bloqueados, mas sem nenhum evento no dashboard. Se precisar desativar um bloqueio durante a integração, remova a regra e recole o snippet.
Canais
O canal de release (stable ou latest) é definido pela URL do shield.js no snippet. Veja
Canais stable e latest.