Configuración
Atributos del snippet, configuración remota, modos monitoreo y bloqueo, pausa y canales.
Casi toda la configuración del SDK se hace en el dashboard y llega al navegador mediante la configuración remota. El snippet solo lleva la clave de la tienda y, cuando las hay, las reglas inline. Esta página muestra de dónde viene cada ajuste y qué hace realmente en el checkout.
Atributos del snippet
El shield.js lee los atributos data-* de su propia etiqueta <script>:
Propiedad
Tipo
No existen otros atributos. El modo de protección y el canal no se definen por atributo: el modo viene del
dashboard y el canal es la propia URL del shield.js. El atributo data-safe-url, de versiones antiguas del snippet,
se ignora.
Configuración remota
Al iniciar, el SDK obtiene la configuración de la tienda de app.proteside.com. Cuando las capas difieren, se aplica
este orden de prioridad:
- Configuración remota (lo que está guardado en el dashboard);
- Snippet (atributos
data-*y reglas inline); - Valores predeterminados del SDK.
Una clave inválida, un error o la falta de red nunca rompen la página. Los cambios llegan al checkout en pocos minutos. Para comprobar un cambio, espera unos minutos y recarga el checkout.
Qué viene del dashboard
La mayor parte está en Ajustes → Protección del pago, organizada en cuatro pasos:

| Paso y ajuste en el dashboard | Efecto en el SDK |
|---|---|
| Quién puede recibir tu dinero → Destinatarios confiables | Claves Pix, cuentas, billeteras cripto y bancos de boleto de la tienda. Consulta Integridad de pagos y Pix. |
| Cómo debe reaccionar el SDK → Modo de protección | Monitorear o Bloquear. Consulta más abajo. |
| Cómo debe reaccionar el SDK → Opciones para el equipo técnico → Modo desarrollador | Pausa el SDK. Consulta Pausa y modo desarrollador. |
| Cómo debe reaccionar el SDK → Opciones para el equipo técnico → Canal de release del SDK | Solo informativo para el SDK. El canal efectivo es la URL pegada en el snippet. Consulta Canales. |
| Qué es normal en tu checkout → Orígenes de iframe esperados | Hosts de los iframes de pago legítimos. Con la lista completa, el SDK alerta sobre iframes de proveedores fuera de ella, iframes superpuestos a los esperados y campos de tarjeta editables fuera del iframe. |
| Qué es normal en tu checkout → Contenedores GTM permitidos | Con la lista completa, los contenedores fuera de ella se bloquean. Consulta el aviso más abajo. |
| Qué es normal en tu checkout → Service workers permitidos (avanzado) | Con la lista completa, los service workers fuera de ella se reportan y, en modo Bloquear, se eliminan. |
| Medios de pago detectados | Solo lectura. El SDK reconoce por sí solo los medios de pago de la página; no hay nada que marcar. |
| Campos extra para vigilar → Selectores extra (opcional) | Campos sensibles con nombres fuera del estándar. Los selectores se suman a la detección automática; no se desactiva nada. |
El aviso de orden de instalación ya no se configura en esta pantalla. La propia alerta INSTALLATION_ORDER_WARNING
ofrece la opción No avisar más en esta tienda. Consulta
Solución de problemas.
Las reglas de Reglas (bloquear o permitir por Dominio o URL del script) también llegan mediante la configuración remota.
Bloqueo por dirección
El bloqueo en el navegador aplica a los scripts cargados por dirección; los scripts inline deben eliminarse en el origen. Para impedir un script, usa una regla por Dominio o URL del script.
Campos sensibles
El SDK reconoce los campos de tarjeta más comunes; marca otros con data-proteside-sensitive o configúralos en
Protección del pago.
Para incluir un campo propio sin tocar el dashboard, márcalo con el atributo data-proteside-sensitive:
<input id="cpf" name="cpf" data-proteside-sensitive />En el dashboard, usa Campos extra para vigilar → Selectores extra (opcional), con un selector CSS por línea. Lo que agregues se suma a la detección automática: la lista no reemplaza los campos que el SDK ya reconoce.
Modo monitoreo y modo bloqueo
El modo se elige en Protección del pago → Cómo debe reaccionar el SDK → Modo de protección y llega al SDK mediante la configuración remota.
Qué ocurre en cualquier modo
Las reglas y la lista de GTM bloquean también en modo Monitorear
Las reglas de bloqueo (por dominio o URL) y la lista de Contenedores GTM permitidos bloquean scripts en ambos modos. El modo solo decide las reacciones automáticas del SDK ante lo que no tiene regla. Si solo quieres observar, no crees reglas de bloqueo y deja vacía la lista de GTM.
- Un script que coincide con una regla de bloqueo se bloquea antes de entrar en la página, y el SDK envía
SCRIPT_BLOCKED. Los scripts escritos en el HTML de la página deben eliminarse en el origen. - Con la lista de GTM completa, los contenedores fuera de ella se bloquean. El SDK envía
GTM_CONTAINER_BLOCKED. - Una regla Permitir que coincida con el script anula las reglas de bloqueo.
cdn.proteside.comyapp.proteside.comnunca se bloquean.
La lista de GTM también puede bloquear GA4 y Google Ads
La lista acepta solo IDs con el formato GTM-XXXXXXX. Con ella completa, las etiquetas de Google Analytics 4
(G-…) y de Google Ads (AW-…) también pueden bloquearse, incluso cuando las dispara el propio GTM, y no hay forma
de incluir esos IDs en la lista. Antes de activar la lista, confirma si la tienda usa esas etiquetas y prueba el
checkout.
Qué cambia en modo Bloquear
Además de alertar, el SDK intenta neutralizar la manipulación:
| Detección | Acción en modo Bloquear |
|---|---|
SCRIPT_INJECTION de un script desconocido | Elimina la etiqueta del script después de detectarlo. |
FORM_ACTION_HIJACK | Restaura el action original del formulario. |
OVERLAY_DETECTED | Elimina el elemento superpuesto. |
PIX_TAMPERED, UPI_TAMPERED, QR_TAMPERED, BOLETO_TAMPERED, CRYPTO_ADDRESS_SWAP (texto alterado) | Reescribe el texto con el valor original capturado. |
| Destinatario fuera de la lista de confiables | Reemplaza el texto leído por ⚠︎ y marca el elemento con data-proteside-blocked="untrusted_recipient". |
CLIPBOARD_HIJACK | Vuelve a escribir el valor original en el portapapeles. |
SERVICE_WORKER_BLOCKED | Elimina el registro del service worker. |
Para un script no deseado, crea también una regla de bloqueo en Reglas. Las detecciones de envío de datos exigen acción inmediata a partir de la alerta.
En modo Bloquear, una regla equivocada puede romper el checkout. Empieza en Monitorear, revisa las alertas durante algunas semanas y prueba el modo Bloquear en una página de poco tráfico antes de activarlo en toda la tienda.
Pausa y modo desarrollador
El SDK queda en pausa cuando:
- el Modo desarrollador está activado en Protección del pago → Cómo debe reaccionar el SDK → Opciones para el equipo técnico;
- la suscripción no está vigente o la tienda no está activa.
En pausa, el SDK no ejecuta protecciones y la Salud del SDK muestra SDK en pausa (modo desarrollador).
Las reglas inline siguen aplicándose en modo desarrollador
Las reglas guardadas en el snippet siguen aplicándose con el modo desarrollador activado: los scripts que coinciden con ellas siguen bloqueados, pero sin ningún evento en el dashboard. Si necesitas desactivar un bloqueo durante la integración, elimina la regla y vuelve a pegar el snippet.
Canales
El canal de release (stable o latest) lo define la URL del shield.js en el snippet. Consulta
Canales stable y latest.