Contrôlez Messenger Notiondesk avec le SDK JavaScript

Le SDK JavaScript Messenger Notiondesk vous permet d'intégrer Messenger directement à l'interface et à l'état de votre application.

Tu peux:

• Ouvrez et fermez Messenger depuis votre propre interface utilisateur.

• Dirigez les visiteurs directement vers l'aide, les messages, le contact ou le journal des modifications.

• Créez votre propre lanceur Messenger

• Réagir aux événements Messenger

• Synchronisez Messenger avec le thème et la langue de votre application.

• Mise à jour des utilisateurs authentifiés sans recharger la page

• Modifier la position et l'empilement en cours d'exécution

• Intégrer Messenger à l'état de l'application React et Vue

• Supprimez et réinitialisez Messenger si nécessaire.

Utilisez le SDK pour les applications qui nécessitent un contrôle plus poussé que celui fourni par l'extrait de code d'installation standard de Messenger.

Installez le SDK

Installez le package officiel :

Vous pouvez également utiliser du fil :

Ou pnpm :

Initialiser Messenger

Importez initNotiondesk() et indiquez votre identifiant Messenger :

initNotiondesk() est résolu lorsque Messenger est prêt à être utilisé ; le modèle le plus sûr consiste donc à attendre l’initialisation avant d’appeler les méthodes du SDK :

Notiondesk Messenger doit être initialisé dans le navigateur. Ne l'initialisez pas lors du rendu côté serveur.

Pour l'installation de React et Next.js, consultez Comment installer Notiondesk Messenger avec React et Next.js.

Ouvrir, fermer et activer/désactiver Messenger

Ouvrir Messenger

Utilisez show():

Par exemple:

Fermer Messenger

Utilisez hide():

Basculer Messenger

Utilisez toggle() pour ouvrir Messenger lorsqu'il est fermé et pour le fermer lorsqu'il est ouvert :

toggle() est particulièrement utile lorsque votre application fournit son propre bouton Messenger.

Ouvrir une section spécifique de Messenger

Utilisez showTab() pour ouvrir Messenger directement sur un module spécifique :

Les onglets disponibles sont :

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");

Par exemple:

showTab() ouvre également Messenger s'il est actuellement fermé.

Le module demandé doit être activé dans votre configuration Messenger. Par exemple, showTab("changelog") ne basculera pas vers le journal des modifications si le module Journal des modifications est désactivé.

Cela permet de connecter différentes parties de l'interface de votre application à différentes expériences d'assistance.

Par exemple:

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

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

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

• Centre d'aide → showTab("help")

• Demandez à l'IA → showTab("messages")

• Contacter l'assistance → showTab("contact")

• Nouveautés → showTab("changelog")

Utilisez votre propre bouton Messenger

Vous n'êtes pas obligé d'utiliser le lanceur par défaut Notiondesk.

Désactivez l' option « Afficher le lanceur » dans les paramètres de Messenger, puis utilisez le SDK pour ouvrir Messenger depuis votre propre interface.

Par exemple:

Ceci est utile lorsque l'assistance doit être intégrée à une barre de navigation existante, un menu de compte, un tableau de bord, un bouton flottant ou l'interface de l'application.

Lors de l'utilisation d'un lanceur personnalisé, privilégiez toggle() si la même commande doit à la fois ouvrir et fermer Messenger.

Écoutez les événements Messenger

Le SDK expose les événements via on() et off().

Par exemple:

on() renvoie une fonction de désabonnement :

Événements 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();

Suivez les sections Messenger utilisées par les visiteurs.

L'événement messenger:tabChanged inclut l'onglet actuel et l'onglet précédent.

Par exemple, vous pouvez transférer l'activité de Messenger vers votre plateforme d'analyse :

Gardez votre propre lanceur synchronisé

Les événements peuvent également synchroniser votre interface utilisateur avec l'état de Messenger :

Changer le thème de Messenger

Utilisez setTheme() pour basculer entre le mode clair et le mode sombre sans recharger Messenger :

Ou:

Par exemple, synchronisez Messenger avec le thème de votre application :

Vous pouvez également réagir aux changements de thème du système d'exploitation :

Utilisez le tableau de bord Notiondesk pour gérer les couleurs, les polices, l'apparence du lanceur et autres paramètres de marque de Messenger. Le contrôle du thème du SDK permet de changer le schéma de couleurs actif.

Changer la langue de Messenger

Utilisez setLanguage():

Ceci est utile lorsque votre application possède déjà son propre sélecteur de langue :

La langue demandée doit être activée pour votre Messenger dans Notiondesk.

Si la langue locale n'est pas activée, Messenger conserve une langue configurée disponible.

Mettre à jour Messenger après l'initialisation

Utilisez updateConfig() lorsque l'état de l'application change après que Messenger ait déjà été chargé.

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);

Mettre à jour un utilisateur authentifié

Après la connexion de l'utilisateur :

Messenger met à jour les informations de l'utilisateur actuel sans nécessiter de rechargement de la page.

Retour à un utilisateur anonyme

Lorsqu'un utilisateur se déconnecte :

Pour connaître le flux d'authentification complet, consultez la section « Identifier les utilisateurs connectés dans Messenger » .

Modifier la position du messager

Vous pouvez déplacer Messenger en cours d'exécution :

Les postes pris en charge sont :

notiondesk.updateConfig({
  userToken,
});

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

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

• bottom-right

• bottom-left

Normalement, la position de lancement par défaut se configure dans le tableau de bord Notiondesk. Utilisez updateConfig() lorsque votre application nécessite une substitution d'exécution temporaire.

Par exemple, vous pouvez déplacer Messenger lorsqu'un autre élément flottant occupe le même coin.

Modifier le niveau d'empilement

Si Messenger doit apparaître au-dessus d'un autre élément de l'application :

Utilisez Messenger avec des utilisateurs authentifiés

Transmettez un jeton d'utilisateur signé lors de l'initialisation de Messenger :

Vous pouvez également commencer anonymement et identifier l'utilisateur ultérieurement :

Le jeton doit être généré par votre serveur.

Ne jamais exposer votre secret d'application Notiondesk dans le code du navigateur.

Consultez la section « Identifier les utilisateurs connectés dans Notiondesk Messenger » pour connaître le flux complet d’authentification et de déconnexion.

Supprimer Messenger

Utilisez destroy() pour supprimer complètement l'instance Messenger actuelle :

Utilisez destroy() lorsque :

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 ne devrait plus figurer sur la page actuelle.

• Un compte utilisateur est en cours de changement.

• Votre application désactive l'intégration Messenger

• Vous devez initialiser une nouvelle session Messenger

Vous pouvez réinitialiser Messenger après l'avoir supprimé.

Charger Messenger sans l'initialiser

Pour les applications qui nécessitent un contrôle plus précis de l'initialisation, utilisez loadNotiondesk() :

La plupart des applications devraient utiliser initNotiondesk() à la place.

loadNotiondesk() est utile lorsque le chargement du SDK Messenger et le démarrage de Messenger lui-même doivent avoir lieu à différents moments du cycle de vie de votre application.

Accédez à une API Messenger déjà chargée

Utilisez getNotiondesk() pour accéder de manière synchrone à l'API lorsque Messenger a déjà été chargé :

Si Messenger n'a pas encore été chargé, getNotiondesk() renvoie null.

Pour une initialisation normale de l'application, préférez initNotiondesk().

Contrôles et état React

Les applications React doivent utiliser :

useNotiondesk() fournit à la fois les commandes Messenger et son état de chargement actuel.

Par exemple:

Les valeurs disponibles sont les suivantes :

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>
  );
}

Utilisez api lorsque vous avez besoin d'API telles que les abonnements à des événements :

Gardez les propriétés de configuration telles que le thème et les paramètres régionaux stables sur NotiondeskProvider lorsque cela est possible.

Pour les modifications en cours d'exécution, préférez setTheme(), setLanguage() ou updateConfig() plutôt que de modifier à plusieurs reprises la configuration du fournisseur.

Contrôles et état de Vue

Les applications Vue peuvent accéder à Messenger via :

Par exemple:

L'intégration Vue expose également l'API Messenger, le statut, les erreurs et les mêmes contrôles d'exécution que le SDK principal.

Recettes courantes du SDK

Créer un bouton d'aide personnalisé

Désactivez le lanceur par défaut dans vos paramètres Messenger :

Ouvrez directement votre centre d'aide.

Ouvrez directement votre assistant IA

Le module Messages doit être activé et configuré dans Messenger.

Ouvrez directement votre formulaire de contact.

Ouvrez votre journal des modifications à partir d'un lien « Nouveautés ».

Masquer Messenger sur une route d'application spécifique

Éloignez Messenger d'un autre élément flottant

Suivre l'utilisation de Messenger

Mettre à jour Messenger après la connexion

Effacer l'utilisateur après la déconnexion

Dépannage

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>
);