Instalación del snippet

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 snippetCopiar enlace de la sección

El snippet está en Ajustes → Páginas y Dominios, en la tarjeta Instalación del SDK:

• Clave del SDK: la clave de la tienda, con el formato pk_live_ seguido de 32 caracteres hexadecimales. 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.

InstalarCopiar enlace de la sección

Qué contiene el snippetCopiar enlace de la sección

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_3f9c1a7b2e4d6f8a0c1e3b5d7f9a1c3e"
        data-api="https://app.proteside.com/api/sdk"></script>
<!-- Proteside End -->

Los comentarios dentro del snippet quedan en inglés en cualquier idioma del dashboard. Es el comportamiento normal.

Snippet con reglas inlineCopiar enlace de la sección

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>"use strict";window.__PROTE_INLINE__={"rules":[{"type":"block","target":"domain","value":"cdn-suspeito.example"}],"gtm":["GTM-AB12CD3"]};var __ProteBoots=/* resto del bootstrapper, copiado del dashboard */</script>
<script async src="https://cdn.proteside.com/v1/shield.js"
        data-key="pk_live_3f9c1a7b2e4d6f8a0c1e3b5d7f9a1c3e"
        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.

Por qué el primer script del headCopiar enlace de la sección

El bootstrapper solo observa lo que ocurre después de él. Un script que se ejecuta antes puede guardar referencias originales de fetch o addEventListener y escapar de la observación.

Si hay cualquier script antes del bootstrapper, 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.

Los scripts escritos en el HTML de la página se ejecutan antes de que cargue el SDK y no se pueden impedir en el navegador. Para bloquear uno de ellos, quita la etiqueta del HTML o del tema. Los scripts insertados por JavaScript, incluidas las etiquetas que dispara Google Tag Manager, pasan por el bootstrapper y se bloquean antes de ejecutarse.

En qué páginas instalarloCopiar enlace de la sección

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 (por ejemplo, /obrigado o /sucesso), si aceptas tarjeta. El SDK usa esa página para confirmar el pago con tarjeta cuando no logra observar la respuesta del proveedor.

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 sitioCopiar enlace de la sección

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 latestCopiar enlace de la sección

El canal de release define qué build del shield.js carga el snippet. Se elige en Ajustes → Protección del pago → Canal de release del SDK.

No existen URLs con número de versión: no es posible fijar una versión específica del SDK.

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 SDKCopiar enlace de la sección

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.

Próximos pasosCopiar enlace de la sección

• Instalación por plataforma
• Verificar la instalación
• Configuración