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.
<!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.
| Plataforma | Onde obter | Repositório |
|---|---|---|
| WooCommerce | WordPress.org | proteside-woocommerce |
| Magento / Adobe Commerce | Download da versão mais recente | proteside-magento |
| OpenCart | Download da versão mais recente | proteside-opencart |
| PrestaShop | Download da versão mais recente | proteside-prestashop |
| Medusa | npm | proteside-medusa |
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:flushAtive 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/medusaRegistre o plugin em 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:migrateAtive 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:
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:
- 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.
- Se é possível inserir código no
<head>do checkout, não só no restante da loja. - 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.
| Plataforma | Orientação |
|---|---|
| Shopify | O 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. |
| VTEX | Use 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. |
| Nuvemshop | Use 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. |
| Yampi | Use 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. |
| WooCommerce | Use o plugin oficial. |
| Tray | Use 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. |
| Wix | Use 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>. |
| Medusa | Use o plugin oficial. |
| Checkout próprio ou headless | Use 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.