# El widget como componente web Declara el widget de soporte en tu HTML con la etiqueta y sus atributos, y contrólalo como cualquier otro elemento. El widget de soporte es un componente web: una etiqueta HTML propia, ``, con sus estilos aislados del resto de tu página. Puedes declararlo directamente en tu HTML o en la plantilla de tu framework, con la configuración en atributos. 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). ## Uso La etiqueta solo existe cuando el código del widget está cargado. Impórtalo una vez en tu aplicación: ```ts import '@utilia-os/widget'; ``` Y declara el elemento donde quieras (su posición en pantalla no depende de dónde lo pongas: siempre flota en una esquina inferior): ```html ``` El widget arranca en cuanto tiene los tres atributos obligatorios: `base-url`, `api-key` y `user-id`. Si alguno falta, se queda sin configurar y no hace ninguna petición. ## Atributos | Nombre | Tipo | Obligatorio | Por defecto | Descripción | | - | - | - | - | - | | `base-url` | `string` | Sí | | Dirección base de la API: `https://os.utilia.ai/api`. | | `api-key` | `string` | Sí | | Clave de API de la aplicación externa. | | `user-id` | `string` | Sí | | Identificador opaco de la persona en tu sistema. Que no se pueda adivinar. | | `user-signature` | `string` | No | | Firma del user-id hecha en tu servidor con el secreto del widget. Obligatoria si la aplicación exige la verificación de identidad. Desde la versión 1.2.0 del widget. | | `user-email` | `string` | No | | Correo de la persona. | | `user-name` | `string` | No | | Nombre de la persona. | | `position` | `'bottom-right' \| 'bottom-left'` | No | `bottom-right` | Esquina en la que aparece el botón. | | `theme` | `'light' \| 'dark' \| 'auto'` | No | `light` | Aspecto del widget. `auto` se acepta, pero hoy se pinta igual que `light`. | Si cambias un atributo con el elemento ya en la página (por ejemplo, `user-id` cuando otra persona inicia sesión), el widget se vuelve a configurar con los valores nuevos. ## Atributos o método init **Configurar el componente web** ### Con atributos (En el HTML) La dirección de la API, la clave, el usuario (identificador, correo y nombre), la posición y el tema. Sin categoría ni prioridad por defecto, sin metadatos, sin contexto automático y sin callbacks. ### Con el método init (Desde tu código) Todas las opciones del paquete npm: además de lo anterior, categoría y prioridad por defecto, metadatos del usuario, contexto automático, onTicketCreated y onError. Sin contexto automático, los tickets se crean sin la dirección de la página ni los datos del navegador. Si necesitas alguna de las opciones que solo admite `init`, configura el mismo elemento desde tu código, que admite todas las opciones del [paquete npm](https://os.utilia.ai/docs/developers/widget/npm-react): ```ts import type { UtiliaSupportWidget } from '@utilia-os/widget'; const widget = document.querySelector('utilia-support') as UtiliaSupportWidget; widget.init({ baseURL: 'https://os.utilia.ai/api', apiKey: 'TU_CLAVE_DE_API', userId: '9b2f6c1e-4d7a-4f0e-8a51-3c6d2e7f1a90', autoContext: true, defaultCategory: 'BUG', }); ``` En ese caso no pongas los atributos obligatorios en la etiqueta: si los tiene, el widget se configura dos veces y repite las peticiones iniciales. ## Controlarlo y escuchar sus eventos El elemento tiene los métodos `open()`, `close()`, `showNewTicketForm()` y `showTicketDetail(ticketId)`, y emite los eventos `widget:open`, `widget:close` y `ticket:created`. Están explicados en [Eventos y callbacks](https://os.utilia.ai/docs/developers/widget/events-and-callbacks). ## Siguiente paso Adapta el aspecto del widget a tu marca con las [variables CSS](https://os.utilia.ai/docs/developers/widget/css-variables).