Controla Notiondesk Messenger con el SDK de JavaScript

El SDK de JavaScript de Messenger Notiondesk te permite integrar Messenger directamente con la interfaz y el estado de tu aplicación.

Puede:

• Abre y cierra Messenger desde tu propia interfaz de usuario.

• Dirija a los visitantes directamente a Ayuda, Mensajes, Contacto o Registro de cambios

• Crea tu propio lanzador de Messenger

• Reacciona a los eventos de Messenger

• Sincroniza Messenger con el tema y el idioma de tu aplicación.

• Actualizar usuarios autenticados sin recargar la página.

• Cambiar la posición y el apilamiento en tiempo de ejecución.

• Integrar Messenger con el estado de la aplicación React y Vue

• Desinstale y vuelva a inicializar Messenger cuando sea necesario.

Utilice el SDK para aplicaciones que necesiten un mayor control que el que ofrece el fragmento de instalación estándar de Messenger.

Instale el SDK

Instale el paquete oficial:

También puedes usar hilo:

O pnpm:

Inicializar Messenger

Importa initNotiondesk() y proporciona tu ID de Messenger:

initNotiondesk() se resuelve cuando Messenger está listo para usarse, por lo que el patrón más seguro es esperar a la inicialización antes de llamar a los métodos del SDK:

Notiondesk Messenger debe inicializarse en el navegador. No lo inicialice durante la renderización del lado del servidor.

Para la instalación de React y Next.js, consulte Cómo instalar Notiondesk Messenger con React y Next.js.

Abrir, cerrar y alternar Messenger

Mensajero abierto

Utilice show():

Por ejemplo:

Mensajero cercano

Utilice hide():

Alternar Messenger

Usa toggle() para abrir Messenger cuando esté cerrado y cerrarlo cuando esté abierto:

toggle() es particularmente útil cuando su aplicación proporciona su propio botón de Messenger.

Abrir una sección específica de Messenger

Utilice showTab() para abrir Messenger directamente en un módulo específico:

Las pestañas disponibles son:

npm install @notiondesk-so/messenger-js-sdk

yarn add @notiondesk-so/messenger-js-sdk

pnpm add @notiondesk-so/messenger-js-sdk

import { initNotiondesk } from "@notiondesk-so/messenger-js-sdk";

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
});

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
});

await notiondesk.show();

await notiondesk.show();

document.querySelector("#support")?.addEventListener("click", () => {
  void notiondesk.show();
});

await notiondesk.hide();

await notiondesk.toggle();

notiondesk.showTab("help");

Por ejemplo:

showTab() también abre Messenger si está cerrado.

El módulo solicitado debe estar habilitado en la configuración de Messenger. Por ejemplo, showTab("changelog") no cambiará al registro de cambios si el módulo de registro de cambios está deshabilitado.

Esto permite conectar diferentes partes de la interfaz de tu aplicación con diferentes experiencias de soporte.

Por ejemplo:

helpButton.addEventListener("click", () => {
  notiondesk.showTab("help");
});

updatesButton.addEventListener("click", () => {
  notiondesk.showTab("changelog");
});

contactButton.addEventListener("click", () => {
  notiondesk.showTab("contact");
});

• Centro de ayuda → showTab("help")

• Preguntar a la IA → __PRESERVADO_112__

• Contacta con soporte → showTab("contact")

• Novedades → __PRESERVADO_110__

Usa tu propio botón de Messenger

No es necesario utilizar el lanzador predeterminado Notiondesk.

Desactiva la opción "Mostrar lanzador" en la configuración de Messenger y, a continuación, utiliza el SDK para abrir Messenger desde tu propia interfaz.

Por ejemplo:

Esto resulta útil cuando se debe integrar la asistencia en una barra de navegación, menú de cuenta, panel de control, botón flotante o interfaz de aplicación ya existente.

Cuando utilice un lanzador personalizado, prefiera toggle() si el mismo control debe abrir y cerrar Messenger.

Escucha los eventos de Messenger

El SDK expone eventos a través de on() y off().

Por ejemplo:

on() devuelve una función para cancelar la suscripción:

Eventos de Messenger disponibles

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
});

document.querySelector("#help")?.addEventListener("click", () => {
  void notiondesk.toggle();
});

notiondesk.on("messenger:show", () => {
  console.log("Messenger opened");
});

notiondesk.on("messenger:hide", () => {
  console.log("Messenger closed");
});

const unsubscribe = notiondesk.on("messenger:show", () => {
  console.log("Messenger opened");
});

// Later
unsubscribe();

Rastrea qué sección de Messenger utilizan los visitantes.

El evento messenger:tabChanged incluye la pestaña actual y la anterior.

Por ejemplo, puedes reenviar la actividad de Messenger a tu plataforma de análisis:

Mantén sincronizado tu propio lanzador.

Los eventos también pueden sincronizar tu interfaz de usuario con el estado de Messenger:

Cambiar el tema de Messenger

Usa setTheme() para alternar entre el modo claro y el oscuro sin recargar Messenger:

O:

Por ejemplo, sincroniza Messenger con el tema de tu aplicación:

También puedes reaccionar a los cambios de tema del sistema operativo:

Utiliza el panel de control Notiondesk para configurar los colores, las fuentes, la apariencia del lanzador y otros ajustes de marca de Messenger. El control de temas del SDK sirve para cambiar el esquema de color activo.

Cambiar el idioma de Messenger

Utilice setLanguage():

Esto resulta útil cuando su aplicación ya tiene su propio selector de idioma:

La configuración regional solicitada debe estar habilitada para su Messenger en Notiondesk.

Si la configuración regional no está habilitada, Messenger mantendrá un idioma configurado disponible en su lugar.

Actualizar Messenger después de la inicialización

Utilice updateConfig() cuando el estado de la aplicación cambie después de que Messenger ya se haya cargado.

notiondesk.on(
  "messenger:tabChanged",
  ({ tabName, previousTab }) => {
    console.log("Messenger tab:", tabName);
  },
);

notiondesk.on("messenger:show", () => {
  analytics.track("support_opened");
});

notiondesk.on("messenger:tabChanged", ({ tabName }) => {
  analytics.track("support_tab_opened", {
    tab: tabName,
  });
});

notiondesk.on("messenger:show", () => {
  helpButton.setAttribute("aria-expanded", "true");
});

notiondesk.on("messenger:hide", () => {
  helpButton.setAttribute("aria-expanded", "false");
});

notiondesk.setTheme("dark");

notiondesk.setTheme("light");

notiondesk.setTheme(
  isDarkMode ? "dark" : "light",
);

const colorScheme = window.matchMedia(
  "(prefers-color-scheme: dark)",
);

function syncMessengerTheme() {
  notiondesk.setTheme(
    colorScheme.matches ? "dark" : "light",
  );
}

syncMessengerTheme();

colorScheme.addEventListener(
  "change",
  syncMessengerTheme,
);

notiondesk.setLanguage("fr");

notiondesk.setLanguage(currentLocale);

Actualizar un usuario autenticado

Después de que un usuario inicia sesión:

Messenger actualiza al usuario actual sin necesidad de recargar la página.

Volver a un usuario anónimo

Cuando un usuario cierra sesión:

Para conocer el flujo de autenticación completo, consulte Identificar usuarios que han iniciado sesión en Notiondesk Messenger .

Cambiar la posición del mensajero

Puedes mover Messenger en tiempo de ejecución:

Los puestos que admiten son:

notiondesk.updateConfig({
  userToken,
});

notiondesk.updateConfig({
  userToken: null,
});

notiondesk.updateConfig({
  position: "bottom-left",
});

• bottom-right

• bottom-left

La posición predeterminada del lanzador normalmente debería configurarse en el panel de control Notiondesk. Utilice updateConfig() cuando su aplicación necesite una anulación temporal en tiempo de ejecución.

Por ejemplo, podrías mover Messenger cuando otro elemento flotante ocupe la misma esquina.

Cambiar el nivel de apilamiento

Si Messenger necesita aparecer encima de otro elemento de la aplicación:

Utiliza Messenger con usuarios autenticados

Al inicializar Messenger, pase un token de usuario firmado:

También puedes empezar de forma anónima e identificar al usuario más tarde:

El token debe ser generado por tu backend.

Nunca expongas tu secreto de aplicación Notiondesk en el código del navegador.

Consulte Identificar usuarios conectados en Messenger para conocer el flujo completo de autenticación y cierre de sesión.

Eliminar Messenger

Utilice destroy() para eliminar completamente la instancia actual de Messenger:

Utilice destroy() cuando:

notiondesk.updateConfig({
  zIndex: 10000,
});

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
  userToken,
});

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
});

notiondesk.updateConfig({
  userToken,
});

notiondesk.destroy();

• Messenger ya no debería existir en la página actual.

• Se está cambiando una cuenta de usuario.

• Tu aplicación está desmontando la integración de Messenger.

• Necesitas iniciar una nueva sesión de Messenger.

Puedes volver a inicializar Messenger después de destruirlo.

Cargar Messenger sin inicializarlo

Para aplicaciones que necesitan más control sobre la inicialización, utilice loadNotiondesk():

La mayoría de las aplicaciones deberían usar initNotiondesk() en su lugar.

loadNotiondesk() es útil cuando la carga del SDK de Messenger y el inicio del propio Messenger deben ocurrir en diferentes momentos del ciclo de vida de su aplicación.

Acceda a una API de Messenger ya cargada

Utilice getNotiondesk() para acceder de forma síncrona a la API cuando Messenger ya se haya cargado:

Si Messenger aún no se ha cargado, getNotiondesk() devuelve null.

Para la inicialización normal de la aplicación, prefiera initNotiondesk().

Controles y estado de React

Las aplicaciones React deberían usar:

useNotiondesk() proporciona tanto los controles de Messenger como su estado de carga actual.

Por ejemplo:

Los valores disponibles incluyen:

import {
  loadNotiondesk,
} from "@notiondesk-so/messenger-js-sdk";

const notiondesk = await loadNotiondesk();

await notiondesk.init({
  messengerId: "YOUR_MESSENGER_ID",
});

import {
  getNotiondesk,
} from "@notiondesk-so/messenger-js-sdk";

getNotiondesk()?.show();

import {
  NotiondeskProvider,
  useNotiondesk,
} from "@notiondesk-so/messenger-js-sdk/react";

function SupportButton() {
  const {
    show,
    status,
  } = useNotiondesk();

  return (
    <button
      disabled={status !== "ready"}
      onClick={() => void show()}
    >
      Contact support
    </button>
  );
}

Utilice api cuando necesite API como suscripciones a eventos:

Mantén estables las propiedades de configuración, como el tema y la configuración regional, en NotiondeskProvider siempre que sea posible.

Para cambios en tiempo de ejecución, prefiera setTheme(), setLanguage() o updateConfig() en lugar de cambiar repetidamente la configuración del proveedor.

Vue controla y el estado

Las aplicaciones Vue pueden acceder a Messenger mediante:

Por ejemplo:

La integración con Vue también expone la API de Messenger, el estado, los errores y los mismos controles de tiempo de ejecución que el SDK principal.

Recetas comunes del SDK

Crear un botón de Ayuda personalizado

Desactiva el lanzador predeterminado en la configuración de tu Messenger:

Abra su centro de ayuda directamente.

Abre tu asistente de IA directamente

El módulo Mensajes debe estar habilitado y configurado en Messenger.

Abre tu formulario de contacto directamente.

Abre el registro de cambios desde un enlace de “Novedades”.

Ocultar Messenger en una ruta de aplicación específica

Mueva Messenger lejos de otro elemento flotante.

Seguimiento del uso de Messenger

Actualizar Messenger después de iniciar sesión.

Borrar el usuario después de cerrar sesión.

Solución de problemas

import { useEffect } from "react";
import { useNotiondesk } from "@notiondesk-so/messenger-js-sdk/react";

function MessengerAnalytics() {
  const { api } = useNotiondesk();

  useEffect(() => {
    if (!api) {
      return;
    }

    return api.on("messenger:show", () => {
      analytics.track("support_opened");
    });
  }, [api]);

  return null;
}

import {
  useNotiondesk,
} from "@notiondesk-so/messenger-js-sdk/vue";

<script setup lang="ts">
import {
  useNotiondesk,
} from "@notiondesk-so/messenger-js-sdk/vue";

const {
  show,
  showTab,
  isReady,
} = useNotiondesk();
</script>

<template>
  <button
    :disabled="!isReady"
    @click="show()"
  >
    Contact support
  </button>

  <button @click="showTab('changelog')">
    What's new
  </button>
</template>

helpButton.addEventListener("click", () => {
  void notiondesk.toggle();
});

notiondesk.showTab("help");

notiondesk.showTab("messages");

notiondesk.showTab("contact");

notiondesk.showTab("changelog");

if (window.location.pathname.startsWith("/checkout")) {
  await notiondesk.hide();
}

notiondesk.updateConfig({
  position: "bottom-left",
});

notiondesk.on("messenger:show", () => {
  analytics.track("support_opened");
});

notiondesk.on("messenger:tabChanged", ({ tabName }) => {
  analytics.track("support_section_opened", {
    section: tabName,
  });
});

notiondesk.updateConfig({
  userToken,
});

notiondesk.updateConfig({
  userToken: null,
});

try {
  const notiondesk = await initNotiondesk({
    messengerId: "YOUR_MESSENGER_ID",
  });
} catch (error) {
  console.error(
    "Could not initialize Notiondesk Messenger",
    error,
  );
}

notiondesk.updateConfig({
  zIndex: 10000,
});

notiondesk.updateConfig({
  userToken: null,
});

notiondesk.destroy();

const { show, status } = useNotiondesk();

return (
  <button
    disabled={status !== "ready"}
    onClick={() => void show()}
  >
    Contact support
  </button>
);