Instalação do snippet

A instalação é um bloco de código que você copia do dashboard e cola no <head> das páginas de checkout. Não há pacote npm nem app de loja: o mesmo snippet funciona em qualquer site em que você controle o HTML do checkout.

Onde obter o snippetCopiar link da seção

O snippet fica em Configurações → Páginas e Domínios, no card Instalação do SDK:

• Chave do SDK: a chave da loja, no formato pk_live_ seguido de 32 caracteres hexadecimais. É uma chave pública: ela vai no HTML da loja e só identifica a loja para o SDK.
• Snippet: o bloco pronto, já com a sua chave, o canal de release e as regras de bloqueio ativas. Há uma aba para cada plataforma: HTML, Next.js, Nuxt e WordPress.

O assistente de criação da loja também mostra o snippet, no passo de instalação. Aquele snippet sai sempre no canal stable e sem as suas regras. Se você já configurou regras ou containers do Google Tag Manager, copie o snippet de Páginas e Domínios.

InstalarCopiar link da seção

O que tem no snippetCopiar link da seção

Este é o formato do snippet HTML gerado pelo dashboard. O conteúdo do bootstrapper foi abreviado aqui: ele tem cerca de 4,3 KB de JavaScript minificado e muda entre versões. Copie sempre o bloco completo do dashboard.

<!-- Proteside Start -->
<!-- Place first in <head>, before GTM, Stripe.js, analytics, or any other scripts. -->
<script>/* bootstrapper: conteúdo completo copiado do dashboard */</script>
<script async src="https://cdn.proteside.com/v1/shield.js"
        data-key="pk_live_3f9c1a7b2e4d6f8a0c1e3b5d7f9a1c3e"
        data-api="https://app.proteside.com/api/sdk"></script>
<!-- Proteside End -->

Os comentários dentro do snippet ficam em inglês em qualquer idioma do dashboard. É o comportamento normal.

Snippet com regras inlineCopiar link da seção

Se a loja tem regras de bloqueio ativas por domínio ou por URL, ou uma lista de containers do Google Tag Manager permitidos, o dashboard grava essa configuração no início do próprio <script> do bootstrapper:

<!-- Proteside Start -->
<!-- Place first in <head>, before GTM, Stripe.js, analytics, or any other scripts. -->
<script>"use strict";window.__PROTE_INLINE__={"rules":[{"type":"block","target":"domain","value":"cdn-suspeito.example"}],"gtm":["GTM-AB12CD3"]};var __ProteBoots=/* restante do bootstrapper, copiado do dashboard */</script>
<script async src="https://cdn.proteside.com/v1/shield.js"
        data-key="pk_live_3f9c1a7b2e4d6f8a0c1e3b5d7f9a1c3e"
        data-api="https://app.proteside.com/api/sdk"></script>
<!-- Proteside End -->

Esse trecho permite que o bootstrapper bloqueie scripts desde o primeiro byte da página, sem esperar a configuração remota.

Por que o primeiro script do headCopiar link da seção

O bootstrapper só observa o que acontece depois dele. Um script que executa antes pode guardar referências originais de fetch ou addEventListener e escapar da observação.

Se houver qualquer script antes do bootstrapper, o SDK marca a instalação como fora de ordem: envia o evento INSTALLATION_ORDER_WARNING, que vira alerta no dashboard, e Proteside.getStatus().installationOrderValid fica false. A proteção continua, mas com cobertura parcial.

Scripts que estão escritos no HTML da página executam antes de o SDK carregar e não podem ser impedidos no navegador. Para bloquear um desses, remova a tag do HTML ou do tema. Scripts inseridos por JavaScript, inclusive tags disparadas pelo Google Tag Manager, passam pelo bootstrapper e são bloqueados antes de executar.

Em quais páginas instalarCopiar link da seção

Instale o snippet nas páginas em que o cliente informa ou recebe dados de pagamento:

• o checkout, incluindo as etapas de entrega e pagamento, quando forem páginas separadas;
• as páginas que exibem o QR code ou o código Pix copia e cola, o boleto ou o endereço cripto;
• a página de confirmação do pedido (por exemplo, /obrigado ou /sucesso), se você aceita cartão. O SDK usa essa página para confirmar o pagamento com cartão quando não consegue observar a resposta do provedor.

Se o checkout é uma aplicação de página única (SPA), instale o snippet uma vez no HTML base e avise o SDK sobre as trocas de rota com Proteside.pageChanged().

Instalar no site inteiroCopiar link da seção

É possível colar o snippet no layout global do site. Saiba o que muda:

• O SDK roda igual em todas as páginas em que estiver. Não há configuração por página que chegue ao navegador.
• Todas as páginas aparecem em Páginas e Domínios e entram no inventário de Scripts, o que aumenta o volume de scripts para revisar.
• Cada pageview faz as requisições extras do SDK (configuração, eventos e uma leitura dos headers da própria página). Veja Desempenho e compatibilidade.
• Enquanto a loja não tiver páginas de pagamento cadastradas, todas as pageviews com o SDK contam como pageviews de páginas de pagamento no uso do plano. As páginas de pagamento são cadastradas pela API, não pelo dashboard.

Para o PCI DSS 4.0, requisitos 6.4.3 e 11.6.1, o que importa são as páginas de pagamento. Prefira instalar só nelas.

Canais stable e latestCopiar link da seção

O canal de release define qual build do shield.js o snippet carrega. Ele é escolhido em Configurações → Proteção do pagamento → Canal de release do SDK.

Não existem URLs com número de versão: não é possível fixar uma versão específica do SDK.

O shield.js se atualiza sozinho pela CDN. O bootstrapper, por ser inline, só muda quando você recola o snippet.

Trocar a chave do SDKCopiar link da seção

Se precisar de uma chave nova, use Trocar chave em Páginas e Domínios e digite TROCAR para confirmar. Só proprietários e administradores conseguem concluir a troca. A chave antiga continua funcionando por 24 horas. Nesse prazo, cole o snippet atualizado em todas as páginas: depois dele, a chave antiga deixa de ser aceita e os eventos dessas páginas se perdem sem aviso.

Próximos passosCopiar link da seção

• Instalação por plataforma
• Verificar a instalação
• Configuração