# Configuración

> Atributos del snippet, configuración remota, modos monitoreo y bloqueo, pausa y canales.

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

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>`:

- `data-key` (`string`), obligatorio: Clave del SDK de la tienda (empieza con pk_live_). Sin ella, el SDK no se inicializa y no muestra ningún aviso.
- `data-api` (`string`), predeterminado: `https://app.proteside.com/api/sdk`: Dirección base de la API de Proteside, incluida la ruta /api/sdk. El dashboard siempre la completa con el valor predeterminado; no la cambies.

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:

*Imagen: 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 dashboard                                                                        | Efecto en el SDK                                                                                                                                                                                              |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Quién puede recibir tu dinero** → **Destinatarios confiables**                                     | Claves Pix, cuentas, billeteras cripto y bancos de boleto de la tienda. Consulta [Integridad de pagos y Pix](https://docs.proteside.com/es/docs/integration/payment-integrity).                                                                        |
| **Cómo debe reaccionar el SDK** → **Modo de protección**                                             | **Monitorear** o **Bloquear**. Consulta más abajo.                                                                                                                                                            |
| **Cómo debe reaccionar el SDK** → **Opciones para el equipo técnico** → **Modo desarrollador**       | Pausa el SDK. Consulta [Pausa y modo desarrollador](#pausa-y-modo-desarrollador).                                                                                                                             |
| **Cómo debe reaccionar el SDK** → **Opciones para el equipo técnico** → **Canal de release del SDK** | Solo informativo para el SDK. El canal efectivo es la URL pegada en el snippet. Consulta [Canales](https://docs.proteside.com/es/docs/integration/install#canales-stable-y-latest).                                                                    |
| **Qué es normal en tu checkout** → **Orígenes de iframe esperados**                                  | Hosts 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 permitidos**                                   | Con 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 detectados**                                                                        | Solo 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](https://docs.proteside.com/es/docs/integration/troubleshooting#ordem-de-instalacao).

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`:

```html
<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ón                                                                                                | Acción en modo **Bloquear**                                                                               |
| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `SCRIPT_INJECTION` de un script desconocido                                                              | Elimina la etiqueta del script después de detectarlo.                                                     |
| `FORM_ACTION_HIJACK`                                                                                     | Restaura el `action` original del formulario.                                                             |
| `OVERLAY_DETECTED`                                                                                       | Elimina 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 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.                                                                   |

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.

> **Atención**
>
> 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](https://docs.proteside.com/es/docs/integration/install#canales-stable-y-latest).

## Próximos pasos
* [Integridad de pagos y Pix](https://docs.proteside.com/es/docs/integration/payment-integrity)
* [Eventos y detecciones](https://docs.proteside.com/es/docs/integration/events)
* [Protección del pago en el dashboard](https://docs.proteside.com/es/docs/guide/settings/payment-protection)
