Kontroluj komunikator Notiondesk za pomocą pakietu JavaScript SDK

Pakiet SDK JavaScript Notiondesk Messenger umożliwia bezpośrednią integrację Messengera z interfejsem i stanem aplikacji.

Możesz:

• Otwieraj i zamykaj Messengera z poziomu własnego interfejsu użytkownika

• Kieruj odwiedzających bezpośrednio do Pomocy, Wiadomości, Kontaktu lub Rejestru zmian

• Zbuduj własny program uruchamiający Messenger

• Reaguj na wydarzenia w Messengerze

• Synchronizuj Messengera z motywem i językiem swojej aplikacji

• Aktualizuj uwierzytelnionych użytkowników bez przeładowywania strony

• Zmiana pozycji i układania w stosy w czasie wykonywania

• Zintegruj Messenger ze stanem aplikacji React i Vue

• W razie potrzeby usuń i ponownie zainicjuj Messengera

Użyj zestawu SDK w przypadku aplikacji, które wymagają większej kontroli niż ta, jaką zapewnia standardowy fragment instalacyjny programu Messenger.

Zainstaluj zestaw SDK

Zainstaluj oficjalny pakiet:

Można również użyć Yarn:

Lub pnpm:

Zainicjuj Messengera

Zaimportuj initNotiondesk() i podaj swój identyfikator Messenger:

initNotiondesk() rozwiązuje się, gdy Messenger jest gotowy do użycia, więc najbezpieczniejszym wzorcem jest oczekiwanie na inicjalizację przed wywołaniem metod SDK:

Notiondesk Komunikator musi zostać zainicjowany w przeglądarce. Nie inicjuj go podczas renderowania po stronie serwera.

Aby uzyskać informacje na temat instalacji React i Next.js, zapoznaj się z artykułem Jak zainstalować Notiondesk Messenger za pomocą React i Next.js.

Otwieranie, zamykanie i przełączanie komunikatora

Otwórz Messengera

Użyj show():

Na przykład:

Zamknij Messengera

Użyj hide():

Przełącz komunikator

Użyj toggle(), aby otworzyć Messengera, gdy jest zamknięty i zamknąć go, gdy jest otwarty:

toggle() jest szczególnie użyteczny, gdy Twoja aplikacja udostępnia własny przycisk Messenger.

Otwórz konkretną sekcję Messengera

Użyj showTab(), aby otworzyć Messengera bezpośrednio w konkretnym module:

Dostępne zakładki to:

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

Na przykład:

showTab() otwiera również aplikację Messenger, jeśli jest ona aktualnie zamknięta.

Żądany moduł musi być włączony w konfiguracji Messengera. Na przykład showTab("changelog") nie przełączy się na Changelog, jeśli moduł Changelog jest wyłączony.

Dzięki temu możliwe jest połączenie różnych części interfejsu aplikacji z różnymi środowiskami pomocy technicznej.

Na przykład:

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

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

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

• Centrum pomocy → showTab("help")

• Zapytaj AI → showTab("messages")

• Skontaktuj się z pomocą techniczną → showTab("contact")

• Co nowego → showTab("changelog")

Użyj własnego przycisku Messenger

Nie musisz używać domyślnego programu uruchamiającego Notiondesk.

Wyłącz opcję Pokaż program uruchamiający w ustawieniach Messengera, a następnie użyj zestawu SDK, aby otworzyć Messengera z poziomu własnego interfejsu.

Na przykład:

Jest to przydatne, gdy pomoc techniczna powinna być zintegrowana z istniejącym paskiem nawigacyjnym, menu konta, pulpitem nawigacyjnym, przyciskiem pływającym lub powłoką aplikacji.

W przypadku korzystania z niestandardowego programu uruchamiającego, należy wybrać opcję toggle(), jeśli ten sam element sterujący ma zarówno otwierać, jak i zamykać program Messenger.

Słuchaj wydarzeń w Messengerze

Zestaw SDK udostępnia zdarzenia poprzez on() i off().

Na przykład:

on() zwraca funkcję anulowania subskrypcji:

Dostępne wydarzenia w Messengerze

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

Śledź, z której sekcji Messengera korzystają odwiedzający

Zdarzenie messenger:tabChanged obejmuje bieżącą i poprzednią kartę.

Możesz na przykład przesłać aktywność w Messengerze na platformę analityczną:

Zachowaj synchronizację swojego programu uruchamiającego

Wydarzenia mogą również synchronizować Twój interfejs użytkownika ze stanem Messengera:

Zmień motyw Messengera

Użyj setTheme(), aby przełączać się między trybem jasnym i ciemnym bez konieczności przeładowywania Messengera:

Lub:

Na przykład zsynchronizuj Messengera z motywem swojej aplikacji:

Możesz również reagować na zmiany motywu systemu operacyjnego:

Użyj pulpitu Notiondesk, aby skonfigurować kolory, czcionki, wygląd launchera i inne ustawienia marki w Messengerze. Kontrolka motywu SDK służy do przełączania aktywnego schematu kolorów.

Zmień język Messengera

Użyj setLanguage():

Jest to przydatne, gdy Twoja aplikacja ma już własny selektor języka:

Żądana lokalizacja musi być włączona dla Twojego Messengera w Notiondesk.

Jeśli ustawienia regionalne nie są włączone, Messenger zachowuje dostępny, skonfigurowany język.

Zaktualizuj Messengera po inicjalizacji

Użyj updateConfig(), gdy stan aplikacji ulegnie zmianie po załadowaniu Messengera.

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

Zaktualizuj uwierzytelnionego użytkownika

Po zalogowaniu się użytkownika:

Messenger aktualizuje informacje o bieżącym użytkowniku bez konieczności przeładowywania strony.

Powrót do anonimowego użytkownika

Kiedy użytkownik się wylogowuje:

Pełen przebieg uwierzytelniania opisano w artykule Identyfikowanie zalogowanych użytkowników w programie Notiondesk Messenger .

Zmień pozycję Messengera

Możesz przenosić Messengera w czasie wykonywania:

Obsługiwane stanowiska to:

notiondesk.updateConfig({
  userToken,
});

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

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

• bottom-right

• bottom-left

Domyślna pozycja programu uruchamiającego powinna być zazwyczaj skonfigurowana w panelu Notiondesk. Użyj updateConfig(), gdy aplikacja wymaga tymczasowego nadpisania środowiska wykonawczego.

Na przykład możesz przesunąć Messengera, gdy inny element ruchomy zajmuje ten sam róg.

Zmień poziom układania

Jeśli Messenger ma być wyświetlany nad innym elementem aplikacji:

Korzystaj z Messengera z uwierzytelnionymi użytkownikami

Przekaż podpisany token użytkownika podczas inicjalizacji Messengera:

Możesz również zacząć anonimowo i zidentyfikować użytkownika później:

Token musi zostać wygenerowany przez Twój system zaplecza.

Nigdy nie ujawniaj swojego sekretu aplikacji Notiondesk w kodzie przeglądarki.

Pełną procedurę uwierzytelniania i wylogowywania znajdziesz w sekcji Identyfikowanie zalogowanych użytkowników w programie Notiondesk Messenger .

Usuń Messengera

Użyj destroy(), aby całkowicie usunąć bieżącą instancję Messengera:

Użyj destroy() gdy:

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 nie powinien już istnieć na obecnej stronie

• Konto użytkownika jest przełączane

• Twoja aplikacja odmontowuje integrację Messenger

• Musisz zainicjować nową sesję Messengera

Po zniszczeniu programu Messenger możesz go ponownie uruchomić.

Załaduj Messengera bez jego inicjalizacji

W przypadku aplikacji wymagających większej kontroli nad inicjalizacją należy użyć loadNotiondesk():

Większość aplikacji powinna zamiast tego używać initNotiondesk().

loadNotiondesk() przydaje się, gdy załadowanie pakietu Messenger SDK i uruchomienie samego Messengera musi nastąpić w różnych punktach cyklu życia aplikacji.

Uzyskaj dostęp do już załadowanego interfejsu API Messenger

Użyj getNotiondesk(), aby uzyskać synchroniczny dostęp do API, gdy Messenger został już załadowany:

Jeżeli Messenger nie został jeszcze załadowany, getNotiondesk() zwraca null.

Do normalnej inicjalizacji aplikacji preferuj initNotiondesk().

Kontrolki i stan React

Aplikacje React powinny używać:

useNotiondesk() zapewnia zarówno kontrolki Messengera, jak i jego aktualny stan ładowania.

Na przykład:

Dostępne wartości obejmują:

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

Użyj api, gdy potrzebujesz interfejsów API, takich jak subskrypcje zdarzeń:

W miarę możliwości utrzymuj właściwości konfiguracji, takie jak motyw i ustawienia regionalne, na stabilnym poziomie NotiondeskProvider.

W przypadku zmian w czasie wykonywania należy wybrać opcję setTheme(), setLanguage() lub updateConfig() zamiast konieczności ciągłej zmiany konfiguracji dostawcy.

Kontrolki i stan Vue

Aplikacje Vue mogą uzyskać dostęp do Messengera za pomocą:

Na przykład:

Integracja Vue udostępnia również interfejs API Messenger, status, błędy i te same kontrolki środowiska wykonawczego, co podstawowy zestaw SDK.

Typowe przepisy SDK

Utwórz niestandardowy przycisk Pomocy

Wyłącz domyślny program uruchamiający w ustawieniach Notiondesk Messenger:

Otwórz bezpośrednio swoje centrum pomocy

Otwórz swojego asystenta AI bezpośrednio

Moduł Wiadomości musi być włączony i skonfigurowany w Messengerze.

Otwórz bezpośrednio swój formularz kontaktowy

Otwórz dziennik zmian za pomocą łącza „Co nowego”

Ukryj Messengera na określonej ścieżce aplikacji

Przesuń Messengera z dala od innego pływającego elementu

Śledź użycie Messengera

Zaktualizuj Messengera po zalogowaniu

Wyczyść użytkownika po wylogowaniu

Rozwiązywanie problemów

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