Instalación del snippet
Copia el snippet del dashboard y pégalo como primer script del head de las páginas de pago.
La instalación es un bloque de código que copias del dashboard y pegas en el <head> de las páginas de checkout. No hay
paquete npm ni app para tiendas: el mismo snippet funciona en cualquier sitio en el que controles el HTML del checkout.
Dónde obtener el snippet
El snippet está en Ajustes → Páginas y Dominios, en la tarjeta Instalación del SDK:
- Clave del SDK: la clave de la tienda, que empieza con
pk_live_. Es una clave pública: va en el HTML de la tienda y solo identifica la tienda ante el SDK. - Snippet: el bloque listo, ya con tu clave, el canal de release y las reglas de bloqueo activas. Hay una pestaña para cada plataforma: HTML, Next.js, Nuxt y WordPress.

El asistente de creación de la tienda también muestra el snippet, en el paso de instalación. Ese snippet siempre sale
en el canal stable y sin tus reglas. Si ya configuraste reglas o contenedores de Google Tag Manager, copia el snippet
de Páginas y Dominios.
Instalar
Abre Páginas y Dominios
En el dashboard, ve a Ajustes → Páginas y Dominios.
Copia el snippet de tu plataforma
Elige la pestaña HTML, Next.js, Nuxt o WordPress y haz clic en Copiar. Para otras plataformas, usa la pestaña HTML y sigue Instalación por plataforma.
Pégalo como primer elemento del head
Pega el bloque completo justo después de la apertura del <head>, antes de Google Tag Manager, Stripe.js,
analytics y cualquier otro script, en todas las páginas de checkout y de pago.
Publica y abre el checkout
Publica el cambio y abre la página de checkout en el navegador. Después, sigue Verificar la instalación.
Qué contiene el snippet
Este es el formato del snippet HTML que genera el dashboard. El contenido del bootstrapper está abreviado aquí: tiene unos 4,3 KB de JavaScript minificado y cambia entre versiones. Copia siempre el bloque completo del dashboard.
<!-- 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 -->| Parte | Función |
|---|---|
<script> inline | El bootstrapper. Se ejecuta al instante, sin red, y empieza a observar la página. |
<script async src=".../shield.js"> | El SDK. Se carga desde la CDN sin bloquear la página. |
data-key | La clave del SDK de la tienda. Obligatoria. |
data-api | La dirección de la API de Proteside. El dashboard siempre la completa con el valor predeterminado. |
Los comentarios dentro del snippet quedan en inglés en cualquier idioma del dashboard. Es el comportamiento normal.
Snippet con reglas inline
Si la tienda tiene reglas de bloqueo activas por dominio o por URL, o una lista de contenedores de Google Tag Manager
permitidos, el dashboard escribe esa configuración al principio del propio <script> del bootstrapper:
<!-- Proteside Start -->
<!-- Place first in <head>, before GTM, Stripe.js, analytics, or any other scripts. -->
<script>/* bootstrapper con las reglas inline: 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 -->Ese fragmento permite que el bootstrapper bloquee scripts desde el primer byte de la página, sin esperar la configuración remota.
Las reglas inline quedan congeladas en el HTML
La configuración inline guarda las reglas del momento en que copiaste el snippet. Cuando el SDK inicia, pasa a valer la configuración remota, pero hasta entonces la página usa la versión pegada. Una regla eliminada en el dashboard sigue bloqueando en ese intervalo, y una regla nueva solo bloquea desde el primer byte después de que vuelvas a pegar el snippet. Vuelve a pegar el snippet siempre que cambies reglas de bloqueo o contenedores de Google Tag Manager.
No modifiques el snippet
- No separes el bootstrapper del
shield.jsni inviertas el orden. - No reemplaces el bootstrapper inline por un
<script src>externo. Debe ejecutarse de forma síncrona. - No agregues
async,defernitype="module". Contype="module", el SDK no se inicializa. - Excluye el snippet de los plugins de optimización que combinan, difieren o cargan JavaScript de forma asíncrona.
Por qué el primer script del head
El snippet debe ser el primer script del <head> para una cobertura completa.
Si hay cualquier script antes del snippet, el SDK marca la instalación como fuera de orden: envía el evento
INSTALLATION_ORDER_WARNING, que se convierte en una alerta en el dashboard, y
Proteside.getStatus().installationOrderValid queda en false. La protección continúa, pero con cobertura parcial.
Para corregirlo, mueve el snippet al inicio del <head> y vuelve a publicar. Consulta
Solución de problemas.
Para bloquear un script escrito en el HTML de la página, quita la etiqueta del HTML o del tema. Los scripts insertados después, incluidas las etiquetas que dispara Google Tag Manager, se bloquean según tus reglas antes de ejecutarse.
Los snippets antiguos traían la configuración inline en una etiqueta <script> separada, antes del bootstrapper. Si
usas un snippet antiguo, copia el snippet actual en Páginas y Dominios y reemplaza el bloque completo.
En qué páginas instalarlo
Instala el snippet en las páginas en las que el cliente ingresa o recibe datos de pago:
- el checkout, incluidos los pasos de envío y pago, cuando son páginas separadas;
- las páginas que muestran el código QR o el código Pix copia y pega, el boleto o la dirección cripto;
- la página de confirmación del pedido, si aceptas tarjeta. El SDK usa esa página para confirmar el pago con tarjeta.
Si el checkout es una aplicación de página única (SPA), instala el snippet una vez en el HTML base y avisa al SDK de los
cambios de ruta con Proteside.pageChanged().
Instalar en todo el sitio
Puedes pegar el snippet en el layout global del sitio. Ten en cuenta lo que cambia:
- El SDK funciona igual en todas las páginas en las que esté. No hay configuración por página que llegue al navegador.
- Todas las páginas aparecen en Páginas y Dominios y entran en el inventario de Scripts, lo que aumenta el volumen de scripts por revisar.
- Cada pageview hace las solicitudes extra del SDK (configuración, eventos y una lectura de los headers de la propia página). Consulta Rendimiento y compatibilidad.
- Mientras la tienda no tenga páginas de pago registradas, todos los pageviews con el SDK cuentan como pageviews de páginas de pago en el uso del plan. Las páginas de pago se registran mediante la API, no desde el dashboard.
Para PCI DSS 4.0, requisitos 6.4.3 y 11.6.1, lo que importa son las páginas de pago. Es preferible instalarlo solo en ellas.
Canales stable y latest
El canal de release define qué build del shield.js carga el snippet. Se elige en
Ajustes → Protección del pago → Cómo debe reaccionar el SDK → Opciones para el equipo técnico → Canal de release
del SDK.
| Canal | URL del shield.js | Cuándo se actualiza |
|---|---|---|
stable (predeterminado) | https://cdn.proteside.com/v1/shield.js | con cada versión validada |
latest | https://cdn.proteside.com/v1/latest/shield.js | con cada publicación |
Cambiar el canal exige volver a pegar el snippet
La pantalla de Protección del pago dice que no hace falta reinstalar al cambiar el canal. Pero la URL del shield.js
está escrita en el snippet: lo que ya está pegado sigue cargando el canal anterior. Después de cambiar el canal,
vuelve a copiar el snippet en Páginas y Dominios y publícalo. Cuando la tienda usa latest, el snippet muestra la
insignia canal latest.
El shield.js se actualiza solo a través de la CDN. El bootstrapper, por ser inline, solo cambia cuando vuelves a
pegar el snippet.
Cambiar la clave del SDK
Si necesitas una clave nueva, usa Rotar en Páginas y Dominios y escribe ROTAR para confirmar. Solo los
propietarios y administradores pueden completar el cambio. La clave anterior sigue funcionando durante 24 horas.
En ese plazo, pega el snippet actualizado en todas las páginas: después, la clave anterior deja de aceptarse y los
eventos de esas páginas se pierden sin aviso.