Proteside Docs

Instalação por plataforma

Onde colar o snippet em HTML, Next.js, Nuxt e WordPress, e como usar os plugins oficiais para WooCommerce, Magento, OpenCart, PrestaShop e Medusa.

O dashboard gera o snippet pronto para quatro plataformas: HTML, Next.js, Nuxt e WordPress. Em todas, a regra é a mesma: o bootstrapper inline precisa ser o primeiro script do <head> e o shield.js vem logo depois.

Nos exemplos abaixo, o conteúdo do bootstrapper foi abreviado. Copie sempre o código completo em Configurações → Páginas e Domínios, que já vem com a sua chave, o seu canal e as suas regras.

Plataformas com snippet no dashboard

Cole o bloco uma vez, como primeiro item do <head>, em todas as páginas com checkout. Use esta aba também para sites estáticos, aplicações React ou Vue sem framework de servidor (no index.html) e para qualquer plataforma que permita editar o HTML do checkout.

checkout.html
<!doctype html>
<html lang="pt-BR">
  <head>
    <!-- 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_SUA_CHAVE"
            data-api="https://app.proteside.com/api/sdk"></script>
    <!-- Proteside End -->

    <meta charset="utf-8" />
    <title>Checkout · Minha Loja</title>
    <!-- GTM, analytics e demais scripts vêm depois -->
  </head>
  <body>
    <!-- ... -->
  </body>
</html>

Plataformas com plugin oficial

Nestas plataformas, um plugin da Proteside instala o snippet por você: você cola a chave do SDK no admin da loja, escolhe as páginas, e o plugin confere a sua assinatura sozinho. Cada plugin tem um repositório público com o código-fonte, as notas de cada versão e o pacote para download.

Os menus citados abaixo seguem o admin de cada plataforma em inglês. Depois de instalar qualquer um deles, abra o checkout e rode Proteside.getStatus() no console do navegador para conferir.

WooCommerce

Requisitos: WordPress 6.7 ou mais novo, PHP 7.4 ou mais novo e WooCommerce ativo.

Instale o plugin. No WordPress, abra Plugins → Add New Plugin, procure por Proteside for WooCommerce, clique em Install Now e depois em Activate.

Cole a chave. Abra WooCommerce → Proteside, cole a chave do SDK (Configurações → Páginas e Domínios no dashboard do Proteside) e clique em Save changes. O plugin mostra o status da conexão na hora.

Confira as páginas. Por padrão, a proteção carrega no checkout, na página de pagamento do pedido e na confirmação do pedido. Ajuste se precisar e salve.

Se um tema ou plugin imprimir scripts antes do wp_head, ligue Strict first position (output buffering) em Advanced. Não use ao mesmo tempo o plugin e o código da aba WordPress.

Magento

Requisitos: Magento Open Source ou Adobe Commerce 2.4.4 a 2.4.9 e o cron do Magento rodando.

Baixe o pacote proteside-module-checkout-<versão>.zip da versão mais recente.

Instale o módulo na raiz do Magento:

mkdir -p app/code/Proteside/Checkout
# troque 1.0.2 pela versão que você baixou
unzip proteside-module-checkout-1.0.2.zip -d app/code/Proteside/Checkout
bin/magento module:enable Proteside_Checkout
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Ative e cole a chave. Abra Stores → Configuration → Security → Proteside, mude Enabled para Yes, cole a chave do SDK e salve. Ao salvar, o módulo verifica o status e limpa o cache de página.

Por padrão, a proteção carrega no checkout e na confirmação do pedido. O módulo já registra os domínios do Proteside na Content Security Policy do Magento.

OpenCart

Requisitos: OpenCart 3.0.2 a 3.0.5.1, ou 4.0.2 ou mais novo (inclusive 4.1). A release tem um pacote para cada versão: proteside-opencart-3.ocmod.zip para o OpenCart 3 e proteside.ocmod.zip para o OpenCart 4.

Envie o pacote da versão mais recente em Extensions → Installer → Upload. No OpenCart 4, mantenha o nome proteside.ocmod.zip e clique em Install na lista de instalados.

Instale o módulo. Em Extensions → Extensions, escolha Modules, encontre Proteside checkout protection, clique em Install (+) e depois em Edit (lápis).

Cole a chave do SDK e clique em Save. A página recarrega com o status retornado pelo Proteside.

Não é preciso adicionar o módulo a um layout em Design → Layouts, e o evento proteside em Extensions → Events precisa ficar ligado: é ele que insere a proteção.

PrestaShop

Requisitos: PrestaShop 1.7.6 ou mais novo, inclusive 8 e 9.

Baixe o pacote proteside-<versão>.zip da versão mais recente.

Envie o módulo em Modules → Module Manager → Upload a module.

Cole a chave. Clique em Configure no card Proteside checkout protection, cole a chave do SDK e clique em Save changes.

Deixe ligada a opção Strict first position, que coloca a proteção como primeiro item do <head>.

Medusa

Para lojas Medusa existe o plugin oficial @proteside/medusa. O código-fonte, o histórico de versões e o pacote para download estão no repositório público github.com/proteside-app/proteside-medusa.

O Medusa é headless: a vitrine é um app separado do servidor. Por isso o plugin tem duas partes. No servidor Medusa, ele adiciona a tela Configurações → Proteside no admin, onde você cola a chave e escolhe as páginas, e verifica a sua assinatura sozinho. Na vitrine, você adiciona um componente que imprime o Proteside no <head>.

Requisitos: Medusa 2.22 ou mais novo, Node.js 22 e acesso ao <head> do layout raiz da vitrine.

Instale o plugin no servidor Medusa.

npm install @proteside/medusa

Registre o plugin em medusa-config.ts:

medusa-config.ts
module.exports = defineConfig({
  // ...
  plugins: [
    {
      resolve: '@proteside/medusa',
      options: {
        // opcional: URL da vitrine, usada quando o campo do admin está vazio
        storefrontUrl: 'https://minhaloja.com.br',
      },
    },
  ],
})

Rode a migração e reinicie o Medusa:

npx medusa db:migrate

Ative no admin. Abra Configurações → Proteside, cole a chave do SDK (Configurações → Páginas e Domínios no dashboard do Proteside) e salve. O status fica Ativo quando a assinatura está ativa. Por padrão, a proteção carrega no checkout e na confirmação do pedido.

Adicione o componente na vitrine. No starter Next.js do Medusa, copie o arquivo storefront/nextjs/proteside.tsx do pacote para a vitrine (por exemplo, src/lib/proteside.tsx) e coloque <ProtesideScript /> como primeiro item do <head> do layout raiz:

src/app/layout.tsx
import { ProtesideScript } from '@lib/proteside'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="pt-BR">
      <head>
        <ProtesideScript />
      </head>
      <body>{children}</body>
    </html>
  )
}

O componente usa as variáveis MEDUSA_BACKEND_URL e NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY que o starter já tem e acompanha a navegação entre rotas sozinho, sem precisar chamar Proteside.pageChanged(). Ele usa uma tag <script> comum de propósito: o plugin gera um único script, diferente do snippet de duas tags da aba Next.js. Em outras vitrines, busque o script no servidor com GET /store/proteside/snippet (com a chave publicável do Medusa no header x-publishable-api-key) e imprima o campo html como primeiro item do <head>. As instruções completas estão no README do repositório.

Aviso de ordem de instalação em vitrines Next.js

O Next.js sempre coloca os próprios scripts antes de qualquer script inline do <head>. Por isso, numa vitrine Next.js, Proteside.getStatus().installationOrderValid fica false e o dashboard mostra o alerta de ordem de instalação mesmo com o plugin instalado corretamente. Para não receber esse alerta, abra-o em Alertas e escolha Não avisar mais nesta loja.

Para conferir, abra o checkout da vitrine e rode Proteside.getStatus() no console do navegador: initialized deve ser true. Veja também Verificar a instalação.

Outras plataformas

Para as plataformas abaixo, a instalação é o snippet da aba HTML, colado no <head> das páginas de checkout. O que muda de uma plataforma para outra é se e onde ela deixa você editar esse <head>.

Antes de instalar, confirme três pontos com a sua plataforma:

  1. Em qual domínio o checkout roda. Muitas plataformas hospedam o checkout em um domínio ou subdomínio próprio. O snippet precisa estar nas páginas desse domínio.
  2. Se é possível inserir código no <head> do checkout, não só no restante da loja.
  3. Se o código entra como primeiro item do <head>, inline e sem ser adiado. Se a plataforma só permite adicionar scripts depois dos dela, o SDK funciona com cobertura parcial e gera o aviso de ordem de instalação.
PlataformaOrientação
ShopifyO checkout é controlado pela própria plataforma. Verifique com o suporte do Shopify se o seu plano permite inserir código no <head> das páginas de checkout. Pixels e scripts que rodam em ambiente isolado (sandbox) não enxergam a página de checkout e não servem para o Proteside.
VTEXUse o recurso de personalização do checkout da plataforma, se ele permitir código no <head> das páginas de checkout. Confirme com o suporte da VTEX em que posição o código é inserido.
NuvemshopUse o recurso de scripts personalizados do checkout, se o seu plano oferecer. Confirme com o suporte da Nuvemshop se o código entra no <head> do checkout.
YampiUse o recurso de scripts personalizados do checkout, se disponível. Confirme com o suporte da Yampi se o código entra no <head> do checkout.
WooCommerceUse o plugin oficial.
TrayUse o recurso de scripts personalizados do checkout, se disponível. Confirme com o suporte da Tray se o código entra no <head> do checkout.
WixUse o recurso de código personalizado do site, se ele puder ser aplicado às páginas de checkout. Confirme com o suporte do Wix se o checkout aceita código no <head>.
MedusaUse o plugin oficial.
Checkout próprio ou headlessUse a aba HTML (ou Next.js / Nuxt) no template das páginas de pagamento.

Se a plataforma não permite código no <head> do checkout, o Proteside não consegue proteger aquela página. Nesse caso, instale o snippet nas páginas que você controla e confirme com a plataforma como ela atende os requisitos 6.4.3 e 11.6.1 do PCI DSS 4.0 nas páginas dela.

Google Tag Manager

Não instale o Proteside por meio do Google Tag Manager. O GTM carrega as tags de forma assíncrona, depois do próprio container, então:

  • o bootstrapper deixa de ser o primeiro script e deixa de ser síncrono, que é justamente o que a arquitetura exige;
  • a proteção fica com cobertura parcial;
  • o bloqueio de containers e tags não autorizados deixa de funcionar, porque quem carrega o Proteside seria o próprio GTM.

Se você usa GTM, cole o snippet do Proteside antes do snippet do GTM no <head>. Assim, as tags que o GTM insere por JavaScript passam pelo bootstrapper e podem ser bloqueadas pelas suas regras e pela lista de Containers GTM permitidos.

Próximos passos

Nesta página