Inicializa el widget de DobroDesk mediante código

Elige la instalación programática si el sitio es una aplicación

Usa el SDK programático cuando el sitio esté desarrollado como aplicación y el widget deba iniciarse después del consentimiento, la autenticación, la selección de una ruta u otro evento. La inserción estándar mediante script sigue siendo la opción más sencilla para un constructor web o un campo de código general.

Ambos métodos cargan el mismo widget alojado por DobroDesk. El SDK no crea otra implementación. Proporciona el Integration ID y la configuración regional al cargador y ofrece métodos tipados para controlar la instancia resultante.

• Usa la inserción mediante script cuando el botón de Soporte deba cargarse en todas las páginas públicas sin lógica de aplicación.
• Usa el SDK cuando la inicialización dependa del estado de la aplicación o cuando un botón personalizado deba abrir el widget.
• Inicializa el widget una sola vez por página. Conserva el cliente devuelto en vez de volver a llamar a createDobroDeskWidget.
• Ejecuta la inicialización en el navegador. El renderizado en servidor no proporciona document ni window.

Instala el paquete

Añade el paquete del widget de DobroDesk a la aplicación frontend con el gestor de paquetes que ya utilice el proyecto.

npm install @dobrodesk/widget

Inicializa una sola instancia

1. 1

   Copia el Integration ID desde Admin > Channels > Website widgets.

   

2. 2

   Importa createDobroDeskWidget en el código de la aplicación que se ejecuta en el navegador.

3. 3

   Pasa el Integration ID exacto a la opción integrationId y elige auto, en o uk.

4. 4

   Guarda el cliente devuelto y espera a client.ready antes de ejecutar lógica que dependa de que la configuración se haya cargado correctamente.

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

const supportWidget = createDobroDeskWidget({
  integrationId: "wgt_7f4c1d2e3a5b6980718293a4b5c6d7e8",
  locale: "auto",
});

await supportWidget.ready;

Usa el módulo ES alojado sin gestor de paquetes

Una aplicación de navegador compatible con módulos ES puede importar directamente el mismo SDK. Resulta útil para un sitio personalizado pequeño que utiliza módulos de JavaScript, pero no tiene un proceso de compilación con npm.

import { createDobroDeskWidget } from "https://dobrodesk.com/widget/sdk/v1.js";

const supportWidget = createDobroDeskWidget({
  integrationId: "wgt_7f4c1d2e3a5b6980718293a4b5c6d7e8",
  locale: "en",
  openOnReady: false,
});

Controla el widget desde acciones de la aplicación

Conserva el cliente en el módulo o componente que gestione la experiencia de soporte. Cuando tu propio botón de Ayuda o Soporte abra el widget, inicialízalo con launcher: hidden para que el botón estándar no aparezca a su lado. La lógica de consentimiento puede controlar la visibilidad del botón después de la inicialización. Prefill puede aportar campos que el cliente ya haya completado en la aplicación.

• open, close y toggle cambian el estado del panel.
• hide impide interactuar con el widget y show vuelve a dejarlo disponible.
• setLauncherVisibility oculta o muestra solo el botón estándar sin destruir el cliente del widget.
• prefill combina los valores proporcionados de nombre, correo, asunto, mensaje o campos personalizados configurados.
• setLocale carga en o uk y vuelve al inglés para cualquier otro idioma.
• destroy elimina de forma permanente la instancia del widget de la página actual.

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

await supportWidget.ready;

// Your application button
supportWidget.open();

// Consent or route state
supportWidget.setLauncherVisibility(false);
supportWidget.setLauncherVisibility(true);

supportWidget.close();
supportWidget.toggle();
supportWidget.hide();
supportWidget.show();

supportWidget.prefill({
  email: "customer@example.com",
  subject: "Question about order 1042",
});

supportWidget.setLocale("uk");

Identifica de forma segura a clientes autenticados con un JWT de corta duración

Usa una identidad de cliente firmada cuando la aplicación ya conozca al usuario autenticado. DobroDesk verifica el ID del cliente y, opcionalmente, el correo confirmado antes de vincular el historial o mostrar contexto de CRM. El secreto de identidad debe permanecer únicamente en el gestor de secretos del backend.

En la configuración del widget elige Require a signed logged-in user, guarda el widget y selecciona Copy identity secret. Guarda el valor como DOBRODESK_WIDGET_IDENTITY_SECRET en el backend. El Integration ID público puede aparecer en el navegador; el secreto de identidad no.

1. 1

   Instala en el backend una biblioteca JWT mantenida, como jose.

2. 2

   Firma con HS256, usa dobrodesk-widget:{Integration ID} como issuer, el Integration ID como audience y el ID interno estable del usuario como subject.

3. 3

   Usa una duración de cinco minutos y nunca superior a 15 minutos. Genera un token nuevo al cargar la página o al iniciar sesión.

4. 4

   Incluye email y email_verified: true solo si la aplicación ya ha verificado que la dirección pertenece al usuario.

5. 5

   Devuelve el token desde un endpoint autenticado del backend y pásalo como identityToken al crear el widget.

• sub es el ID estable del usuario en tu aplicación, no una dirección de correo.
• email_verified: false o un valor omitido no convierte el correo en una identidad fiable.
• Si el correo está en identityToken o prefill.email, el widget no muestra un segundo campo de correo.
• Un correo precompletado o escrito sin firma permanece sin verificar hasta que el cliente abra el enlace de confirmación de un solo uso.
• Si el inicio de sesión ocurre después, llama a setIdentityToken(token) y luego a prefill({ email, name }).
• Antes de cerrar la sesión en tu aplicación, llama a logout() para que otra persona en el navegador no herede la conversación anterior.

import { SignJWT } from "jose";

const integrationId = process.env.DOBRODESK_WIDGET_ID;
const identitySecret = new TextEncoder().encode(
  process.env.DOBRODESK_WIDGET_IDENTITY_SECRET,
);

export const createWidgetIdentityToken = (user) =>
  new SignJWT({
    name: user.name,
    email: user.email,
    email_verified: true,
  })
    .setProtectedHeader({ alg: "HS256", typ: "JWT" })
    .setIssuer(`dobrodesk-widget:${integrationId}`)
    .setAudience(integrationId)
    .setSubject(user.id)
    .setIssuedAt()
    .setExpirationTime("5m")
    .sign(identitySecret);

// Browser code after your authenticated endpoint returns the token
const supportWidget = createDobroDeskWidget({
  integrationId,
  identityToken,
  prefill: { email: currentUser.email, name: currentUser.name },
});

Comprueba la integración en la aplicación

1. 1

   Carga la ruta que inicializa el SDK y confirma que aparezca únicamente el botón de Soporte estándar o personalizado previsto.

2. 2

   Activa la acción personalizada que llama a open y comprueba que el panel se abra sin recargar la página.

3. 3

   Prueba cada campo completado previamente con un valor de muestra no sensible. No introduzcas datos de pago, contraseñas ni tokens privados en los campos del widget.

4. 4

   Alterna entre auto, en y uk y comprueba el botón, las etiquetas del formulario y las respuestas sugeridas.

5. 5

   Envía un mensaje de prueba completo y confirma que llegue a la bandeja configurada en DobroDesk.