Steuern Sie Notiondesk Messenger mit dem JavaScript SDK

Mit dem Messenger JavaScript SDK können Sie Messenger direkt in die Benutzeroberfläche und den Status Ihrer Anwendung integrieren.

Du kannst:

• Messenger über Ihre eigene Benutzeroberfläche öffnen und schließen.

• Leiten Sie Besucher direkt zu Hilfe, Nachrichten, Kontakt oder Änderungsprotokoll weiter.

• Erstelle deinen eigenen Messenger-Launcher

• Auf Messenger-Ereignisse reagieren

• Synchronisieren Sie Messenger mit dem Design und der Sprache Ihrer Anwendung.

• Authentifizierte Benutzer aktualisieren, ohne die Seite neu zu laden

• Position und Stapelung zur Laufzeit ändern

• Messenger in den Anwendungsstatus von React und Vue integrieren

• Messenger bei Bedarf entfernen und neu initialisieren.

Verwenden Sie das SDK für Anwendungen, die mehr Kontrolle benötigen, als der Standard-Messenger-Installationscode bietet.

Installieren Sie das SDK

Installieren Sie das offizielle Paket:

Sie können auch Yarn verwenden:

Oder pnpm:

Messenger initialisieren

Importieren Sie initNotiondesk() und geben Sie Ihre Messenger-ID an:

initNotiondesk() wird aufgelöst, wenn Messenger einsatzbereit ist. Daher ist es am sichersten, die Initialisierung abzuwarten, bevor SDK-Methoden aufgerufen werden:

Notiondesk Messenger muss im Browser initialisiert werden. Initialisieren Sie ihn nicht während des serverseitigen Renderings.

Für die Installation von React und Next.js siehe Anleitung zur Installation von Notiondesk Messenger mit React und Next.js.

Messenger öffnen, schließen und umschalten

Messenger öffnen

Verwenden Sie show():

Zum Beispiel:

Messenger schließen

Verwenden Sie hide():

Messenger umschalten

Verwenden Sie toggle(), um Messenger zu öffnen, wenn er geschlossen ist, und um ihn zu schließen, wenn er geöffnet ist:

toggle() ist besonders nützlich, wenn Ihre Anwendung über eine eigene Messenger-Schaltfläche verfügt.

Öffnen Sie einen bestimmten Messenger-Bereich

Verwenden Sie showTab(), um Messenger direkt in einem bestimmten Modul zu öffnen:

Folgende Registerkarten stehen zur Verfügung:

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

Zum Beispiel:

showTab() öffnet auch Messenger, falls dieser gerade geschlossen ist.

Das angeforderte Modul muss in Ihrer Messenger-Konfiguration aktiviert sein. Beispielsweise wechselt showTab("changelog") nicht zum Changelog, wenn das Changelog-Modul deaktiviert ist.

Dadurch wird es möglich, verschiedene Teile der Benutzeroberfläche Ihrer Anwendung mit unterschiedlichen Support-Erlebnissen zu verbinden.

Zum Beispiel:

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

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

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

• Hilfezentrum → showTab("help")

• Frag die KI → showTab("messages")

• Support kontaktieren → showTab("contact")

• Was ist neu? → showTab("changelog")

Verwenden Sie Ihre eigene Messenger-Schaltfläche

Sie müssen nicht den Standard-Launcher Notiondesk verwenden.

Deaktivieren Sie in den Messenger-Einstellungen die Option „Launcher anzeigen“ und verwenden Sie anschließend das SDK, um Messenger über Ihre eigene Benutzeroberfläche zu öffnen.

Zum Beispiel:

Dies ist nützlich, wenn die Unterstützung in eine bestehende Navigationsleiste, ein Kontomenü, ein Dashboard, einen schwebenden Button oder eine Anwendungsshell integriert werden soll.

Bei Verwendung eines benutzerdefinierten Launchers ist toggle() vorzuziehen, wenn dasselbe Steuerelement sowohl Messenger öffnen als auch schließen soll.

Messenger-Ereignisse anhören

Das SDK stellt Ereignisse über on() und off() bereit.

Zum Beispiel:

on() gibt eine Abmeldefunktion zurück:

Verfügbare Messenger-Ereignisse

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

Verfolgen Sie, welchen Messenger-Bereich die Besucher nutzen.

Das messenger:tabChanged-Ereignis umfasst den aktuellen und den vorherigen Tab.

Sie können beispielsweise Messenger-Aktivitäten an Ihre Analyseplattform weiterleiten:

Halten Sie Ihren eigenen Launcher synchronisiert

Ereignisse können auch Ihre Benutzeroberfläche mit dem Messenger-Status synchronisieren:

Ändern Sie das Messenger-Design

Verwenden Sie setTheme(), um zwischen hellem und dunklem Modus zu wechseln, ohne Messenger neu zu laden:

Oder:

Synchronisieren Sie beispielsweise Messenger mit dem Design Ihrer Anwendung:

Sie können auch auf Änderungen des Betriebssystemdesigns reagieren:

Über das Dashboard Notiondesk können Sie die Farben, Schriftarten, das Erscheinungsbild des Launchers und weitere Markeneinstellungen Ihres Messengers anpassen. Die SDK-Designsteuerung dient zum Umschalten des aktiven Farbschemas.

Ändern Sie die Messenger-Sprache

Verwenden Sie setLanguage():

Dies ist nützlich, wenn Ihre Anwendung bereits über eine eigene Sprachauswahl verfügt:

Die angeforderte Gebietsschemaeinstellung muss für Ihren Messenger in Notiondesk aktiviert sein.

Wenn die Gebietsschemaeinstellung nicht aktiviert ist, verwendet Messenger stattdessen eine verfügbare, konfigurierte Sprache.

Messenger nach der Initialisierung aktualisieren

Verwenden Sie updateConfig(), wenn sich der Anwendungsstatus ändert, nachdem Messenger bereits geladen wurde.

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

Aktualisieren Sie einen authentifizierten Benutzer

Nach der Anmeldung eines Benutzers:

Messenger aktualisiert den aktuellen Benutzer, ohne dass ein Neuladen der Seite erforderlich ist.

Zurück zu einem anonymen Benutzer

Wenn sich ein Benutzer abmeldet:

Den vollständigen Authentifizierungsablauf finden Sie unter „Angemeldete Benutzer in Notiondesk Messenger identifizieren“ .

Ändern Sie die Messenger-Position

Sie können Messenger zur Laufzeit verschieben:

Unterstützte Positionen sind:

notiondesk.updateConfig({
  userToken,
});

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

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

• bottom-right

• bottom-left

Die Standardposition für den Launcher sollte normalerweise im Dashboard Notiondesk konfiguriert werden. Verwenden Sie updateConfig(), wenn Ihre Anwendung eine temporäre Laufzeitüberschreibung benötigt.

Beispielsweise könnten Sie Messenger verschieben, wenn sich ein anderes schwebendes Element in derselben Ecke befindet.

Ändern Sie die Stapelebene

Falls Messenger über einem anderen Anwendungselement angezeigt werden soll:

Messenger mit authentifizierten Benutzern verwenden

Übergeben Sie beim Initialisieren von Messenger ein signiertes Benutzertoken:

Sie können auch anonym beginnen und den Nutzer später identifizieren:

Das Token muss von Ihrem Backend generiert werden.

Geben Sie Ihr Notiondesk App-Geheimnis niemals im Browsercode preis.

Den vollständigen Authentifizierungs- und Abmeldevorgang finden Sie unter „Angemeldete Benutzer in Notiondesk Messenger identifizieren“ .

Messenger entfernen

Verwenden Sie destroy(), um die aktuelle Messenger-Instanz vollständig zu entfernen:

Verwenden Sie destroy(), wenn:

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 sollte auf der aktuellen Seite nicht mehr vorhanden sein.

• Ein Benutzerkonto wird umgeschaltet

• Ihre Anwendung trennt die Messenger-Integration.

• Sie müssen eine neue Messenger-Sitzung initialisieren.

Messenger kann nach der Zerstörung erneut initialisiert werden.

Messenger laden, ohne ihn zu initialisieren

Für Anwendungen, die mehr Kontrolle über die Initialisierung benötigen, verwenden Sie loadNotiondesk():

Die meisten Anwendungen sollten stattdessen initNotiondesk() verwenden.

loadNotiondesk() ist nützlich, wenn das Laden des Messenger SDK und das Starten des Messengers selbst zu unterschiedlichen Zeitpunkten im Lebenszyklus Ihrer Anwendung erfolgen müssen.

Greifen Sie auf eine bereits geladene Messenger-API zu.

Verwenden Sie getNotiondesk(), um synchron auf die API zuzugreifen, wenn Messenger bereits geladen wurde:

Falls Messenger noch nicht geladen wurde, gibt getNotiondesk() null zurück.

Für die normale Anwendungsinitialisierung ist initNotiondesk() vorzuziehen.

React-Steuerelemente und -Zustand

React-Anwendungen sollten Folgendes verwenden:

useNotiondesk() stellt sowohl die Messenger-Steuerelemente als auch den aktuellen Ladestatus bereit.

Zum Beispiel:

Verfügbare Werte sind:

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

Verwenden Sie api, wenn Sie APIs wie Ereignisabonnements benötigen:

Konfigurationseigenschaften wie Theme und Locale sollten nach Möglichkeit auf NotiondeskProvider stabil gehalten werden.

Bei Änderungen zur Laufzeit sollten Sie setTheme(), setLanguage() oder updateConfig() bevorzugen, anstatt die Provider-Konfiguration wiederholt zu ändern.

Vue-Steuerelemente und Status

Vue-Anwendungen können über Folgendes auf Messenger zugreifen:

Zum Beispiel:

Die Vue-Integration stellt außerdem die Messenger-API, Statusinformationen, Fehlerinformationen und die gleichen Laufzeitsteuerungen wie das Kern-SDK bereit.

Häufige SDK-Rezepte

Erstellen Sie eine benutzerdefinierte Hilfeschaltfläche

Deaktivieren Sie den Standard-Launcher in Ihren Messenger-Einstellungen:

Öffnen Sie direkt Ihr Hilfecenter.

Öffnen Sie Ihren KI-Assistenten direkt

Das Nachrichtenmodul muss in Messenger aktiviert und konfiguriert sein.

Öffnen Sie direkt Ihr Kontaktformular.

Öffnen Sie das Änderungsprotokoll über den Link „Neuigkeiten“.

Messenger auf einer bestimmten Anwendungsroute ausblenden

Bewege Messenger von einem anderen schwebenden Element weg.

Messenger-Nutzung verfolgen

Messenger nach dem Einloggen aktualisieren

Benutzer nach Abmeldung löschen

Fehlerbehebung

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