Integra el SDK del widget web de DobroDesk

Instala el paquete publicado

El paquete para navegador está publicado en https://www.npmjs.com/package/@dobrodesk/widget/v/0.3.1. Fija la versión en tu lockfile y copia el Integration ID público en Admin > Channels > Website widgets.

npm install @dobrodesk/widget@0.3.1

Configura y presenta el widget

Después de la instalación, copia el Integration ID público en Admin > Channels > Website widgets y configura el widget desde tu aplicación.

Usa launcher: hidden cuando tu aplicación sea propietaria del botón. El launcher integrado se oculta mientras el panel está abierto y devuelve el foco al cerrarse. Omite el override de reduceMotion para que el widget siga la preferencia actual del sistema, incluidos los cambios de prefers-reduced-motion durante la sesión.

import { createDobroDeskWidget } from "@dobrodesk/widget";

const widget = createDobroDeskWidget({
  integrationId: "wgt_0123456789abcdef0123456789abcdef",
  locale: "auto",
  launcher: "hidden",
});

await widget.ready;
widget.open();

Usar un disparador propio o una superficie integrada

Usa launcher: hidden cuando tu aplicación controla el disparador. Para una superficie integrada, define un ancho y una altura estables antes del montaje para que el diseño no salte durante la carga.

El botón propio debe ser accesible con teclado y exponer aria-controls y aria-expanded. Al volver a montar, reutiliza el mismo cliente, la misma sesión y el mismo borrador.

import { createDobroDeskWidget } from "@dobrodesk/widget";

const supportSlot = document.querySelector("#support-slot");
const helpButton = document.querySelector("#help-button");
if (!(supportSlot instanceof HTMLElement) || !(helpButton instanceof HTMLButtonElement)) {
  throw new Error("Support widget host elements are missing");
}

const widget = createDobroDeskWidget({
  integrationId: "wgt_0123456789abcdef0123456789abcdef",
  launcher: "hidden",
  container: supportSlot,
});

helpButton.addEventListener("click", () => widget.toggle());
widget.onStateChange((state) => {
  helpButton.setAttribute("aria-expanded", String(state.visible));
});
await widget.ready;

Gestiona la carga y la identidad firmada

El frame del widget controla los indicadores de carga que ve el cliente. Usa onLoadingChange para el estado de la página, por ejemplo para desactivar una acción de checkout cercana. Las fases incluyen inicialización, carga de contenido y sesión, entrega de mensajes, espera del asistente, ejecución de acciones y reconexión.

Se admiten sesiones web anónimas. Para un cliente identificado, tu backend debe emitir un JWT de identidad HS256 de corta duración y el navegador puede enviarlo con el correo conocido. Nunca coloques el signing secret ni un support API token en el código del navegador. Llama a logout antes de terminar la sesión autenticada del host o de entregar el navegador a otro cliente.

const stopLoading = widget.onLoadingChange((loading) => {
  checkoutButton.disabled = loading.active;
});

// The token is returned by your backend. This function belongs to your app.
widget.setIdentityToken(await loadIdentityTokenFromYourBackend());
widget.prefill({ email: currentUser.email, name: currentUser.name });

Gestionar carga, visibilidad y accesibilidad

Usa los hooks de carga o los eventos tipados para el estado de la pantalla anfitriona. La superficie muestra por sí misma la carga de mensajes, la espera y los reintentos para evitar un segundo spinner sobre el campo de entrada.

Oculta o muestra la superficie cuando una ruta cambia temporalmente y conserva el cliente. El widget respeta las preferencias del sistema para reducir movimiento. Quitar o cerrar la vista no descarta la sesión ni el borrador.

1. Al volver a montar, reutiliza el mismo cliente y dimensiones estables del contenedor.
2. Usa la función de visibilidad para ocultar temporalmente, no una función de reinicio de sesión.
3. Finaliza la sesión solo al cerrar sesión o cambiar de cuenta de forma intencionada.

Verifica la integración

1. Abre la página desde un origin permitido y comprueba que el panel se abre una sola vez y que el launcher oculto permanece oculto.
2. Envía un mensaje de prueba desde una sesión privada del navegador y confirma que llega al Inbox configurado sin crear una segunda conversación.
3. Desactiva brevemente la red y espera el estado de reconexión del widget. Deja que el frame reintente su operación pendiente. No envíes el mismo mensaje desde otro control mientras la primera solicitud no tenga resultado.
4. Cambia la preferencia del sistema para reducir movimiento con el widget abierto y confirma que las transiciones posteriores respetan la nueva preferencia.