Proteside Docs

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:

  1. Configuración remota (lo que está guardado en el dashboard);
  2. Snippet (atributos data-* y reglas inline);
  3. 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 1 de la pantalla Protección del pago: cómo funciona la verificación, destinatarios vistos en el checkout, destinatarios confiables y registro manual
Paso y ajuste en el dashboardEfecto en el SDK
Quién puede recibir tu dinero → Destinatarios confiablesClaves 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ónMonitorear o Bloquear. Consulta más abajo.
Cómo debe reaccionar el SDK → Opciones para el equipo técnico → Modo desarrolladorPausa el SDK. Consulta Pausa y modo desarrollador.
Cómo debe reaccionar el SDK → Opciones para el equipo técnico → Canal de release del SDKSolo 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 esperadosHosts 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 permitidosCon 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 detectadosSolo 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.com y app.proteside.com nunca 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ónAcción en modo Bloquear
SCRIPT_INJECTION de un script desconocidoElimina la etiqueta del script después de detectarlo.
FORM_ACTION_HIJACKRestaura el action original del formulario.
OVERLAY_DETECTEDElimina 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 confiablesReemplaza el texto leído por ⚠︎ y marca el elemento con data-proteside-blocked="untrusted_recipient".
CLIPBOARD_HIJACKVuelve a escribir el valor original en el portapapeles.
SERVICE_WORKER_BLOCKEDElimina 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.

Próximos pasos

En esta página