Widget por npm y React

El widget de soporte también se distribuye como paquete npm, @utilia-os/widget. Es la vía adecuada si tu web es una aplicación de página única o usa un empaquetador (Vite, webpack) o un framework como React, Vue o Svelte: lo inicializas desde tu código, lo abres desde tus propios botones y te enteras de cada ticket creado.

Si solo necesitas pegar un fragmento en el HTML, la etiqueta de script es más sencilla. En ambos casos, prepara antes la aplicación externa, su clave y tus dominios autorizados como se explica en la visión general.

Instalación

npm install @utilia-os/widget

El paquete trae sus propios tipos de TypeScript e incluye dentro el SDK de JavaScript, así que no tienes que instalar nada más. Al importarlo se registra el componente web utilia-support; funciona en cualquier navegador actual con soporte de componentes web.

Uso básico

initUtiliaWidget busca el elemento <utilia-support> en la página; si no existe, lo crea y lo añade al final del body. Después lo configura y te devuelve la instancia para controlarlo.

import { initUtiliaWidget } from '@utilia-os/widget';
 
const widget = initUtiliaWidget({
  baseURL: 'https://os.utilia.ai/api',
  apiKey: 'TU_CLAVE_DE_API',
  userId: 'user-123',
});
 
widget.open();

La clave de API viaja en el navegador y cualquiera puede leerla: usa una aplicación externa dedicada al widget, con los scopes mínimos y tus dominios autorizados, como se explica en la visión general.

Opciones de configuración

Solo baseURL, apiKey y userId son obligatorias.

Fíjate en autoContext: por npm está desactivado si no lo pones, mientras que con la etiqueta de script está activado salvo que escribas false.

Integración con React

En React, el widget sigue la vida del componente que lo monta:

import { useEffect, useRef, useState } from 'react';
import { initUtiliaWidget } from '@utilia-os/widget';
 
export function SoporteWidget({ usuario }: { usuario: { id: string; email: string; nombre: string } }) {
  const widgetRef = useRef<ReturnType<typeof initUtiliaWidget> | null>(null);
  const [ultimoTicket, setUltimoTicket] = useState<string | null>(null);
 
  useEffect(() => {
    const widget = initUtiliaWidget({
      baseURL: 'https://os.utilia.ai/api',
      apiKey: import.meta.env.VITE_UTILIA_API_KEY,
      userId: usuario.id,
      userEmail: usuario.email,
      userName: usuario.nombre,
      autoContext: true,
      onTicketCreated: (ticket) => setUltimoTicket(ticket.ticketKey),
      onError: (error) => console.error('Widget de soporte:', error),
    });
 
    widgetRef.current = widget;
 
    // Al desmontar, el widget sale de la página.
    return () => {
      widget.remove();
      widgetRef.current = null;
    };
  }, [usuario.id, usuario.email, usuario.nombre]);
 
  return (
    <div>
      <button onClick={() => widgetRef.current?.open()}>Abrir soporte</button>
      <button onClick={() => widgetRef.current?.showNewTicketForm()}>Informar de un problema</button>
      {ultimoTicket && <p>Último ticket creado: {ultimoTicket}</p>}
    </div>
  );
}

Cada llamada a initUtiliaWidget vuelve a identificar al usuario y a pedir el contador de no leídos, y ambas peticiones cuentan para el límite de la clave. Por eso el efecto depende solo de los datos del usuario: si cambian, el widget se reconfigura; si no, se queda como está.

Métodos de la instancia

La instancia es el propio elemento <utilia-support>, así que también puedes escuchar sus eventos con addEventListener. Están explicados en Eventos y callbacks.

Siguiente paso

• Eventos y callbacksReacciona a la creación de tickets y a la apertura o cierre del widget.
• Variables CSSAdapta los colores y el radio de las esquinas a tu marca.
• Problemas frecuentesQué revisar si el widget no aparece o da errores.