Solución de problemas

El dashboard solo considera activo el SDK cuando recibe eventos de clientes reales. Revisa, en este orden:

1. ¿El snippet está publicado? Mira el código fuente de la página de checkout publicada y busca Proteside Start. Limpia las cachés del sitio, del tema y de la CDN.
2. ¿Está en el dominio correcto? El snippet debe estar en las páginas en las que realmente se ejecuta el checkout, que pueden estar en otro dominio o subdominio.
3. ¿Alguien abrió el checkout? Abre la página tú mismo y recarga el dashboard después de unos segundos.
4. ¿El SDK carga? Ejecuta Proteside.getStatus() en la consola. Si da error, consulta el siguiente punto.
5. ¿Salen los eventos? En la pestaña Red, POST …/api/sdk/events debe responder 202. Consulta el punto El SDK se ejecuta, pero no llega nada al dashboard.

Si la página Salud del SDK muestra Solo verificación sintética, el verificador de Proteside encontró el snippet, pero todavía ningún cliente real pasó por el checkout.

El shield.js no cargó. Causas comunes:

• el snippet no está publicado, o solo se pegó el bootstrapper;
• la Content Security Policy no permite https://cdn.proteside.com en script-src (la consola muestra Refused to load the script);
• una extensión de bloqueo de anuncios o rastreadores bloqueó el archivo (prueba en una ventana de incógnito sin extensiones);
• un plugin de optimización modificó o eliminó la etiqueta.

Espera unos segundos: el SDK solo termina de iniciar después de obtener la configuración (hasta 2 s). Si sigue en false:

• Falta el data-key en la etiqueta del shield.js. Sin él, el SDK no se inicializa y no muestra ningún aviso.
• La clave tiene un formato inválido. La consola muestra [Proteside] Initialization failed silently con Invalid apiKey format. La clave empieza con pk_live_.
• La etiqueta se cargó como type="module". Quita ese atributo.

El SDK envía este aviso, y getStatus().installationOrderValid queda en false, cuando hay algún <script> en la página antes del bootstrapper.

Para ver cuáles son los dos primeros scripts de la página, ejecuta en la consola:

Array.from(document.scripts).slice(0, 2).map((s) => s.src || s.textContent.slice(0, 40))

• El primer elemento empieza con "use strict"; (seguido de var __ProteBoots o, si la tienda tiene reglas inline, de window.__PROTE_INLINE__=): el bootstrapper es el primer script y el orden es correcto.
• El primer elemento empieza con window.__PROTE_INLINE__= y el segundo con "use strict";var __ProteBoots: es el caso 1.
• Cualquier otra cosa: es el caso 2.

Después de corregirlo, resuelve la alerta en el dashboard. Si no vuelve en el siguiente acceso a la página, el orden es correcto.

Este aviso no entra en el estado de cumplimiento de Evidencias PCI DSS.

Caso 1: snippet antiguo, con la línea window.__PROTE_INLINE__ en su propia etiqueta. En tiendas con reglas de bloqueo o contenedores GTM permitidos, el snippet del dashboard traía la configuración en un <script> separado, antes del bootstrapper. Hoy va al principio del propio <script> del bootstrapper. Desde el SDK 1.1.2, la etiqueta antigua no cuenta como script anterior, siempre que contenga solo la asignación window.__PROTE_INLINE__={…};. Si el aviso continúa:

• revisa en Salud del SDK si la página todavía usa una versión anterior a la 1.1.2;
• comprueba que nadie haya agregado código a la línea window.__PROTE_INLINE__ ni reescrito el JSON: con cualquier otro contenido, la etiqueta vuelve a contar como script anterior;
• o vuelve a pegar el snippet desde Páginas y Dominios. El formato actual tiene una sola etiqueta inline y no depende de la versión del SDK.

No borres la configuración window.__PROTE_INLINE__ para que desaparezca el aviso: es la que bloquea scripts desde el primer byte de la página.

Caso 2: hay otro script antes del snippet. Mueve el snippet al principio del <head> y vuelve a publicar. Si el script anterior viene del tema, de un plugin o de la propia plataforma y no se puede mover, la protección sigue funcionando, pero con cobertura parcial: lo que ese script haga antes del bootstrapper no se observa. En Next.js, revisa el orden final de las etiquetas en el código fuente de la página publicada.

Estas detecciones dependen del bootstrapper. Si solo se pegó la etiqueta del shield.js, o si un plugin de optimización convirtió el bootstrapper en un archivo externo o diferido, el SDK funciona con cobertura reducida, y getStatus() no lo indica. Compruébalo en la consola:

typeof window.__PROTE_BOOT_TS__ === 'number' // debe ser true

Si es false, vuelve a pegar el snippet completo y exclúyelo de las optimizaciones de JavaScript.

La URL del shield.js (canal stable o latest) está escrita en el snippet. Después de cambiar el canal en Protección del pago, vuelve a copiar el snippet en Páginas y Dominios y publícalo.

Si la Salud del SDK muestra más de una versión activa durante algunos días, verifica que todas las páginas usen el mismo snippet. Justo después de una actualización, es normal ver dos versiones por la caché del navegador y de la CDN.

Mensajes comunes en la consola y qué habilitar:

El mensaje del script inline indica el hash 'sha256-…' que debes incluir. Consulta Content Security Policy y headers.

Con Contenedores GTM permitidos completo, el SDK bloquea cualquier gtag/js con un ID que no está en la lista, incluidas las etiquetas de Google Analytics 4 (G-…) y de Google Ads (AW-…) que dispara el propio GTM. La lista solo acepta IDs GTM-…, así que no hay forma de habilitar esos IDs.

Para resolverlo:

1. En Protección del pago, vacía la lista Contenedores GTM permitidos y haz clic en Guardar cambios.
2. Vuelve a copiar el snippet en Páginas y Dominios y publícalo. La lista también queda guardada en el snippet y sigue bloqueando al inicio de la carga hasta que lo vuelvas a pegar.

El bloqueo aplica en ambos modos de protección, Monitorear y Bloquear.

• El script está en el HTML de la página. Los scripts escritos en el HTML se ejecutan antes de que cargue el SDK y no se pueden impedir en el navegador. En Scripts, aparecen con el aviso de que siguen cargándose desde el HTML. Quita la etiqueta del HTML o del tema.
• La regla es por Hash de contenido. El SDK no aplica reglas de este tipo. Usa Dominio o URL del script.
• La regla está inactiva. Las reglas inactivas no se envían al SDK.
• El cambio todavía no llegó. Consulta Un cambio en el dashboard no llegó al checkout.

1. En Reglas, desactiva la regla que coincide con el script afectado. Recuerda que una regla por Dominio bloquea el dominio completo y todos sus subdominios.
2. Vuelve a copiar el snippet en Páginas y Dominios y publícalo: las reglas quedan guardadas en el snippet.
3. Si activaste el modo Bloquear, vuelve a Monitorear mientras investigas.

Activar el Modo desarrollador no deshace los bloqueos guardados en el snippet. Consulta Pausa y modo desarrollador.

Es lo esperado. Todo script nuevo que encuentra el SDK entra en el inventario con el estado Requiere revisión y espera tu decisión. Para cumplir con PCI DSS 4.0, requisito 6.4.3, autoriza cada script legítimo con una justificación o bloquea los indebidos. Puedes autorizar todos los scripts propios de una vez y crear políticas para automatizar decisiones recurrentes.

Un script autorizado vuelve a Requiere revisión cuando su contenido cambia o cuando vence la vigencia de la autorización. Consulta Scripts y Políticas.

• Caché de la configuración: la configuración puede quedar en caché durante 60 segundos, y la CDN puede servir la versión anterior durante algunos minutos más. Espera y recarga el checkout.
• Reglas y contenedores GTM: quedan guardados en el snippet. Vuelve a pegar el snippet después de cambiarlos.
• Canal de release: exige volver a pegar el snippet.

Mira la respuesta de GET …/api/sdk/config y de POST …/api/sdk/events en la pestaña Red:

Un dominio que ya envió eventos pasó 24 horas sin sesiones reales. Verifica si el snippet sigue publicado (una actualización del tema o de la plantilla puede quitarlo) y si el checkout recibió visitas en el período. La alerta se resuelve sola cuando vuelve el tráfico.

• Todavía ningún cliente pagó con Pix con el SDK en la página. El estado cambia con la primera lectura válida.
• El código Pix está en un campo <input> o <textarea>. El SDK solo lee texto. Muestra el código como texto. Consulta Integridad de pagos y Pix.
• El snippet no está en la página que muestra el Pix, por ejemplo una página de pago separada del checkout.
• El código está dentro de un iframe del proveedor de pagos. El SDK solo lee la página principal, no el contenido de los iframes.

El destinatario leído en el código no está entre los Destinatarios confiables. Antes de tratarlo como un ataque, revisa:

• si la clave registrada es la misma que aparece en el código copia y pega que genera tu proveedor de pagos. Algunos proveedores generan el código con una clave propia, distinta de la clave de la tienda;
• si todas las claves que usa la tienda están registradas y activas.

Si la clave del código no pertenece a la tienda ni a tu proveedor, trátalo como un incidente: abre la alerta en Alertas.

Un BRCode dinámico trae una URL de cobro en lugar de la clave del destinatario, así que no hay clave para comparar con la lista de confiables. El SDK sigue comparando el código mostrado con la primera lectura de la página. Si el código trae el monto, informa también el monto esperado con Proteside.expectPayment().