Управляйте мессенджером Notiondesk с помощью JavaScript SDK.

JavaScript SDK Notiondesk Messenger позволяет интегрировать Messenger непосредственно с интерфейсом и состоянием вашего приложения.

Ты можешь:

• Открывайте и закрывайте Messenger из собственного пользовательского интерфейса.

• Направляйте посетителей непосредственно в разделы «Помощь», «Сообщения», «Контакты» или «Журнал изменений».

• Создайте свой собственный лаунчер для Messenger

• Реагируйте на события в Messenger.

• Синхронизируйте Messenger с темой оформления и языком вашего приложения.

• Обновление данных авторизованных пользователей без перезагрузки страницы.

• Изменение положения и наложения элементов во время выполнения программы.

• Интеграция Messenger с состоянием приложения React и Vue.

• При необходимости удалите и повторно запустите Messenger.

Используйте SDK для приложений, которым требуется больше контроля, чем предоставляет стандартный фрагмент кода установки Messenger.

Установите SDK.

Установите официальный пакет:

Также можно использовать пряжу:

Или pnpm:

Инициализация мессенджера

Импортируйте initNotiondesk() и укажите свой ID в Messenger:

initNotiondesk() разрешается, когда Messenger готов к использованию, поэтому наиболее безопасный подход — дождаться инициализации, прежде чем вызывать методы SDK:

Notiondesk Messenger должен быть инициализирован в браузере. Не инициализируйте его во время рендеринга на стороне сервера.

Инструкции по установке React и Next.js см. в разделе «Как установить Notiondesk Messenger с React и Next.js» .

Открыть, закрыть и переключить Messenger

Открыть мессенджер

Используйте show():

Например:

Близкий мессенджер

Используйте hide():

Переключить мессенджер

Используйте toggle(), чтобы открывать Messenger, когда он закрыт, и закрывать его, когда он открыт:

toggle() особенно полезен, если ваше приложение предоставляет собственную кнопку Messenger.

Откройте определенный раздел Messenger.

Используйте showTab() для прямого открытия Messenger на определенном модуле:

Доступные вкладки:

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

Например:

showTab() также открывает Messenger, если он в данный момент закрыт.

Запрашиваемый модуль должен быть включен в настройках Messenger. Например, showTab("changelog") не переключится на Changelog, если модуль Changelog отключен.

Это позволяет связать различные части интерфейса вашего приложения с различными вариантами поддержки.

Например:

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

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

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

• Центр поддержки → showTab("help")

• Спросить ИИ → showTab("messages")

• Связаться со службой поддержки → showTab("contact")

• Что нового → __СОХРАНЕНО_110__

Используйте свою собственную кнопку Messenger

Использовать стандартный лаунчер Notiondesk необязательно.

Отключите параметр «Показывать панель запуска» в настройках Messenger, затем используйте SDK для открытия Messenger из собственного интерфейса.

Например:

Это полезно, когда поддержку необходимо интегрировать в существующую панель навигации, меню учетной записи, панель управления, плавающую кнопку или оболочку приложения.

При использовании пользовательского лаунчера отдавайте предпочтение toggle(), если один и тот же элемент управления должен одновременно открывать и закрывать Messenger.

Слушайте события Messenger

SDK предоставляет доступ к событиям через on() и off().

Например:

Функция on() возвращает функцию отмены подписки:

Доступные события Messenger

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

Отслеживайте, какой раздел Messenger используют посетители.

Событие messenger:tabChanged включает текущую и предыдущую вкладку.

Например, вы можете пересылать сообщения из Messenger на свою аналитическую платформу:

Поддерживайте синхронизацию своего лаунчера.

События также могут синхронизировать ваш пользовательский интерфейс с состоянием Messenger:

Изменить тему оформления Messenger

Используйте setTheme() для переключения между светлым и темным режимом без перезагрузки Messenger:

Или:

Например, синхронизируйте Messenger с темой вашего приложения:

Вы также можете реагировать на изменения темы оформления операционной системы:

Используйте панель управления Notiondesk для настройки цветов, шрифтов, внешнего вида лаунчера и других параметров фирменного стиля вашего Messenger. Элемент управления темой SDK предназначен для переключения активной цветовой схемы.

Изменить язык мессенджера

Используйте setLanguage():

Это полезно, если в вашем приложении уже есть собственный селектор языка:

Для включения требуемой локали в Messenger необходимо использовать параметр Notiondesk.

Если языковая поддержка не включена, Messenger будет использовать доступный настроенный язык.

Обновите Messenger после инициализации.

Используйте updateConfig(), если состояние приложения изменяется после того, как Messenger уже загружен.

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

Обновление данных аутентифицированного пользователя

После входа пользователя в систему:

Messenger обновляет информацию для текущего пользователя без необходимости перезагрузки страницы.

Вернуться к анонимному пользователю

Когда пользователь выходит из системы:

Полный алгоритм аутентификации см. в разделе «Идентификация авторизованных пользователей в Messenger Notiondesk» .

Изменить положение мессенджера

Переместить Messenger можно во время выполнения:

Поддерживаемые позиции:

notiondesk.updateConfig({
  userToken,
});

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

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

• bottom-right

• bottom-left

Обычно положение панели запуска по умолчанию следует настраивать в панели управления Notiondesk. Используйте updateConfig(), если вашему приложению требуется временное переопределение во время выполнения.

Например, вы можете переместить Messenger, если другой плавающий элемент занимает тот же угол.

Изменить уровень штабелирования

Если Messenger должен отображаться поверх другого элемента приложения:

Используйте Messenger с авторизованными пользователями.

Передайте подписанный пользовательский токен при инициализации Messenger:

Вы также можете начать анонимно и идентифицировать пользователя позже:

Токен должен быть сгенерирован вашей серверной частью.

Никогда не раскрывайте свой секретный ключ приложения Notiondesk в коде браузера.

Полную информацию о процессе аутентификации и выхода из системы см. в разделе «Идентификация авторизованных пользователей в мессенджере Notiondesk» .

Удалить мессенджер

Используйте destroy() для полного удаления текущего экземпляра Messenger:

Используйте destroy() в следующих случаях:

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 больше не должна присутствовать на текущей странице.

• Происходит переключение учетной записи пользователя.

• Ваше приложение отключает интеграцию с Messenger.

• Вам необходимо инициализировать новую сессию Messenger.

После удаления Messenger его можно инициализировать повторно.

Загрузить Messenger без его инициализации.

Для приложений, которым требуется больший контроль над инициализацией, используйте loadNotiondesk():

В большинстве приложений следует использовать initNotiondesk() вместо этого.

Параметр loadNotiondesk() полезен, когда загрузка SDK Messenger и запуск самого Messenger должны происходить в разные моменты жизненного цикла вашего приложения.

Получите доступ к уже загруженному API Messenger.

Используйте getNotiondesk() для синхронного доступа к API, когда Messenger уже загружен:

Если Messenger еще не загружен, getNotiondesk() возвращает null.

Для обычной инициализации приложения предпочтительнее использовать initNotiondesk().

React управляет состоянием.

В приложениях на основе React следует использовать:

useNotiondesk() предоставляет как элементы управления Messenger, так и текущее состояние загрузки.

Например:

Доступные значения включают:

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

Используйте api, когда вам нужны API, например, для подписки на события:

По возможности сохраняйте стабильные параметры конфигурации, такие как тема и локаль, в NotiondeskProvider.

Для внесения изменений во время выполнения предпочтительнее использовать setTheme(), setLanguage() или updateConfig(), а не многократно изменять конфигурацию поставщика.

Управление и состояние в Vue

Приложения Vue могут получить доступ к Messenger следующими способами:

Например:

Интеграция с Vue также предоставляет доступ к API Messenger, статусу, ошибкам и тем же элементам управления во время выполнения, что и основной SDK.

Рецепты Common SDK

Создайте пользовательскую кнопку справки.

Отключите стандартный лаунчер в настройках Messenger:

Откройте свой справочный центр напрямую.

Откройте своего ИИ-помощника напрямую.

Модуль «Сообщения» должен быть включен и настроен в Messenger.

Откройте форму обратной связи напрямую.

Откройте список изменений по ссылке «Что нового».

Скрыть Messenger на определенном маршруте приложения

Переместите Messenger подальше от другого плавающего элемента.

Отслеживание использования мессенджера

Обновить Messenger после входа в систему

После выхода из системы необходимо удалить данные пользователя.

Поиск неисправностей

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