El widget como componente web

El widget de soporte es un componente web: una etiqueta HTML propia, <utilia-support>, 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.

Uso

La etiqueta solo existe cuando el código del widget está cargado. Impórtalo una vez en tu aplicación:

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

<utilia-support
  base-url="https://os.utilia.ai/api"
  api-key="TU_CLAVE_DE_API"
  user-id="user-123"
  user-email="ana@tuempresa.com"
  user-name="Ana García"
  position="bottom-right"
  theme="light"
></utilia-support>

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

base-urlstringobligatorio

Dirección base de la API: https://os.utilia.ai/api.

api-keystringobligatorio

Clave de API de la aplicación externa.

user-idstringobligatorio

Identificador de la persona en tu sistema.

user-emailstring

Correo de la persona.

user-namestring

Nombre de la persona.

position'bottom-right' | 'bottom-left'Por defecto: bottom-right

Esquina en la que aparece el botón.

theme'light' | 'dark' | 'auto'Por defecto: 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

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:

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: 'user-123',
  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.

Siguiente paso

Adapta el aspecto del widget a tu marca con las variables CSS.