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.
Actualizado el . 3 min de lectura
Incluido en los planes Profesional y Avanzado. Ver precios
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.
La etiqueta mínima
<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="user-123"
></script>data-utilia-widgetmarca la etiqueta: el script busca la primera que lo lleve y lee de ella la configuración.data-base-url,data-api-keyydata-user-idson obligatorios. Si falta alguno, el widget no arranca y escribe en la consola del navegador un aviso que empieza por[UtiliaWidget].data-user-ides el identificador de la persona en tu sistema. Pon el de quien ha iniciado sesión en tu web: es lo que separa los tickets de cada usuario.
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
Participan: Tu página, Widget, UTILIA OS.
De Tu página a Widget:
Carga utilia-widget.js
El script busca la etiqueta con data-utilia-widget y lee sus atributos.Nota en Widget:
Crea el elemento utilia-support al final de la página.De Widget a UTILIA OS:
POST /api/external/v1/users/identify
Da de alta o actualiza a la persona con su data-user-id.De Widget a UTILIA OS:
GET /api/external/v1/tickets/unread-count
Pide cuántos mensajes tiene sin leer.De UTILIA OS a Widget:
Número de no leídos (respuesta)
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.
Todos los atributos
- data-base-urlstringobligatorio
- Dirección base de la API:
https://os.utilia.ai/api. - data-api-keystringobligatorio
- Clave de API de la aplicación externa.
- data-user-idstringobligatorio
- Identificador de la persona en tu sistema.
- data-user-emailstring
- Correo de la persona. Se guarda al identificarla.
- data-user-namestring
- Nombre de la persona. Se guarda al identificarla.
- data-position'bottom-right' | 'bottom-left'Por defecto:
bottom-right - Esquina en la que aparece el botón.
- data-theme'light' | 'dark' | 'auto'Por defecto:
light - Aspecto del widget.
autose acepta, pero hoy se pinta igual quelight. - data-auto-context'true' | 'false'Por defecto:
true - Adjunta a cada ticket la dirección de la página y los datos del navegador. Solo se desactiva con
false.
Ejemplo completo:
<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="user-123"
data-user-email="ana@tuempresa.com"
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.
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; para adaptar los colores, las variables CSS.