# Instalación del snippet

> Copia el snippet del dashboard y pégalo como primer script del head de las páginas de pago.

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

La instalación es un bloque de código que copias del dashboard y pegas en el `<head>` de las páginas de checkout. No hay
paquete npm ni app para tiendas: el mismo snippet funciona en cualquier sitio en el que controles el HTML del checkout.

## Dónde obtener el snippet
El snippet está en **Ajustes → Páginas y Dominios**, en la tarjeta **Instalación del SDK**:

* **Clave del SDK:** la clave de la tienda, que empieza con `pk_live_`. Es una clave **pública**: va en el HTML de la tienda y solo identifica la tienda ante el SDK.
* **Snippet:** el bloque listo, ya con tu clave, el canal de release y las reglas de bloqueo activas. Hay una pestaña
  para cada plataforma: **HTML**, **Next.js**, **Nuxt** y **WordPress**.

*Imagen: La tarjeta Instalación del SDK muestra la clave y el snippet listo para cada plataforma.*

El asistente de creación de la tienda también muestra el snippet, en el paso de instalación. Ese snippet siempre sale
en el canal `stable` y sin tus reglas. Si ya configuraste reglas o contenedores de Google Tag Manager, copia el snippet
de **Páginas y Dominios**.

## Instalar
### Abre Páginas y Dominios
En el dashboard, ve a **Ajustes → Páginas y Dominios**.

### Copia el snippet de tu plataforma
Elige la pestaña **HTML**, **Next.js**, **Nuxt** o **WordPress** y haz clic en **Copiar**. Para otras plataformas, usa
la pestaña **HTML** y sigue [Instalación por plataforma](https://docs.proteside.com/es/docs/integration/platforms).

### Pégalo como primer elemento del head
Pega el bloque completo justo después de la apertura del `<head>`, **antes** de Google Tag Manager, Stripe.js,
analytics y cualquier otro script, en todas las páginas de checkout y de pago.

### Publica y abre el checkout
Publica el cambio y abre la página de checkout en el navegador. Después, sigue
[Verificar la instalación](https://docs.proteside.com/es/docs/integration/verify).

## Qué contiene el snippet
Este es el formato del snippet HTML que genera el dashboard. El contenido del bootstrapper está abreviado aquí: tiene
unos 4,3 KB de JavaScript minificado y cambia entre versiones. Copia siempre el bloque completo del dashboard.

```html title="Snippet HTML (canal stable)"
<!-- Proteside Start -->
<!-- Place first in <head>, before GTM, Stripe.js, analytics, or any other scripts. -->
<script>/* bootstrapper: contenido completo copiado del dashboard */</script>
<script async src="https://cdn.proteside.com/v1/shield.js"
        data-key="pk_live_TU_CLAVE"
        data-api="https://app.proteside.com/api/sdk"></script>
<!-- Proteside End -->
```

| Parte                                | Función                                                                                            |
| ------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `<script>` inline                    | El bootstrapper. Se ejecuta al instante, sin red, y empieza a observar la página.                  |
| `<script async src=".../shield.js">` | El SDK. Se carga desde la CDN sin bloquear la página.                                              |
| `data-key`                           | La clave del SDK de la tienda. Obligatoria.                                                        |
| `data-api`                           | La dirección de la API de Proteside. El dashboard siempre la completa con el valor predeterminado. |

Los comentarios dentro del snippet quedan en inglés en cualquier idioma del dashboard. Es el comportamiento normal.

### Snippet con reglas inline
Si la tienda tiene reglas de bloqueo activas por dominio o por URL, o una lista de contenedores de Google Tag Manager
permitidos, el dashboard escribe esa configuración al principio del propio `<script>` del bootstrapper:

```html title="Snippet HTML con configuración inline"
<!-- Proteside Start -->
<!-- Place first in <head>, before GTM, Stripe.js, analytics, or any other scripts. -->
<script>/* bootstrapper con las reglas inline: contenido completo copiado del dashboard */</script>
<script async src="https://cdn.proteside.com/v1/shield.js"
        data-key="pk_live_TU_CLAVE"
        data-api="https://app.proteside.com/api/sdk"></script>
<!-- Proteside End -->
```

Ese fragmento permite que el bootstrapper bloquee scripts desde el primer byte de la página, sin esperar la configuración
remota.

> **Las reglas inline quedan congeladas en el HTML**
>
> La configuración inline guarda las reglas del momento en que copiaste el snippet. Cuando el SDK inicia,
> pasa a valer la configuración remota, pero hasta entonces la página usa la versión pegada. Una regla eliminada en el
> dashboard sigue bloqueando en ese intervalo, y una regla nueva solo bloquea desde el primer byte después de que
> vuelvas a pegar el snippet. Vuelve a pegar el snippet siempre que cambies reglas de bloqueo o contenedores de Google
> Tag Manager.

> **No modifiques el snippet**
>
> * No separes el bootstrapper del `shield.js` ni inviertas el orden.
> * No reemplaces el bootstrapper inline por un `<script src>` externo. Debe ejecutarse de forma síncrona.
> * No agregues `async`, `defer` ni `type="module"`. Con `type="module"`, el SDK no se inicializa.
> * Excluye el snippet de los plugins de optimización que combinan, difieren o cargan JavaScript de forma asíncrona.

## Por qué el primer script del head
El snippet debe ser el primer script del `<head>` para una cobertura completa.

Si hay cualquier script antes del snippet, el SDK marca la instalación como fuera de orden: envía el evento
`INSTALLATION_ORDER_WARNING`, que se convierte en una alerta en el dashboard, y
`Proteside.getStatus().installationOrderValid` queda en `false`. La protección continúa, pero con cobertura parcial.
Para corregirlo, mueve el snippet al inicio del `<head>` y vuelve a publicar. Consulta
[Solución de problemas](https://docs.proteside.com/es/docs/integration/troubleshooting#ordem-de-instalacao).

Para bloquear un script escrito en el HTML de la página, quita la etiqueta del HTML o del tema. Los scripts insertados
después, incluidas las etiquetas que dispara Google Tag Manager, se bloquean según tus reglas antes de ejecutarse.

> **Nota**
>
> Los snippets antiguos traían la configuración inline en una etiqueta `<script>` separada, antes del bootstrapper. Si
> usas un snippet antiguo, copia el snippet actual en **Páginas y Dominios** y reemplaza el bloque completo.

## En qué páginas instalarlo
Instala el snippet en las páginas en las que el cliente ingresa o recibe datos de pago:

* el checkout, incluidos los pasos de envío y pago, cuando son páginas separadas;
* las páginas que muestran el código QR o el código Pix copia y pega, el boleto o la dirección cripto;
* la página de confirmación del pedido, si aceptas tarjeta. El SDK usa esa página para confirmar el pago con
  tarjeta.

Si el checkout es una aplicación de página única (SPA), instala el snippet una vez en el HTML base y avisa al SDK de los
cambios de ruta con [`Proteside.pageChanged()`](https://docs.proteside.com/es/docs/integration/javascript-api#pagechangedpath).

### Instalar en todo el sitio
Puedes pegar el snippet en el layout global del sitio. Ten en cuenta lo que cambia:

* El SDK funciona igual en todas las páginas en las que esté. No hay configuración por página que llegue al navegador.
* Todas las páginas aparecen en **Páginas y Dominios** y entran en el inventario de **Scripts**, lo que aumenta el
  volumen de scripts por revisar.
* Cada pageview hace las solicitudes extra del SDK (configuración, eventos y una lectura de los headers de la propia
  página). Consulta [Rendimiento y compatibilidad](https://docs.proteside.com/es/docs/integration/performance).
* Mientras la tienda no tenga páginas de pago registradas, **todos** los pageviews con el SDK cuentan como pageviews
  de páginas de pago en el uso del plan. Las páginas de pago se registran mediante la [API](https://docs.proteside.com/es/docs/api), no desde
  el dashboard.

Para PCI DSS 4.0, requisitos 6.4.3 y 11.6.1, lo que importa son las páginas de pago. Es preferible instalarlo solo en
ellas.

## Canales stable y latest
El canal de release define qué build del `shield.js` carga el snippet. Se elige en
**Ajustes → Protección del pago → Cómo debe reaccionar el SDK → Opciones para el equipo técnico → Canal de release
del SDK**.

| Canal                     | URL del `shield.js`                             | Cuándo se actualiza       |
| ------------------------- | ----------------------------------------------- | ------------------------- |
| `stable` (predeterminado) | `https://cdn.proteside.com/v1/shield.js`        | con cada versión validada |
| `latest`                  | `https://cdn.proteside.com/v1/latest/shield.js` | con cada publicación      |

> **Cambiar el canal exige volver a pegar el snippet**
>
> La pantalla de Protección del pago dice que no hace falta reinstalar al cambiar el canal. Pero la URL del `shield.js`
> está escrita en el snippet: lo que ya está pegado sigue cargando el canal anterior. Después de cambiar el canal,
> vuelve a copiar el snippet en **Páginas y Dominios** y publícalo. Cuando la tienda usa `latest`, el snippet muestra la
> insignia **canal latest**.

El `shield.js` se actualiza solo a través de la CDN. El bootstrapper, por ser inline, solo cambia cuando vuelves a
pegar el snippet.

## Cambiar la clave del SDK
Si necesitas una clave nueva, usa **Rotar** en **Páginas y Dominios** y escribe `ROTAR` para confirmar. Solo los
propietarios y administradores pueden completar el cambio. La clave anterior sigue funcionando durante **24 horas**.
En ese plazo, pega el snippet actualizado en todas las páginas: después, la clave anterior deja de aceptarse y los
eventos de esas páginas se pierden sin aviso.

## Próximos pasos
* [Instalación por plataforma](https://docs.proteside.com/es/docs/integration/platforms)
* [Verificar la instalación](https://docs.proteside.com/es/docs/integration/verify)
* [Configuración](https://docs.proteside.com/es/docs/integration/configuration)
