Proteside 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 a través de 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 en https://app.proteside.com/api/sdk/config. Cuando las
capas no coinciden, vale este orden de prioridad:
- Configuración remota (lo que está guardado en el dashboard);
- Snippet (atributos
data-*y reglas inlinewindow.__PROTE_INLINE__); - Valores predeterminados del SDK.
| Comportamiento | Detalle |
|---|---|
| Tiempo límite | 2 segundos. Si la respuesta no llega, el SDK continúa con el snippet y los valores predeterminados. |
| Falla | Una clave inválida, un error o la falta de red no rompen la página: el SDK continúa con los valores predeterminados locales. |
| Inicio de las detecciones | Los módulos de detección solo empiezan después de la respuesta (o del tiempo límite). Hasta entonces, el bootstrapper guarda lo que ocurre y el SDK lo procesa después. |
| Caché | La respuesta puede quedar en caché durante 60 segundos en el navegador y en la CDN. |
Los cambios pueden tardar más de 60 segundos
El dashboard dice que los cambios llegan al SDK en hasta 60 segundos. La CDN puede seguir sirviendo la respuesta
anterior durante algunos minutos más mientras obtiene la nueva, sobre todo en tiendas con poco tráfico. Para probar
un cambio, espera algunos minutos y compruébalo con Proteside.getStatus().
Qué viene del dashboard
La mayor parte está en Ajustes → Protección del pago:
| Ajuste en el dashboard | Efecto en el SDK |
|---|---|
| Destinatarios confiables | Hashes de las claves Pix, direcciones cripto, VPAs de UPI y bancos de boleto de la tienda. Consulta Integridad de pagos y Pix. |
| Modo de protección | Monitorear o Bloquear. Consulta más abajo. |
| Modo desarrollador | Pausa el SDK. Consulta Pausa y modo desarrollador. |
| Canal de release del SDK | Solo informativo para el SDK. El canal efectivo es la URL pegada en el snippet. Consulta Canales. |
| Orígenes de iframe esperados | Hosts de los iframes de pago legítimos. Con la lista completa, el SDK alerta sobre iframes de proveedores que no están en ella, iframes superpuestos a los esperados y campos de tarjeta editables fuera del iframe. |
| Contenedores GTM permitidos | Con la lista completa, los contenedores de Google Tag Manager que no están en ella se bloquean. Consulta el aviso de abajo. |
| Service workers permitidos | Con la lista completa, los service workers que no están en ella se reportan y, en modo Bloquear, se eliminan. |
| Métodos de pago | Métodos que se muestran como monitoreados. No desactiva la detección. Consulta Métodos de pago. |
| Campos sensibles | Selectores de los campos vigilados contra keyloggers y superposiciones. |
| Calibración (segundos) | Tiempo de aprendizaje después de la carga (10 a 120 s, predeterminado 30). |
| Verificación de overlay (ms) | Intervalo entre verificaciones de elementos superpuestos (mínimo 500, predeterminado 2000). |
| Orden de instalación | Avisar (alerta) envía INSTALLATION_ORDER_WARNING; Silenciar no envía el evento, pero installationOrderValid sigue en false. |
Las reglas de Reglas (bloquear o permitir por Dominio o URL del script) también llegan en la configuración remota. Las reglas inactivas no se envían. Las listas vacías significan "sin restricción".
Las reglas por hash de contenido no se aplican en el navegador
La pantalla de Reglas ofrece el objetivo Hash de contenido, pero el SDK ignora esas reglas: no bloquean ningún script en el checkout. Para impedir un script, usa una regla por Dominio o URL del script.
Campos sensibles
De forma predeterminada, el SDK vigila estos selectores:
#card-number, #card-cvv, #card-expiry, #card-name,
[data-proteside-sensitive],
input[autocomplete="cc-number"],
input[autocomplete="cc-csc"]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 />Si desactivas Usar la lista predeterminada de Proteside e ingresas una lista propia, esta reemplaza la
predeterminada. Incluye [data-proteside-sensitive] en tu lista si quieres que el atributo siga funcionando.
Modo monitoreo y modo bloqueo
El modo se elige en Protección del pago → Modo de protección y llega al SDK a través de la configuración remota.
Qué ocurre en cualquier modo
Las reglas y la lista de GTM también bloquean en modo Monitorear
La pantalla describe el modo Monitorear como "sin interferir en la página" y dice que los contenedores fuera de la lista se bloquean "en modo Bloquear". En el navegador, las reglas de bloqueo (por dominio o URL) y la lista de Contenedores GTM permitidos bloquean scripts en ambos modos. Si solo quieres observar, no crees reglas de bloqueo y deja vacía la lista de GTM.
- Un script insertado por JavaScript que coincide con una regla de bloqueo nunca llega a entrar en la página. El SDK
envía
SCRIPT_BLOCKED. - Con la lista de GTM completa, se bloquean
googletagmanager.com/gtm.jsygoogletagmanager.com/gtag/jscon un ID que no está en la lista. El SDK envíaGTM_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 bloquea GA4 y Google Ads
La lista solo acepta IDs con el formato GTM-XXXXXXX, pero el bloqueo también aplica a gtag/js. Con la lista
completa, cualquier etiqueta de Google Analytics 4 (G-…) o de Google Ads (AW-…) cargada por JavaScript, incluso
por el propio GTM, se bloquea, y no hay forma de incluir esos IDs en la lista. Antes de activar la lista, confirma si
la tienda usa GA4 o Google Ads cargados de esa forma.
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 | Quita la etiqueta del script después de detectarlo. |
FORM_ACTION_HIJACK | Restaura el action original del formulario. |
OVERLAY_DETECTED | Quita el elemento superpuesto. |
PIX_TAMPERED, UPI_TAMPERED, QR_TAMPERED, BOLETO_TAMPERED, CRYPTO_ADDRESS_SWAP (texto modificado) | 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. |
Estas detecciones solo alertan, en cualquier modo: EXFILTRATION_ATTEMPT, KEYLOGGER_DETECTED,
WEBSOCKET_EXFILTRATION, IFRAME_REPLACED, IFRAME_UNEXPECTED, CARD_FIELD_OUTSIDE_VAULT, AMOUNT_TAMPERED,
SCRIPT_MODIFIED y FIELD_ACCESS.
Quitar un script no deshace lo que ya ejecutó
Cuando un script ya entró en la página, quitar la etiqueta no cancela su ejecución. Solo el bloqueo antes de la inserción, que hace el bootstrapper con las reglas, impide realmente que el script se ejecute. Por eso, para un script no deseado, crea una regla de bloqueo en lugar de depender solo del modo Bloquear.
En modo Bloquear, una regla incorrecta 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;
- la suscripción no está vigente o la tienda no está activa.
En pausa, el SDK envía un único PAGEVIEW marcado como en pausa en cada carga de página (la pantalla habla de "1
pageview por sesión") y no inicia ningún módulo de detección. Proteside.getStatus().paused queda en true y la
Salud del SDK muestra SDK en pausa (modo desarrollador).
Las reglas inline siguen vigentes en modo desarrollador
El bootstrapper aplica las reglas guardadas en el snippet (window.__PROTE_INLINE__) antes de saber que la tienda
está en pausa. Con el modo desarrollador activado, los scripts que coinciden con esas reglas 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.
También existe la pausa local, que la propia página activa con Proteside.pause().
Solo aplica a esa carga.
Canales
El canal de release (stable o latest) lo define la URL del shield.js en el snippet. Consulta
Canales stable y latest.