Solução de problemas
Causas e soluções para os problemas mais comuns na instalação e no uso do SDK no checkout.
Antes de tudo, abra o checkout com as ferramentas de desenvolvedor do navegador e rode Proteside.getStatus() no
console. O resultado indica a maioria dos problemas abaixo. Veja Verificar a instalação.
Instalação
O dashboard só considera o SDK ativo quando recebe eventos de clientes reais. Confira, na ordem:
- O snippet está publicado? Veja o código-fonte da página de checkout publicada e procure
Proteside Start. Limpe caches do site, do tema e da CDN. - Está no domínio certo? O snippet precisa estar nas páginas em que o checkout roda de fato, que podem ficar em outro domínio ou subdomínio.
- Alguém abriu o checkout? Abra a página você mesmo e recarregue o dashboard depois de alguns segundos.
- O SDK carrega? Rode
Proteside.getStatus()no console. Se der erro, veja o item seguinte. - Os eventos saem? Na aba Rede, as requisições para
app.proteside.comdevem responder com sucesso. Veja o item O SDK roda, mas nada chega ao dashboard.
Se a página Saúde do SDK mostra Só verificação sintética, o verificador do Proteside encontrou o snippet, mas nenhum cliente real passou pelo checkout ainda.
O shield.js não carregou. Causas comuns:
- o snippet não está publicado, ou só o bootstrapper foi colado;
- a Content Security Policy não permite
https://cdn.proteside.comemscript-src(o console mostraRefused to load the script); - uma extensão de bloqueio de anúncios ou rastreadores bloqueou o arquivo (teste em uma janela anônima sem extensões);
- um plugin de otimização alterou ou removeu a tag.
Espere alguns segundos: o SDK só termina de iniciar depois de carregar a configuração da loja. Se continuar false:
- Falta o
data-keyna tag doshield.js. Sem ele, o SDK não inicializa e não mostra aviso. - A chave tem formato inválido. O console mostra
[Proteside] Initialization failed silentlycomInvalid apiKey format. A chave começa compk_live_. - A tag foi carregada como
type="module". Remova esse atributo.
O SDK envia esse aviso, e getStatus().installationOrderValid fica false, quando existe algum <script> na página
antes do snippet. O snippet deve ser o primeiro script do <head> para cobertura completa.
Para conferir, abra o código-fonte da página publicada (Ctrl+U) e veja se o bloco <!-- Proteside Start --> vem logo
depois da abertura do <head>, antes de qualquer outro <script>.
Como corrigir:
- Há outro script antes do snippet. Mova o snippet para o topo do
<head>e publique de novo. Em Next.js, confira a ordem final das tags no código-fonte da página publicada. - O snippet é antigo. Snippets antigos traziam a configuração inline numa tag
<script>separada. Copie o snippet atual em Páginas e Domínios e substitua o bloco inteiro. - O script anterior vem do tema, de um plugin ou da própria plataforma e não pode ser movido. A proteção continua funcionando, mas com cobertura parcial. Se você aceita essa situação, use Não avisar mais nesta loja no próprio alerta. Só proprietários e administradores veem essa opção. Para voltar a receber o aviso, escreva para team@proteside.com.
Não edite o conteúdo do snippet para fazer o aviso sumir: as regras inline bloqueiam scripts desde o primeiro byte da página.
Depois de corrigir, resolva o alerta no dashboard. Se ele não voltar no próximo acesso à página, a ordem está certa.
Esse aviso não entra no status de conformidade em Evidências PCI DSS.
O snippet tem duas partes, e as duas são necessárias para cobertura completa. Se só a tag do shield.js foi colada,
ou se um plugin de otimização transformou o bootstrapper em arquivo externo ou adiado, recole o snippet completo e
exclua-o das otimizações de JavaScript.
Para conferir, abra o código-fonte da página publicada (Ctrl+U): entre <!-- Proteside Start --> e
<!-- Proteside End --> precisa haver um <script> inline seguido da tag do shield.js.
A URL do shield.js (canal stable ou latest) está escrita no snippet. Depois de trocar o canal em
Proteção do pagamento, copie o snippet de novo em Páginas e Domínios e publique.
Se a Saúde do SDK mostra mais de uma versão ativa por alguns dias, verifique se todas as páginas usam o mesmo snippet. Logo depois de uma atualização, é normal ver duas versões por causa do cache do navegador e da CDN.
Bloqueios e regras
Mensagens comuns no console e o que liberar:
| Mensagem | O que falta |
|---|---|
Refused to load the script 'https://cdn.proteside.com/…' | https://cdn.proteside.com em script-src |
Refused to execute inline script | hash, nonce ou 'unsafe-inline' para o bootstrapper |
Refused to connect to 'https://app.proteside.com/…' | https://app.proteside.com em connect-src |
A mensagem de script inline informa o hash 'sha256-…' a incluir. Veja
Content Security Policy e headers.
Com Containers GTM permitidos preenchido, tags do Google Analytics 4 (G-…) e do Google Ads (AW-…) podem ser
barradas, inclusive quando disparadas pelo próprio GTM. A lista só aceita IDs GTM-…, então não há como liberar esses
IDs.
Para resolver:
- Em Proteção do pagamento, passo O que é normal no seu checkout, esvazie a lista Containers GTM permitidos e clique em Salvar esta etapa.
- Copie o snippet de novo em Páginas e Domínios e publique. A lista também fica gravada no snippet e continua bloqueando no início do carregamento até você recolar.
O bloqueio vale nos dois modos de proteção, Monitorar e Bloquear.
- O script está no HTML da página. Em Scripts, ele aparece com o aviso de que continua carregando pelo HTML. Remova a tag na origem (HTML ou tema).
- A regra é por Hash de conteúdo. O bloqueio no navegador vale para scripts carregados por endereço; scripts inline devem ser removidos na origem. Use uma regra por Domínio ou URL do script.
- A regra está inativa. Ative a regra em Regras.
- A mudança ainda não chegou. Veja Uma mudança no dashboard não chegou ao checkout.
- Em Regras, desative a regra que casa com o script afetado. Lembre-se de que uma regra por Domínio bloqueia o domínio inteiro e todos os subdomínios.
- Copie o snippet de novo em Páginas e Domínios e publique: as regras ficam gravadas no snippet.
- Se ligou o modo Bloquear, volte para Monitorar enquanto investiga.
Ligar o Modo desenvolvedor não desfaz os bloqueios gravados no snippet. Veja Pausa e modo desenvolvedor.
Dados no dashboard
É o esperado. Todo script novo encontrado pelo SDK entra no inventário com o status Precisa revisão e espera a sua decisão. Para cumprir o PCI DSS 4.0, requisito 6.4.3, autorize cada script legítimo com uma justificativa ou bloqueie os indevidos. Você pode autorizar todos os scripts próprios de uma vez e criar políticas para automatizar decisões recorrentes.
Um script autorizado volta para Precisa revisão quando o conteúdo muda ou quando a validade da autorização vence. Veja Scripts e Políticas.
- Tempo de propagação: as alterações chegam ao checkout em poucos minutos. Aguarde e recarregue o checkout.
- Regras e containers GTM: ficam gravados no snippet. Recole o snippet depois de mudá-los.
- Canal de release: exige recolar o snippet.
Veja as respostas das requisições para app.proteside.com na aba Rede:
| Resposta | Causa | O que fazer |
|---|---|---|
| Erro 4xx | Problema de chave ou de conta. | Confira em Saúde do SDK. Se você trocou a chave, copie o snippet atual em Páginas e Domínios. Se a assinatura não está vigente, veja Cobrança. |
| Requisição bloqueada | CSP sem https://app.proteside.com em connect-src, ou bloqueador de anúncios. | Veja CSP e headers. |
Um domínio que já enviou eventos parou de receber sessões reais. O alerta aparece em até um dia. Verifique se o snippet ainda está publicado (uma atualização de tema ou de template pode removê-lo) e se o checkout recebeu visitas no período. O alerta é resolvido sozinho quando o tráfego volta.
Pagamento
- Nenhum cliente pagou com Pix ainda com o SDK na página. O status muda quando o SDK valida o primeiro código.
- O código Pix não aparece como texto visível. Para cobertura completa, exiba o código de pagamento como texto
visível ou informe-o com
registerPaymentPayload(). Veja Integridade de pagamento e Pix. - O snippet não está na página que mostra o Pix, por exemplo uma página de pagamento separada do checkout.
O recebedor lido no código não está entre os Recebedores confiáveis. Antes de tratar como ataque, confira:
- se a chave cadastrada é a mesma que aparece no código copia e cola gerado pelo seu provedor de pagamento. Alguns provedores geram o código com uma chave própria, diferente da chave da loja. Nesse caso, confirme o recebedor em Recebedores vistos no seu checkout com É da minha loja;
- se todas as chaves usadas pela loja estão cadastradas e ativas.
Se a chave do código não pertence à loja nem ao seu provedor, trate como incidente: abra o alerta em Alertas.
No Pix dinâmico gerado por um provedor de pagamento, o código traz o endereço do provedor no lugar da chave da loja. Confirme o recebedor em Proteção do pagamento → Recebedores vistos no seu checkout com É da minha loja: a chave usada pelo provedor costuma não ser a que você conhece. A verificação de recebedor se aplica aos códigos que trazem o recebedor.
Se o código traz o valor, informe também o valor esperado com
Proteside.expectPayment().
Ainda com problemas?
Junte o resultado de Proteside.getStatus(), as respostas das requisições para app.proteside.com na aba Rede e
o endereço da página afetada, e escreva para team@proteside.com.