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.
<!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.
| Plataforma | Dónde obtenerlo | Repositorio |
|---|---|---|
| WooCommerce | WordPress.org | proteside-woocommerce |
| Magento / Adobe Commerce | Descarga de la última versión | proteside-magento |
| OpenCart | Descarga de la última versión | proteside-opencart |
| PrestaShop | Descarga de la última versión | proteside-prestashop |
| Medusa | npm | 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.
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:flushActí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/medusaRegistra el plugin en 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:migrateActí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:
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:
- 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.
- Si es posible insertar código en el
<head>del checkout, no solo en el resto de la tienda. - 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. |
| 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. |
| 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.