# Instalar el widget con una etiqueta de script

Pega una etiqueta de script con atributos data- y el widget de soporte arranca solo en tu web, sin compilar nada.

La forma más rápida de poner el widget de soporte en tu web: pegas una etiqueta `<script>` antes del cierre de `</body>` y el widget se inicia solo con los atributos que lleva la propia etiqueta. No necesitas compilar ni escribir JavaScript.

Antes, prepara la aplicación externa, su clave y tus dominios autorizados como se explica en la [visión general](https://os.utilia.ai/docs/developers/widget/overview).

## La etiqueta mínima

```html
<script
  src="https://cdn.utilia.ai/widget/utilia-widget.js"
  data-utilia-widget
  data-base-url="https://os.utilia.ai/api"
  data-api-key="TU_CLAVE_DE_API"
  data-user-id="9b2f6c1e-4d7a-4f0e-8a51-3c6d2e7f1a90"
  data-user-signature="FIRMA_CALCULADA_EN_TU_SERVIDOR"
></script>
```

- `data-utilia-widget` marca la etiqueta: el script busca la primera que lo lleve y lee de ella la configuración.
- `data-base-url`, `data-api-key` y `data-user-id` son obligatorios. Si falta alguno, el widget no arranca y escribe en la consola del navegador un aviso que empieza por `[UtiliaWidget]`.
- `data-user-id` es el identificador de la persona en tu sistema. Pon el de quien ha iniciado sesión en tu web, opaco y que no se pueda adivinar: el widget enseña los tickets de ese identificador.
- `data-user-signature` es la firma de ese identificador, que calcula tu servidor con el secreto del widget. Con la verificación obligatoria, sin ella el widget no funciona. Lo explica [Verificar la identidad en el widget](https://os.utilia.ai/docs/developers/widget/identity-verification).

## Qué pasa al cargar la página

El script espera a que la página termine de cargarse, así que puedes ponerlo en cualquier parte del documento. Después hace esto:

**El widget al cargar tu página**

Participantes: Tu página, Widget y UTILIA OS.

1. Tu página → Widget: Carga utilia-widget.js. El script busca la etiqueta con data-utilia-widget y lee sus atributos.
2. Widget (por su cuenta): Crea el elemento utilia-support al final de la página.
3. Widget → UTILIA OS: `POST /api/external/v1/users/identify`. Da de alta o actualiza a la persona con su data-user-id.
4. Widget → UTILIA OS: `GET /api/external/v1/tickets/unread-count`. Pide cuántos mensajes tiene sin leer.
5. UTILIA OS → Widget (respuesta): Número de no leídos. El botón flotante aparece con su contador.

Son dos peticiones por cada carga de página, que cuentan para el límite de la clave. El asistente con IA del formulario gasta bastantes más: lo cuenta [Límite de peticiones](https://os.utilia.ai/docs/developers/widget/overview#límite-de-peticiones).

## Todos los atributos

| Nombre | Tipo | Obligatorio | Por defecto | Descripción |
| - | - | - | - | - |
| `data-base-url` | `string` | Sí | | Dirección base de la API: `https://os.utilia.ai/api`. |
| `data-api-key` | `string` | Sí | | Clave de API de la aplicación externa. |
| `data-user-id` | `string` | Sí | | Identificador opaco de la persona en tu sistema. Que no se pueda adivinar. |
| `data-user-signature` | `string` | No | | Firma del data-user-id hecha en tu servidor con el secreto del widget (HMAC-SHA256 en hexadecimal). Obligatoria si la aplicación exige la verificación de identidad. Desde la versión 1.2.0 del widget. |
| `data-user-email` | `string` | No | | Correo de la persona. Se guarda al identificarla. |
| `data-user-name` | `string` | No | | Nombre de la persona. Se guarda al identificarla. |
| `data-position` | `'bottom-right' \| 'bottom-left'` | No | `bottom-right` | Esquina en la que aparece el botón. |
| `data-theme` | `'light' \| 'dark' \| 'auto'` | No | `light` | Aspecto del widget. `auto` se acepta, pero hoy se pinta igual que `light`. |
| `data-auto-context` | `'true' \| 'false'` | No | `true` | Adjunta a cada ticket la dirección de la página y los datos del navegador. Solo se desactiva con `false`. |

Ejemplo completo:

```html
<script
  src="https://cdn.utilia.ai/widget/utilia-widget.js"
  data-utilia-widget
  data-base-url="https://os.utilia.ai/api"
  data-api-key="TU_CLAVE_DE_API"
  data-user-id="9b2f6c1e-4d7a-4f0e-8a51-3c6d2e7f1a90"
  data-user-email="ana@tuempresa.example"
  data-user-name="Ana García"
  data-position="bottom-left"
  data-theme="dark"
></script>
```

Con la etiqueta no puedes fijar la categoría ni la prioridad por defecto, ni pasar metadatos del usuario o callbacks. Si los necesitas, usa el [paquete npm](https://os.utilia.ai/docs/developers/widget/npm-react).

## Si prefieres servir el archivo tú

El paquete npm `@utilia-os/widget` incluye el mismo archivo listo para la etiqueta, `dist/utilia-widget.js`. Puedes copiarlo a tu servidor y cambiar el `src` por tu propia dirección; el resto de la etiqueta no cambia.

## Siguiente paso

Abre la página, pulsa el botón y crea un ticket de prueba. Si quieres reaccionar a lo que ocurre en el widget desde tu página, mira los [eventos y callbacks](https://os.utilia.ai/docs/developers/widget/events-and-callbacks); para adaptar los colores, las [variables CSS](https://os.utilia.ai/docs/developers/widget/css-variables).