# Integración

> Entiende cómo funciona el SDK de Proteside en el checkout antes de instalarlo.

URL: https://docs.proteside.com/es/docs/integration

Proteside es un SDK client-side que se ejecuta en las páginas de pago de tu tienda. Mantiene el inventario de los
scripts que se ejecutan en el navegador del cliente, detecta manipulaciones (skimming, cambio de clave Pix, secuestro de
formularios, exfiltración de datos) y envía las evidencias al dashboard. Estas evidencias respaldan los controles de PCI
DSS 4.0, requisitos 6.4.3 y 11.6.1.

Esta sección explica la instalación en el checkout y el comportamiento del SDK en el navegador. Para usar el dashboard
en el día a día, consulta la [Guía del usuario](https://docs.proteside.com/es/docs/guide). Si todavía estás evaluando el producto, empieza por
[Cómo funciona Proteside](https://proteside.com/es/como-funciona).

## Cómo funciona
La instalación es un único bloque de código que pegas en el `<head>` del checkout. Internamente, tiene dos partes con
funciones distintas:

1. **Bootstrapper (inline y síncrono).** Un `<script>` pequeño, pegado directamente en el HTML, que debe ser el
   **primer script del `<head>`**. No hace ninguna solicitud de red. El bootstrapper empieza a observar la página de
   inmediato, antes que cualquier otro script, y bloquea los scripts prohibidos por tus reglas antes de que entren en
   la página.
2. **SDK `shield.js` (asíncrono, servido por la CDN).** Se carga desde `https://cdn.proteside.com/v1/shield.js` con
   `async`, sin bloquear el renderizado. Lee la clave del atributo `data-key`, obtiene la configuración de la tienda e
   inicia los módulos de detección.
3. **Configuración remota.** Al iniciar, el SDK obtiene de `app.proteside.com` lo que definiste en el dashboard: modo
   de protección, reglas, destinatarios confiables, orígenes de iframe esperados y ajustes finos. Los cambios llegan al
   checkout en pocos minutos.
4. **Envío de eventos.** Las detecciones y la telemetría se envían en lotes pequeños a `app.proteside.com`. El
   dashboard convierte los eventos relevantes en alertas y actualiza el inventario de **Scripts** y la
   **Salud del SDK**.

> **¿Por qué dos partes?**
>
> Un script cargado con `async` se ejecuta después de otros scripts de la página. Solo un fragmento inline y síncrono,
> colocado antes de todos, garantiza una cobertura completa desde el inicio de la carga. Por eso nunca debes
> reemplazar el bootstrapper por un `<script src>` externo.

## Qué detecta Proteside
* **Scripts nuevos o modificados** después de que la página cargó, clasificados como propios, de terceros conocidos o
  desconocidos.
* **Scripts bloqueados** por tus reglas y contenedores de Google Tag Manager fuera de la lista permitida.
* **Keyloggers:** un script empieza a capturar lo que se escribe en un campo sensible.
* **Exfiltración:** datos sensibles del cliente se envían a un destino no confiable.
* **Manipulación del pago:** cambio del código Pix copia y pega, de la dirección cripto, del VPA de UPI, del banco del
  boleto o del monto; cambio del contenido copiado al portapapeles.
* **Secuestro de formularios y de iframes:** cambio del `action` de un formulario, cambio del iframe del proveedor de
  pagos, iframes inesperados y elementos superpuestos a los campos de pago.
* **Service workers** no autorizados.
* **Encabezados de seguridad** (headers) de la página de pago (CSP, HSTS y otros), para detectar cambios.

La lista completa, con severidades, está en [Eventos y detecciones](https://docs.proteside.com/es/docs/integration/events).

## Qué no recopila Proteside
El SDK está diseñado para no transportar datos de pago:

* nunca lee el valor escrito en los campos de formulario ni registra teclas;
* nunca envía número de tarjeta, CVV, clave Pix, código copia y pega, dirección cripto ni línea digitable;
* nunca envía el contenido copiado al portapapeles, el cuerpo de las solicitudes ni el código de los scripts (solo
  hashes, tamaños y nombres de patrones encontrados);
* no guarda cookies ni `localStorage`.

Hay puntos que debes conocer, como el envío de la URL completa de la página. Consulta
[Privacidad y LGPD](https://docs.proteside.com/es/docs/integration/privacy).

## Del primer pageview al dashboard
Esto es lo que ocurre cuando un cliente abre el checkout con el snippet instalado:

1. El navegador ejecuta el bootstrapper (menos de 1 ms) y sigue cargando la página con normalidad.
2. El `shield.js` llega desde la CDN y obtiene la configuración de la tienda.
3. El SDK envía un `PAGEVIEW`. Justo después de la carga, el SDK establece la referencia de la página. Los scripts
   presentes en ese momento entran en el inventario y necesitan tu revisión en **Scripts**.
4. Los scripts que el dashboard todavía no conoce aparecen en **Scripts** con el estado **Requiere revisión**.
5. A partir de ahí, cualquier script nuevo o comportamiento sospechoso se convierte en una detección.
6. Los eventos se envían en lotes pequeños y cuando el cliente sale de la página. El indicador **Proteside activo** en
   la parte superior del dashboard y la página **Salud del SDK** empiezan a reflejar el tráfico real.

> **Nota**
>
> La decisión sobre cada script del inventario (autorizar o bloquear) es tuya, en la página
> [Scripts](https://docs.proteside.com/es/docs/guide/scripts).

## Próximos pasos
- [Instalación del snippet](https://docs.proteside.com/es/docs/integration/install): Dónde obtener el snippet y dónde pegarlo.
- [Instalación por plataforma](https://docs.proteside.com/es/docs/integration/platforms): HTML, Next.js, Nuxt, WordPress y otras plataformas.
- [Verificar la instalación](https://docs.proteside.com/es/docs/integration/verify): Confirma que el SDK está activo.
- [Configuración](https://docs.proteside.com/es/docs/integration/configuration): Atributos, configuración remota y modos de protección.
- [Integridad de pagos y Pix](https://docs.proteside.com/es/docs/integration/payment-integrity): Destinatarios confiables y validación del pago.
- [API de JavaScript](https://docs.proteside.com/es/docs/integration/javascript-api): Métodos de window.Proteside.
- [Eventos y detecciones](https://docs.proteside.com/es/docs/integration/events): Tipos de evento, severidad y alertas.
- [CSP y headers](https://docs.proteside.com/es/docs/integration/csp): Content Security Policy y su relación con PCI DSS.
- [Privacidad y LGPD](https://docs.proteside.com/es/docs/integration/privacy): Qué se recopila y qué nunca se recopila.
- [Rendimiento y compatibilidad](https://docs.proteside.com/es/docs/integration/performance): Tamaño, carga y navegadores.
- [Sello Proteside](https://docs.proteside.com/es/docs/integration/badge): Sello estático opcional para el checkout.
- [Solución de problemas](https://docs.proteside.com/es/docs/integration/troubleshooting): Errores comunes y cómo resolverlos.
