Proteside Docs

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:

  1. Configuração remota (o que está salvo no dashboard);
  2. Snippet (atributos data-* e regras inline);
  3. 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 1 da tela Proteção do pagamento: como a verificação funciona, recebedores vistos no checkout, recebedores confiáveis e cadastro manual
Passo e ajuste no dashboardEfeito no SDK
Quem pode receber o seu dinheiro → Recebedores confiáveisChaves Pix, contas, carteiras cripto e bancos de boleto da loja. Veja Integridade de pagamento e Pix.
Como o SDK deve reagir → Modo de proteçãoMonitorar ou Bloquear. Veja abaixo.
Como o SDK deve reagir → Opções para a equipe técnica → Modo desenvolvedorPausa o SDK. Veja Pausa e modo desenvolvedor.
Como o SDK deve reagir → Opções para a equipe técnica → Canal de release do SDKSó informativo para o SDK. O canal efetivo é a URL colada no snippet. Veja Canais.
O que é normal no seu checkout → Origens de iframe esperadasHosts 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 permitidosCom 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 detectadosSó 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.com e app.proteside.com nunca 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çãoAção no modo Bloquear
SCRIPT_INJECTION de script desconhecidoRemove a tag do script depois de detectar.
FORM_ACTION_HIJACKRestaura o action original do formulário.
OVERLAY_DETECTEDRemove 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áveisTroca o texto lido por ⚠︎ e marca o elemento com data-proteside-blocked="untrusted_recipient".
CLIPBOARD_HIJACKRegrava a área de transferência com o valor original.
SERVICE_WORKER_BLOCKEDRemove 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.

Próximos passos

Nesta página