Bestuur Messenger met de JavaScript SDK.

Met de Messenger JavaScript SDK (Notiondesk) kunt u Messenger rechtstreeks integreren met de interface en de status van uw applicatie.

Je kunt:

• Open en sluit Messenger vanuit je eigen gebruikersinterface.

• Stuur bezoekers direct door naar Help, Berichten, Contact of Wijzigingslogboek.

• Bouw je eigen Messenger-launcher

• Reageer op Messenger-gebeurtenissen

• Synchroniseer Messenger met het thema en de taal van je applicatie.

• Geverifieerde gebruikers bijwerken zonder de pagina opnieuw te laden.

• Positie en stapeling wijzigen tijdens de uitvoering.

• Integreer Messenger met de applicatiestatus van React en Vue.

• Verwijder en herinitialiseer Messenger indien nodig.

Gebruik de SDK voor applicaties die meer controle vereisen dan het standaard installatiefragment van Messenger biedt.

Installeer de SDK

Installeer het officiële pakket:

Je kunt ook Yarn gebruiken:

Of pnpm:

Initialiseer Messenger

Importeer initNotiondesk() en geef je Messenger ID op:

initNotiondesk() wordt opgelost wanneer Messenger klaar is voor gebruik. De veiligste aanpak is daarom om te wachten op de initialisatie voordat SDK-methoden worden aangeroepen.

Messenger moet in de browser worden geïnitialiseerd. Initialiseer het niet tijdens het renderen aan de serverzijde.

Voor de installatie met React en Next.js, zie Hoe installeer je Messenger met React en Next.js ?

Messenger openen, sluiten en in- of uitschakelen.

Open Messenger

Gebruik show():

Bijvoorbeeld:

Sluit Messenger

Gebruik hide():

Messenger in-/uitschakelen

Gebruik toggle() om Messenger te openen wanneer het gesloten is en te sluiten wanneer het open is:

toggle() is met name handig wanneer uw applicatie een eigen Messenger-knop biedt.

Open een specifiek Messenger-gedeelte

Gebruik showTab() om Messenger direct in een specifieke module te openen:

De beschikbare tabbladen zijn:

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

Bijvoorbeeld:

showTab() opent ook Messenger als deze momenteel gesloten is.

De gevraagde module moet ingeschakeld zijn in je Messenger-configuratie. Bijvoorbeeld, showTab("changelog") zal niet overschakelen naar Changelog als de Changelog-module is uitgeschakeld.

Dit maakt het mogelijk om verschillende onderdelen van de interface van uw applicatie te koppelen aan verschillende ondersteuningsmogelijkheden.

Bijvoorbeeld:

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

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

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

• Helpcentrum → __GERESERVEERD_113__

• Vraag het aan de AI → __GEVESTIGD_112__

• Neem contact op met de supportafdeling → __GEVESTIGD_111__

• Wat is er nieuw → __GERESERVEERD_110__

Gebruik je eigen Messenger-knop

Je hoeft de standaard launcher Notiondesk niet te gebruiken.

Schakel 'Launcher weergeven' uit in je Messenger-instellingen en gebruik vervolgens de SDK om Messenger vanuit je eigen interface te openen.

Bijvoorbeeld:

Dit is handig wanneer ondersteuning moet worden geïntegreerd in een bestaande navigatiebalk, accountmenu, dashboard, zwevende knop of applicatie-interface.

Bij gebruik van een aangepaste launcher, geef de voorkeur aan toggle() als dezelfde knop zowel Messenger moet openen als sluiten.

Luister naar Messenger-evenementen

De SDK stelt gebeurtenissen beschikbaar via on() en off().

Bijvoorbeeld:

on() retourneert een functie om het abonnement op te zeggen:

Beschikbare Messenger-evenementen

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

Volg welke Messenger-sectie bezoekers gebruiken

De gebeurtenis messenger:tabChanged omvat het huidige en het vorige tabblad.

Je kunt bijvoorbeeld Messenger-activiteit doorsturen naar je analyseplatform:

Houd je eigen launcher gesynchroniseerd.

Gebeurtenissen kunnen je gebruikersinterface ook synchroniseren met de status van Messenger:

Wijzig het Messenger-thema

Gebruik setTheme() om te schakelen tussen de lichte en donkere modus zonder Messenger opnieuw te laden:

Of:

Synchroniseer Messenger bijvoorbeeld met het thema van uw applicatie:

Je kunt ook reageren op wijzigingen in het thema van het besturingssysteem:

Gebruik het Notiondesk dashboard voor de kleuren, lettertypen, het uiterlijk van de launcher en andere merkinstellingen van je Messenger. De SDK-thema-instellingen zijn bedoeld om het actieve kleurenschema te wijzigen.

Wijzig de Messenger-taal

Gebruik setLanguage():

Dit is handig wanneer uw applicatie al een eigen taalkiezer heeft:

De gevraagde landinstelling moet voor uw Messenger zijn ingeschakeld in Notiondesk.

Als de landinstelling niet is ingeschakeld, gebruikt Messenger in plaats daarvan een beschikbare, geconfigureerde taal.

Messenger bijwerken na initialisatie

Gebruik updateConfig() wanneer de applicatiestatus verandert nadat Messenger al is geladen.

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

Een geauthenticeerde gebruiker bijwerken

Nadat een gebruiker is ingelogd:

Messenger werkt de huidige gebruiker bij zonder dat de pagina opnieuw hoeft te worden geladen.

Terug naar een anonieme gebruiker

Wanneer een gebruiker uitlogt:

Voor de volledige authenticatieprocedure, zie Gebruikers identificeren in Messenger .

Wijzig de positie van Messenger

Je kunt Messenger tijdens de uitvoering verplaatsen:

De volgende functies worden ondersteund:

notiondesk.updateConfig({
  userToken,
});

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

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

• bottom-right

• bottom-left

De standaardpositie van uw launcher wordt normaal gesproken geconfigureerd in het Notiondesk dashboard. Gebruik updateConfig() wanneer uw applicatie een tijdelijke runtime-override nodig heeft.

Je kunt Messenger bijvoorbeeld verplaatsen als een ander zwevend element dezelfde hoek inneemt.

Wijzig het stapelniveau

Als Messenger boven een ander applicatie-element moet verschijnen:

Gebruik Messenger met geverifieerde gebruikers.

Geef een ondertekend gebruikerstoken mee bij het initialiseren van Messenger:

Je kunt ook anoniem beginnen en de gebruiker later identificeren:

Het token moet door uw backend worden gegenereerd.

Geef uw Notiondesk app-geheim nooit weer in browsercode.

Zie 'Ingelogde gebruikers identificeren in Messenger' voor het volledige authenticatie- en uitlogproces.

Messenger verwijderen

Gebruik destroy() om de huidige Messenger-instantie volledig te verwijderen:

Gebruik destroy() wanneer:

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 zou niet langer op deze pagina aanwezig moeten zijn.

• Een gebruikersaccount wordt overgezet.

• Uw applicatie ontkoppelt de Messenger-integratie.

• Je moet een nieuwe Messenger-sessie starten.

Je kunt Messenger opnieuw initialiseren nadat je het hebt afgesloten.

Laad Messenger zonder het te initialiseren.

Voor toepassingen die meer controle over de initialisatie vereisen, gebruikt u loadNotiondesk():

De meeste applicaties zouden in plaats daarvan initNotiondesk() moeten gebruiken.

loadNotiondesk() is handig wanneer het laden van de Messenger SDK en het starten van Messenger zelf op verschillende momenten in de levenscyclus van uw applicatie moeten plaatsvinden.

Toegang tot een reeds geladen Messenger API

Gebruik getNotiondesk() om synchroon toegang te krijgen tot de API wanneer Messenger al is geladen:

Als Messenger nog niet is geladen, retourneert getNotiondesk() null.

Voor normale applicatie-initialisatie heeft initNotiondesk() de voorkeur.

React-besturingselementen en -status

React-applicaties zouden het volgende moeten gebruiken:

useNotiondesk() toont zowel de bedieningselementen van Messenger als de huidige laadstatus.

Bijvoorbeeld:

Beschikbare waarden zijn onder andere:

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

Gebruik api wanneer u API's nodig hebt, zoals bijvoorbeeld voor het abonneren op gebeurtenissen:

Zorg ervoor dat configuratie-eigenschappen zoals thema en taal zo stabiel mogelijk blijven op NotiondeskProvider.

Voor wijzigingen tijdens de uitvoering kunt u het beste setTheme(), setLanguage() of updateConfig() gebruiken in plaats van herhaaldelijk de providerconfiguratie te wijzigen.

Vue-besturingselementen en -status

Vue-applicaties hebben toegang tot Messenger via:

Bijvoorbeeld:

De Vue-integratie biedt ook toegang tot de Messenger API, statusinformatie, foutmeldingen en dezelfde runtime-besturingselementen als de kern-SDK.

Veelvoorkomende SDK-recepten

Maak een aangepaste Help-knop aan.

Schakel de standaardlauncher uit in de instellingen van je Messenger:

Open direct uw helpcentrum.

Open uw AI-assistent direct.

De berichtenmodule moet in Messenger ingeschakeld en geconfigureerd zijn.

Open uw contactformulier direct

Open je wijzigingslogboek via een link naar 'Wat is nieuw'.

Messenger verbergen op een specifieke applicatieroute

Verplaats Messenger weg van een ander zwevend element.

Volg het Messenger-gebruik

Update Messenger na het inloggen

Wis de gebruiker na het uitloggen.

Probleemoplossing

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