# Instalación por plataforma

> Dónde pegar el snippet en HTML, Next.js, Nuxt y WordPress, y cómo usar los plugins oficiales para WooCommerce, Magento, OpenCart, PrestaShop y Medusa.

URL: https://docs.proteside.com/es/docs/integration/platforms

El dashboard genera el snippet listo para cuatro plataformas: **HTML**, **Next.js**, **Nuxt** y **WordPress**. En todas,
la regla es la misma: el bootstrapper inline debe ser el primer script del `<head>` y el `shield.js` va justo después.

En los ejemplos de abajo, el contenido del bootstrapper está abreviado. Copia siempre el código completo en
**Ajustes → Páginas y Dominios**, que ya incluye tu clave, tu canal y tus reglas.

## Plataformas con snippet en el dashboard
  **HTML**

Pega el bloque una vez, como primer elemento del `<head>`, en todas las páginas con checkout. Usa esta pestaña también
para sitios estáticos, aplicaciones React o Vue sin framework de servidor (en el `index.html`) y para cualquier
plataforma que permita editar el HTML del checkout.

```html title="checkout.html"
<!doctype html>
<html lang="es">
  <head>
    <!-- Proteside Start -->
    <!-- Place first in <head>, before GTM, Stripe.js, analytics, or any other scripts. -->
    <script>/* bootstrapper: contenido completo copiado del dashboard */</script>
    <script async src="https://cdn.proteside.com/v1/shield.js"
            data-key="pk_live_TU_CLAVE"
            data-api="https://app.proteside.com/api/sdk"></script>
    <!-- Proteside End -->

    <meta charset="utf-8" />
    <title>Checkout · Mi Tienda</title>
    <!-- GTM, analytics y los demás scripts van después -->
  </head>
  <body>
    <!-- ... -->
  </body>
</html>
```

  **Next.js**

Para el App Router, agrega las dos etiquetas `<Script strategy="beforeInteractive">` dentro del `<head>` del layout
    raíz (`app/layout.tsx`). No uses `<script>` simple: Next.js reordena las etiquetas, y el SDK se iniciaría antes del
    bootstrapper.

    Este es el bloque que genera el dashboard:

    ```tsx title="Snippet Next.js generado por el dashboard"
    
    
    
    
    import Script from 'next/script'

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

    El bloque mezcla un `import` con JSX. Lleva el `import` al principio del archivo y pega las etiquetas `<Script>` dentro
    del `<head>`:

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

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

    Si la tienda tiene reglas inline, van al principio del contenido de `<Script id="proteside-bootstrapper">`, sin
    etiqueta extra. Los snippets antiguos traían una tercera etiqueta antes, `<Script id="proteside-inline">`: mantén el
    orden en que aparece o vuelve a pegar el snippet.

    > **Revisa el orden después de publicar**
>
> Next.js inyecta scripts propios en el `<head>`, y el orden final depende de la versión del framework. Después de
> publicar, abre el checkout y ejecuta `Proteside.getStatus().installationOrderValid` en la consola. Si el resultado es
> `false`, el bootstrapper no quedó en primer lugar y la cobertura es parcial. Consulta
> [Solución de problemas](https://docs.proteside.com/es/docs/integration/troubleshooting#ordem-de-instalacao).

    Las navegaciones entre rutas en el cliente no recargan la página. Llama a
    [`Proteside.pageChanged()`](https://docs.proteside.com/es/docs/integration/javascript-api#pagechangedpath) cuando cambie la ruta dentro del checkout.

  **Nuxt**

Coloca las dos entradas al principio de `app.head.script`, en `nuxt.config.ts`, en este orden (el bootstrapper
    primero). Después genera el build y publica el sitio.

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

    Así queda en el archivo:

    ```ts title="nuxt.config.ts"
    export default defineNuxtConfig({
      app: {
        head: {
          script: [
            // Proteside Start — nuxt.config.ts → app.head.script (keep this order)
            {
              children: `/* bootstrapper: contenido completo copiado del dashboard */`,
              tagPosition: 'head',
            },
            {
              src: 'https://cdn.proteside.com/v1/shield.js',
              async: true,
              'data-key': 'pk_live_TU_CLAVE',
              'data-api': 'https://app.proteside.com/api/sdk',
            },
            // Proteside End
            // tus otros scripts van después
          ],
        },
      },
    })
    ```

    > **Nota**
>
> Después de publicar, mira el código fuente de la página de checkout y confirma que la primera etiqueta `<script>`
> del `<head>` contiene el código del bootstrapper. Si tu versión de Nuxt genera la etiqueta vacía, cambia `children`
> por `innerHTML`.

  **WordPress**

En tiendas WooCommerce, prefiere el [plugin oficial](#woocommerce). Para instalar con código, agrégalo en el
`functions.php` de un **tema hijo** o en un plugin de snippets (como Code Snippets), para que las actualizaciones del
tema no borren el código.

```php title="functions.php"
<?php
// Proteside Start — functions.php (bootstrapper first, SDK second)
add_action('wp_head', function() {
  echo '<script>/* bootstrapper: contenido completo copiado del dashboard */</script>';
}, 1);
add_action('wp_head', function() {
  echo '<script async src="https://cdn.proteside.com/v1/shield.js" data-key="pk_live_TU_CLAVE" data-api="https://app.proteside.com/api/sdk"></script>';
}, 2);
// Proteside End
```

Las prioridades 1 y 2 colocan Proteside al principio de `wp_head`. Si la tienda tiene reglas inline, van al
principio del `echo` del bootstrapper. Los snippets antiguos traían una tercera acción, con prioridad 0, para esas reglas.

Después de publicar:

* limpia la caché de los plugins de caché y optimización;
* excluye el snippet de las opciones de combinar, minificar, diferir (`defer`) o retrasar JavaScript;
* revisa que el tema no imprima `<script>` en el `header.php` antes de llamar a `wp_head()` y que ningún plugin use
  prioridad 0 o 1 en `wp_head`. En esos casos, el bootstrapper no queda en primer lugar.

## Plataformas con plugin oficial
En estas plataformas, un plugin de Proteside instala el snippet por ti: pegas la clave del SDK en el admin de la
tienda, eliges las páginas y el plugin verifica tu suscripción por sí solo. Cada plugin tiene un repositorio público
con el código fuente, las notas de cada versión y el paquete para descargar.

| Plataforma               | Dónde obtenerlo                                                                                        | Repositorio                                                                     |
| ------------------------ | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| WooCommerce              | [WordPress.org](https://wordpress.org/plugins/proteside-for-woocommerce/)                              | [proteside-woocommerce](https://github.com/proteside-app/proteside-woocommerce) |
| Magento / Adobe Commerce | [Descarga de la última versión](https://github.com/proteside-app/proteside-magento/releases/latest)    | [proteside-magento](https://github.com/proteside-app/proteside-magento)         |
| OpenCart                 | [Descarga de la última versión](https://github.com/proteside-app/proteside-opencart/releases/latest)   | [proteside-opencart](https://github.com/proteside-app/proteside-opencart)       |
| PrestaShop               | [Descarga de la última versión](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)           |

Los menús de abajo siguen el admin de cada plataforma en inglés. Después de instalar cualquiera de ellos, abre el
checkout y ejecuta `Proteside.getStatus()` en la consola del navegador para verificar.

### WooCommerce
Requisitos: WordPress 6.7 o más reciente, PHP 7.4 o más reciente y WooCommerce activo.

  **Instala el plugin.** En WordPress, abre **Plugins → Add New Plugin**, busca **Proteside for WooCommerce**, haz clic
en **Install Now** y después en **Activate**.

  **Pega la clave.** Abre **WooCommerce → Proteside**, pega la clave del SDK (**Ajustes → Páginas y Dominios** en el
dashboard de Proteside) y haz clic en **Save changes**. El plugin muestra el estado de la conexión al instante.

  **Revisa las páginas.** Por defecto, la protección carga en el checkout, en la página de pago del pedido y en la
confirmación del pedido. Ajústalas si hace falta y guarda.

Si un tema o plugin imprime scripts antes de `wp_head`, activa **Strict first position (output buffering)** en
**Advanced**. No uses al mismo tiempo el plugin y el código de la pestaña **WordPress**.

### Magento
Requisitos: Magento Open Source o Adobe Commerce 2.4.4 a 2.4.9, con el cron de Magento en ejecución.

  **Descarga el paquete** `proteside-module-checkout-<versión>.zip` de la
[última versión](https://github.com/proteside-app/proteside-magento/releases/latest).

  **Instala el módulo** desde la raíz de Magento:

```bash
mkdir -p app/code/Proteside/Checkout
# reemplaza 1.0.2 por la versión que descargaste
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
```

  **Actívalo y pega la clave.** Abre **Stores → Configuration → Security → Proteside**, cambia **Enabled** a **Yes**,
pega la clave del SDK y guarda. Al guardar, el módulo verifica el estado y limpia la caché de páginas.

Por defecto, la protección carga en el checkout y en la confirmación del pedido. El módulo ya agrega los dominios de
Proteside a la Content Security Policy de Magento.

### OpenCart
Requisitos: OpenCart 3.0.2 a 3.0.5.1, o 4.0.2 o más reciente (incluido 4.1). La versión publicada trae un paquete
para cada versión: `proteside-opencart-3.ocmod.zip` para OpenCart 3 y `proteside.ocmod.zip` para OpenCart 4.

  **Sube el paquete** de la [última versión](https://github.com/proteside-app/proteside-opencart/releases/latest) en
**Extensions → Installer → Upload**. En OpenCart 4, mantén el nombre `proteside.ocmod.zip` y haz clic en **Install**
en la lista de instalados.

  **Instala el módulo.** En **Extensions → Extensions**, elige **Modules**, busca **Proteside checkout protection**,
haz clic en **Install** (+) y después en **Edit** (lápiz).

  **Pega la clave** del SDK y haz clic en **Save**. La página se recarga con el estado que devuelve Proteside.

No hace falta agregar el módulo a un layout en **Design → Layouts**, y el evento `proteside` en **Extensions →
Events** tiene que quedar activado: es el que inserta la protección.

### PrestaShop
Requisitos: PrestaShop 1.7.6 o más reciente, incluidos 8 y 9.

  **Descarga el paquete** `proteside-<versión>.zip` de la
[última versión](https://github.com/proteside-app/proteside-prestashop/releases/latest).

  **Sube el módulo** en **Modules → Module Manager → Upload a module**.

  **Pega la clave.** Haz clic en **Configure** en la tarjeta **Proteside checkout protection**, pega la clave del SDK y
haz clic en **Save changes**.

Deja activada la opción **Strict first position**, que coloca la protección como primer elemento del `<head>`.

### Medusa
Para tiendas [Medusa](https://medusajs.com) existe el plugin oficial
[`@proteside/medusa`](https://www.npmjs.com/package/@proteside/medusa). El código fuente, el historial de versiones y
el paquete para descargar están en el repositorio público
[github.com/proteside-app/proteside-medusa](https://github.com/proteside-app/proteside-medusa).

Medusa es headless: la tienda es una app separada del servidor. Por eso el plugin tiene dos partes. En el servidor
Medusa, agrega la pantalla **Configuraciones → Proteside** al admin, donde pegas tu clave y eliges las páginas, y
verifica tu suscripción por sí solo. En la tienda, agregas un componente que imprime Proteside en el `<head>`.

Requisitos: Medusa 2.22 o más reciente, Node.js 22 y acceso al `<head>` del layout raíz de la tienda.

  **Instala el plugin en el servidor Medusa.**

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

  **Registra el plugin** en `medusa-config.ts`:

```ts title="medusa-config.ts"
module.exports = defineConfig({
  // ...
  plugins: [
    {
      resolve: '@proteside/medusa',
      options: {
        // opcional: URL de la tienda, usada cuando el campo del admin está vacío
        storefrontUrl: 'https://mitienda.com',
      },
    },
  ],
})
```

  **Ejecuta la migración** y reinicia Medusa:

```bash
npx medusa db:migrate
```

  **Actívalo en el admin.** Abre **Configuraciones → Proteside**, pega la clave del SDK (**Ajustes → Páginas y
Dominios** en el dashboard de Proteside) y guarda. El estado pasa a **Activo** cuando la suscripción está activa. Por
defecto, la protección carga en el checkout y en la confirmación del pedido.

  **Agrega el componente a la tienda.** En el starter de Next.js de Medusa, copia el archivo
`storefront/nextjs/proteside.tsx` del paquete a la tienda (por ejemplo, `src/lib/proteside.tsx`) y pon
`<ProtesideScript />` como primer elemento del `<head>` del layout raíz:

```tsx title="src/app/layout.tsx"
import { ProtesideScript } from '@lib/proteside'

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

El componente usa las variables `MEDUSA_BACKEND_URL` y `NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY` que el starter ya tiene y
sigue los cambios de ruta por sí solo, sin necesidad de llamar a `Proteside.pageChanged()`. Usa una etiqueta
`<script>` normal a propósito: el plugin genera un único script, a diferencia del snippet de dos etiquetas de la
pestaña **Next.js**. En otras tiendas, obtén el script en el servidor con `GET /store/proteside/snippet` (con la clave
publicable de Medusa en el header `x-publishable-api-key`) e imprime el campo `html` como primer elemento del
`<head>`. Las instrucciones completas están en el README del
[repositorio](https://github.com/proteside-app/proteside-medusa).

> **Aviso de orden de instalación en tiendas Next.js**
>
> Next.js siempre coloca sus propios scripts antes de cualquier script inline del `<head>`. Por eso, en una tienda
> Next.js, `Proteside.getStatus().installationOrderValid` queda en `false` y el dashboard muestra la alerta de orden
> de instalación aunque el plugin esté bien instalado. Para dejar de recibir esa alerta, ábrela en **Alertas** y elige
> **No avisar más en esta tienda**.

Para verificar, abre el checkout de la tienda y ejecuta `Proteside.getStatus()` en la consola del navegador:
`initialized` debe ser `true`. Consulta también [Verificar la instalación](https://docs.proteside.com/es/docs/integration/verify).

## Otras plataformas
Para las plataformas de abajo, la instalación es el snippet de la pestaña **HTML**, pegado en el `<head>` de las
páginas de checkout. Lo que cambia de una plataforma a otra es **si** te
deja editar ese `<head>` y **dónde**.

Antes de instalar, confirma tres puntos con tu plataforma:

1. **En qué dominio se ejecuta el checkout.** Muchas plataformas alojan el checkout en un dominio o subdominio propio.
   El snippet debe estar en las páginas de ese dominio.
2. **Si es posible insertar código en el `<head>` del checkout**, no solo en el resto de la tienda.
3. **Si el código entra como primer elemento del `<head>`**, inline y sin diferirse. Si la plataforma solo permite
   agregar scripts después de los suyos, el SDK funciona con cobertura parcial y genera el aviso de orden de
   instalación.

| Plataforma                 | Orientación                                                                                                                                                                                                                                                                                  |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Shopify                    | El checkout lo controla la propia plataforma. Consulta con el soporte de Shopify si tu plan permite insertar código en el `<head>` de las páginas de checkout. Los pixels y scripts que se ejecutan en un entorno aislado (sandbox) no ven la página de checkout y no sirven para Proteside. |
| VTEX                       | Usa la función de personalización del checkout de la plataforma, si permite código en el `<head>` de las páginas de checkout. Confirma con el soporte de VTEX en qué posición se inserta el código.                                                                                          |
| Nuvemshop                  | Usa la función de scripts personalizados del checkout, si tu plan la ofrece. Confirma con el soporte de Nuvemshop si el código entra en el `<head>` del checkout.                                                                                                                            |
| Yampi                      | Usa la función de scripts personalizados del checkout, si está disponible. Confirma con el soporte de Yampi si el código entra en el `<head>` del checkout.                                                                                                                                  |
| WooCommerce                | Usa el [plugin oficial](#woocommerce).                                                                                                                                                                                                                                                       |
| Tray                       | Usa la función de scripts personalizados del checkout, si está disponible. Confirma con el soporte de Tray si el código entra en el `<head>` del checkout.                                                                                                                                   |
| Wix                        | Usa la función de código personalizado del sitio, si se puede aplicar a las páginas de checkout. Confirma con el soporte de Wix si el checkout acepta código en el `<head>`.                                                                                                                 |
| Medusa                     | Usa el [plugin oficial](#medusa).                                                                                                                                                                                                                                                            |
| Checkout propio o headless | Usa la pestaña **HTML** (o **Next.js** / **Nuxt**) en la plantilla de las páginas de pago.                                                                                                                                                                                                   |

Si la plataforma no permite código en el `<head>` del checkout, Proteside no puede proteger esa página. En ese caso,
instala el snippet en las páginas que controlas y confirma con la plataforma cómo cumple los requisitos 6.4.3 y 11.6.1
de PCI DSS 4.0 en sus páginas.

## Google Tag Manager
No instales Proteside a través de Google Tag Manager. GTM carga las etiquetas de forma asíncrona, después del propio
contenedor, por lo que:

* el bootstrapper deja de ser el primer script y deja de ser síncrono, que es justamente lo que exige la arquitectura;
* la protección queda con cobertura parcial;
* el bloqueo de contenedores y etiquetas no autorizados deja de funcionar, porque quien cargaría Proteside sería el
  propio GTM.

Si usas GTM, pega el snippet de Proteside **antes** del snippet de GTM en el `<head>`. Así, las etiquetas que GTM
inserta por JavaScript pasan por el bootstrapper y pueden bloquearse con tus reglas y con la lista de
**Contenedores GTM permitidos**.

## Próximos pasos
* [Verificar la instalación](https://docs.proteside.com/es/docs/integration/verify)
* [Configuración](https://docs.proteside.com/es/docs/integration/configuration)
* [Content Security Policy y headers](https://docs.proteside.com/es/docs/integration/csp)
