Proteside Docs

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.

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

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.

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>

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.

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.

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

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

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 existe el plugin oficial @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.

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.

npm install @proteside/medusa

Registra el plugin en medusa-config.ts:

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:

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:

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.

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.

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.
PlataformaOrientación
ShopifyEl 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.
VTEXUsa 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.
NuvemshopUsa 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.
YampiUsa 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.
WooCommerceUsa el plugin oficial.
TrayUsa 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.
WixUsa 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>.
MedusaUsa el plugin oficial.
Checkout propio o headlessUsa 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

En esta página