# 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.

URL: https://docs.proteside.com/pt-BR/docs/integration/platforms

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
  **HTML**

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.

```html title="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>
```

  **Next.js**

Para o App Router, adicione as duas tags `<Script strategy="beforeInteractive">` dentro do `<head>` do layout raiz
    (`app/layout.tsx`). Não use `<script>` puro: o Next.js reordena as tags, e o SDK iniciaria antes do bootstrapper.

    Este é o bloco que o dashboard gera:

    ```tsx title="Snippet Next.js gerado pelo dashboard"
    
    
    
    
    import Script from 'next/script'

    <Script
      id="proteside-bootstrapper"
      strategy="beforeInteractive"
      dangerouslySetInnerHTML={{ __html: `/* bootstrapper: conteúdo completo copiado do dashboard */` }}
    />
    <Script
      src="https://cdn.proteside.com/v1/shield.js"
      data-key="pk_live_SUA_CHAVE"
      data-api="https://app.proteside.com/api/sdk"
      strategy="beforeInteractive"
    />
    
    ```

    O bloco mistura um `import` com JSX. Leve o `import` para o topo do arquivo e cole as tags `<Script>` dentro do
    `<head>`:

    ```tsx title="app/layout.tsx"
    import Script from 'next/script'

    export default function RootLayout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="pt-BR">
          <head>
            
            <Script
              id="proteside-bootstrapper"
              strategy="beforeInteractive"
              dangerouslySetInnerHTML={{ __html: `/* bootstrapper: conteúdo completo copiado do dashboard */` }}
            />
            <Script
              src="https://cdn.proteside.com/v1/shield.js"
              data-key="pk_live_SUA_CHAVE"
              data-api="https://app.proteside.com/api/sdk"
              strategy="beforeInteractive"
            />
            
          </head>
          <body>{children}</body>
        </html>
      )
    }
    ```

    Se a loja tem regras inline, elas vêm no início do conteúdo do `<Script id="proteside-bootstrapper">`, sem tag extra.
    Snippets antigos traziam uma terceira tag antes dele, `<Script id="proteside-inline">`: mantenha a ordem em que ela
    aparece ou recole o snippet.

    > **Confira a ordem depois de publicar**
>
> O Next.js injeta scripts próprios no `<head>`, e a ordem final depende da versão do framework. Depois de publicar,
> abra o checkout e rode `Proteside.getStatus().installationOrderValid` no console. Se o resultado for `false`, o
> bootstrapper não ficou em primeiro e a cobertura é parcial. Veja
> [Solução de problemas](https://docs.proteside.com/pt-BR/docs/integration/troubleshooting#ordem-de-instalacao).

    Navegações entre rotas no cliente não recarregam a página. Chame
    [`Proteside.pageChanged()`](https://docs.proteside.com/pt-BR/docs/integration/javascript-api#pagechangedpath) quando a rota mudar dentro do checkout.

  **Nuxt**

Coloque as duas entradas no início de `app.head.script`, em `nuxt.config.ts`, nesta ordem (bootstrapper primeiro).
    Depois gere o build e publique o site.

    ```ts title="Snippet Nuxt gerado pelo dashboard"
    // Proteside Start — nuxt.config.ts → app.head.script (keep this order)
    {
      children: `/* bootstrapper: conteúdo completo copiado do dashboard */`,
      tagPosition: 'head',
    },
    {
      src: 'https://cdn.proteside.com/v1/shield.js',
      async: true,
      'data-key': 'pk_live_SUA_CHAVE',
      'data-api': 'https://app.proteside.com/api/sdk',
    }
    // Proteside End
    ```

    Como fica no arquivo:

    ```ts title="nuxt.config.ts"
    export default defineNuxtConfig({
      app: {
        head: {
          script: [
            // Proteside Start — nuxt.config.ts → app.head.script (keep this order)
            {
              children: `/* bootstrapper: conteúdo completo copiado do dashboard */`,
              tagPosition: 'head',
            },
            {
              src: 'https://cdn.proteside.com/v1/shield.js',
              async: true,
              'data-key': 'pk_live_SUA_CHAVE',
              'data-api': 'https://app.proteside.com/api/sdk',
            },
            // Proteside End
            // seus outros scripts vêm depois
          ],
        },
      },
    })
    ```

    > **Nota**
>
> Depois de publicar, veja o código-fonte da página de checkout e confirme que a primeira tag `<script>` do `<head>`
> contém o código do bootstrapper. Se a sua versão do Nuxt gerar a tag vazia, troque `children` por `innerHTML`.

  **WordPress**

Em lojas WooCommerce, prefira o [plugin oficial](#woocommerce). Para instalar pelo código, adicione-o no
`functions.php` de um **tema filho** ou em um plugin de snippets (como o Code Snippets), para que atualizações do
tema não apaguem o código.

```php title="functions.php"
<?php
// Proteside Start — functions.php (bootstrapper first, SDK second)
add_action('wp_head', function() {
  echo '<script>/* bootstrapper: conteúdo completo copiado do dashboard */</script>';
}, 1);
add_action('wp_head', function() {
  echo '<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>';
}, 2);
// Proteside End
```

As prioridades 1 e 2 colocam o Proteside no início do `wp_head`. Se a loja tem regras inline, elas vêm
no início do `echo` do bootstrapper. Snippets antigos traziam uma terceira ação, com prioridade 0, para essas regras.

Depois de publicar:

* limpe o cache dos plugins de cache e otimização;
* exclua o snippet das opções de combinar, minificar, adiar (`defer`) ou atrasar JavaScript;
* confira se o tema não imprime `<script>` no `header.php` antes de chamar `wp_head()` e se nenhum plugin usa
  prioridade 0 ou 1 no `wp_head`. Nesses casos, o bootstrapper não fica em primeiro.

## 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](https://wordpress.org/plugins/proteside-for-woocommerce/)                                | [proteside-woocommerce](https://github.com/proteside-app/proteside-woocommerce) |
| Magento / Adobe Commerce | [Download da versão mais recente](https://github.com/proteside-app/proteside-magento/releases/latest)    | [proteside-magento](https://github.com/proteside-app/proteside-magento)         |
| OpenCart                 | [Download da versão mais recente](https://github.com/proteside-app/proteside-opencart/releases/latest)   | [proteside-opencart](https://github.com/proteside-app/proteside-opencart)       |
| PrestaShop               | [Download da versão mais recente](https://github.com/proteside-app/proteside-prestashop/releases/latest) | [proteside-prestashop](https://github.com/proteside-app/proteside-prestashop)   |
| Medusa                   | [npm](https://www.npmjs.com/package/@proteside/medusa)                                                   | [proteside-medusa](https://github.com/proteside-app/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](https://github.com/proteside-app/proteside-magento/releases/latest).

  **Instale o módulo** na raiz do Magento:

```bash
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](https://github.com/proteside-app/proteside-opencart/releases/latest) 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](https://github.com/proteside-app/proteside-prestashop/releases/latest).

  **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](https://medusajs.com) existe o plugin oficial
[`@proteside/medusa`](https://www.npmjs.com/package/@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](https://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.**

```bash
npm install @proteside/medusa
```

  **Registre o plugin** em `medusa-config.ts`:

```ts title="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:

```bash
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:

```tsx title="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](https://github.com/proteside-app/proteside-medusa).

> **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](https://docs.proteside.com/pt-BR/docs/integration/verify).

## 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.

| 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](#woocommerce).                                                                                                                                                                                                                                                    |
| 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](#medusa).                                                                                                                                                                                                                                                         |
| 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**.

## Próximos passos
* [Verificar a instalação](https://docs.proteside.com/pt-BR/docs/integration/verify)
* [Configuração](https://docs.proteside.com/pt-BR/docs/integration/configuration)
* [Content Security Policy e headers](https://docs.proteside.com/pt-BR/docs/integration/csp)
