Solución de problemas
Causas y soluciones de los problemas más comunes en la instalación y el uso del SDK en el checkout.
Antes que nada, abre el checkout con las herramientas para desarrolladores del navegador y ejecuta
Proteside.getStatus() en la consola. El resultado indica la mayoría de los problemas de abajo. Consulta
Verificar la instalación.
Instalación
El dashboard solo considera activo el SDK cuando recibe eventos de clientes reales. Revisa, en este orden:
- ¿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. - ¿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.
- ¿Alguien abrió el checkout? Abre la página tú mismo y recarga el dashboard después de unos segundos.
- ¿El SDK carga? Ejecuta
Proteside.getStatus()en la consola. Si da error, consulta el siguiente punto. - ¿Salen los eventos? En la pestaña Red, las solicitudes a
app.proteside.comdeben responder con éxito. 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.comenscript-src(la consola muestraRefused 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 cargar la configuración de la tienda. Si sigue en
false:
- Falta el
data-keyen la etiqueta delshield.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 silentlyconInvalid apiKey format. La clave empieza conpk_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 snippet. El snippet debe ser el primer script del <head> para una cobertura completa.
Para comprobarlo, abre el código fuente de la página publicada (Ctrl+U) y revisa si el bloque
<!-- Proteside Start --> viene justo después de la apertura del <head>, antes de cualquier otro <script>.
Cómo corregirlo:
- Hay otro script antes del snippet. Mueve el snippet al inicio del
<head>y vuelve a publicar. En Next.js, revisa el orden final de las etiquetas en el código fuente de la página publicada. - El snippet es antiguo. Los snippets antiguos traían la configuración inline en una etiqueta
<script>separada. Copia el snippet actual en Páginas y Dominios y reemplaza el bloque completo. - 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. Si aceptas esa situación, usa No avisar más en esta tienda en la propia alerta. Solo los propietarios y administradores ven esta opción. Para volver a recibir el aviso, escribe a team@proteside.com.
No edites el contenido del snippet para que desaparezca el aviso: las reglas inline bloquean scripts desde el primer byte de la página.
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 cuenta para el estado de cumplimiento en Evidencias PCI DSS.
El snippet tiene dos partes, y ambas son necesarias para una cobertura completa. 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, vuelve a pegar
el snippet completo y exclúyelo de las optimizaciones de JavaScript.
Para comprobarlo, abre el código fuente de la página publicada (Ctrl+U): entre <!-- Proteside Start --> y
<!-- Proteside End --> debe haber un <script> inline seguido de la etiqueta del shield.js.
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.
Bloqueos y reglas
Mensajes comunes en la consola y qué habilitar:
| Mensaje | Qué falta |
|---|---|
Refused to load the script 'https://cdn.proteside.com/…' | https://cdn.proteside.com en script-src |
Refused to execute inline script | hash, nonce o 'unsafe-inline' para el bootstrapper |
Refused to connect to 'https://app.proteside.com/…' | https://app.proteside.com en connect-src |
El mensaje del script inline indica el hash 'sha256-…' que debes incluir. Consulta
Content Security Policy y headers.
Con Contenedores GTM permitidos completo, las etiquetas de Google Analytics 4 (G-…) y de Google Ads (AW-…)
pueden bloquearse, incluso cuando las dispara el propio GTM. La lista solo acepta IDs GTM-…, así que no hay forma de
habilitar esos IDs.
Para resolverlo:
- En Protección del pago, paso Qué es normal en tu checkout, vacía la lista Contenedores GTM permitidos y haz clic en Guardar esta etapa.
- 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. En Scripts, aparece con el aviso de que sigue cargándose desde el HTML. Quita la etiqueta en el origen (HTML o tema).
- La regla es por Hash de contenido. El bloqueo en el navegador aplica a los scripts cargados por dirección; los scripts inline deben eliminarse en el origen. Usa una regla por Dominio o URL del script.
- La regla está inactiva. Activa la regla en Reglas.
- El cambio todavía no llegó. Consulta Un cambio en el dashboard no llegó al checkout.
- 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.
- Vuelve a copiar el snippet en Páginas y Dominios y publícalo: las reglas quedan guardadas en el snippet.
- 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.
Datos en el dashboard
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.
- Tiempo de propagación: los cambios llegan al checkout en pocos minutos. 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 las respuestas de las solicitudes a app.proteside.com en la pestaña Red:
| Respuesta | Causa | Qué hacer |
|---|---|---|
| Error 4xx | Problema de clave o de cuenta. | Revisa la Salud del SDK. Si cambiaste la clave, copia el snippet actual en Páginas y Dominios. Si la suscripción no está vigente, consulta Facturación. |
| Solicitud bloqueada | CSP sin https://app.proteside.com en connect-src, o bloqueador de anuncios. | Consulta CSP y headers. |
Un dominio que ya envió eventos dejó de recibir sesiones reales. La alerta aparece en un plazo de un día. 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.
Pago
- Todavía ningún cliente pagó con Pix con el SDK en la página. El estado cambia cuando el SDK valida el primer código.
- El código Pix no aparece como texto visible. Para una cobertura completa, muestra el código de pago como texto
visible o infórmalo con
registerPaymentPayload(). 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 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. En ese caso, confirma el destinatario en Destinatarios vistos en tu checkout con Es de mi 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.
En el Pix dinámico generado por un proveedor de pagos, el código trae la dirección del proveedor en lugar de la clave de la tienda. Confirma el destinatario en Protección del pago → Destinatarios vistos en tu checkout con Es de mi tienda: la clave que usa el proveedor suele no ser la que conoces. La verificación de destinatario se aplica a los códigos que traen el destinatario.
Si el código trae el monto, informa también el monto esperado con
Proteside.expectPayment().
¿Sigues con problemas?
Reúne el resultado de Proteside.getStatus(), las respuestas de las solicitudes a app.proteside.com en la pestaña
Red y la dirección de la página afectada, y escribe a team@proteside.com.