Điều khiển ứng dụng nhắn tin Notiondesk bằng JavaScript SDK

Bộ SDK JavaScript của Messenger cho phép bạn tích hợp Messenger trực tiếp với giao diện và trạng thái ứng dụng của mình.

Bạn có thể:

• Mở và đóng Messenger từ giao diện người dùng của bạn.

• Hướng khách truy cập trực tiếp đến trang Trợ giúp, Tin nhắn, Liên hệ hoặc Nhật ký thay đổi.

• Tự tạo trình khởi chạy Messenger của riêng bạn

• Phản hồi các sự kiện Messenger

• Đồng bộ hóa Messenger với giao diện và ngôn ngữ của ứng dụng.

• Cập nhật người dùng đã xác thực mà không cần tải lại trang.

• Thay đổi vị trí và xếp chồng trong quá trình thực thi

• Tích hợp Messenger với trạng thái ứng dụng React và Vue

• Gỡ bỏ và khởi tạo lại Messenger khi cần thiết.

Hãy sử dụng SDK cho các ứng dụng cần nhiều quyền kiểm soát hơn so với đoạn mã cài đặt Messenger tiêu chuẩn cung cấp.

Cài đặt SDK

Cài đặt gói phần mềm chính thức:

Bạn cũng có thể sử dụng Yarn:

Hoặc pnpm:

Khởi tạo Messenger

Nhập initNotiondesk() và cung cấp ID Messenger của bạn:

Biến initNotiondesk() sẽ được giải quyết khi Messenger sẵn sàng sử dụng, vì vậy cách an toàn nhất là đợi quá trình khởi tạo hoàn tất trước khi gọi các phương thức SDK:

Ứng dụng Messenger phải được khởi tạo trong trình duyệt. Không được khởi tạo nó trong quá trình hiển thị phía máy chủ.

Để cài đặt React và Next.js, hãy xem Cách cài đặt Notiondesk Messenger với React và Next.js.

Mở, đóng và bật/tắt Messenger

Mở ứng dụng nhắn tin

Sử dụng show():

Ví dụ:

Đóng ứng dụng nhắn tin

Sử dụng hide():

Bật/tắt Messenger

Sử dụng toggle() để mở Messenger khi nó đang đóng và đóng nó khi nó đang mở:

toggle() đặc biệt hữu ích khi ứng dụng của bạn cung cấp nút Messenger riêng.

Mở một mục Messenger cụ thể

Sử dụng showTab() để mở Messenger trực tiếp trên một mô-đun cụ thể:

Các tab hiện có là:

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

Ví dụ:

showTab() cũng mở Messenger nếu ứng dụng hiện đang đóng.

Mô-đun được yêu cầu phải được kích hoạt trong cấu hình Messenger của bạn. Ví dụ, showTab("changelog") sẽ không chuyển sang Nhật ký thay đổi nếu mô-đun Nhật ký thay đổi bị vô hiệu hóa.

Điều này cho phép kết nối các phần khác nhau của giao diện ứng dụng với các trải nghiệm hỗ trợ khác nhau.

Ví dụ:

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

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

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

• Trung tâm trợ giúp → showTab("help")

• Hỏi AI → __ĐÃ BẢO TỒN_112__

• Liên hệ bộ phận hỗ trợ → showTab("contact")

• Có gì mới → showTab("changelog")

Sử dụng nút Messenger của riêng bạn

Bạn không nhất thiết phải sử dụng trình khởi chạy mặc định Notiondesk.

Tắt tùy chọn "Hiển thị trình khởi chạy" trong cài đặt Messenger, sau đó sử dụng SDK để mở Messenger từ giao diện của riêng bạn.

Ví dụ:

Điều này rất hữu ích khi cần tích hợp chức năng hỗ trợ vào thanh điều hướng, menu tài khoản, bảng điều khiển, nút nổi hoặc giao diện ứng dụng hiện có.

Khi sử dụng trình khởi chạy tùy chỉnh, hãy ưu tiên toggle() nếu cùng một điều khiển cần dùng để mở và đóng Messenger.

Nghe các sự kiện trên Messenger

SDK hiển thị các sự kiện thông qua on() và off().

Ví dụ:

on() trả về một hàm hủy đăng ký:

Các sự kiện Messenger có sẵn

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

Theo dõi xem khách truy cập sử dụng phần nào của Messenger.

Sự kiện messenger:tabChanged bao gồm tab hiện tại và tab trước đó.

Ví dụ, bạn có thể chuyển tiếp hoạt động của Messenger đến nền tảng phân tích của mình:

Hãy giữ cho trình khởi chạy của bạn luôn được đồng bộ hóa.

Các sự kiện cũng có thể đồng bộ hóa giao diện người dùng của bạn với trạng thái của Messenger:

Thay đổi giao diện Messenger

Sử dụng setTheme() để chuyển đổi giữa chế độ sáng và tối mà không cần tải lại Messenger:

Hoặc:

Ví dụ, đồng bộ hóa Messenger với giao diện ứng dụng của bạn:

Bạn cũng có thể phản hồi lại những thay đổi về giao diện hệ điều hành:

Sử dụng bảng điều khiển Notiondesk để tùy chỉnh màu sắc, phông chữ, giao diện trình khởi chạy và các cài đặt thương hiệu khác cho Messenger của bạn. Chức năng điều khiển chủ đề SDK được thiết kế để chuyển đổi lược đồ màu đang hoạt động.

Thay đổi ngôn ngữ của Messenger

Sử dụng setLanguage():

Điều này hữu ích khi ứng dụng của bạn đã có bộ chọn ngôn ngữ riêng:

Ngôn ngữ được yêu cầu phải được bật cho Messenger của bạn trong Notiondesk.

Nếu tùy chọn ngôn ngữ không được bật, Messenger sẽ sử dụng ngôn ngữ đã được cấu hình sẵn.

Cập nhật Messenger sau khi khởi tạo.

Sử dụng updateConfig() khi trạng thái ứng dụng thay đổi sau khi Messenger đã tải xong.

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

Cập nhật thông tin người dùng đã xác thực

Sau khi người dùng đăng nhập:

Messenger cập nhật thông tin người dùng hiện tại mà không cần tải lại trang.

Quay lại người dùng ẩn danh

Khi người dùng đăng xuất:

Để xem quy trình xác thực đầy đủ, hãy xem Xác định người dùng đã đăng nhập trong Notiondesk Messenger .

Thay đổi vị trí của người đưa tin

Bạn có thể di chuyển Messenger trong quá trình chạy:

Các vị trí được hỗ trợ là:

notiondesk.updateConfig({
  userToken,
});

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

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

• bottom-right

• bottom-left

Vị trí trình khởi chạy mặc định của bạn thường được cấu hình trong bảng điều khiển Notiondesk. Sử dụng updateConfig() khi ứng dụng của bạn cần ghi đè tạm thời trong thời gian chạy.

Ví dụ, bạn có thể di chuyển Messenger khi một phần tử nổi khác chiếm cùng một góc.

Thay đổi cấp độ xếp chồng

Nếu Messenger cần hiển thị phía trên một thành phần ứng dụng khác:

Sử dụng Messenger với người dùng đã được xác thực.

Hãy truyền mã thông báo người dùng đã ký khi khởi tạo Messenger:

Bạn cũng có thể bắt đầu ẩn danh và xác định danh tính người dùng sau đó:

Mã token phải được tạo bởi hệ thống phụ trợ của bạn.

Tuyệt đối không để lộ mã bí mật ứng dụng Notiondesk của bạn trong mã trình duyệt.

Xem phần "Xác định người dùng đã đăng nhập trong Notiondesk Messenger" để biết quy trình xác thực và đăng xuất đầy đủ.

Xóa Messenger

Sử dụng destroy() để xóa hoàn toàn phiên bản Messenger hiện tại:

Sử dụng destroy() khi:

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

• Ứng dụng Messenger không nên còn tồn tại trên trang hiện tại.

• Đang chuyển đổi tài khoản người dùng.

• Ứng dụng của bạn đang gỡ bỏ tích hợp Messenger.

• Bạn cần khởi tạo một phiên Messenger mới.

Bạn có thể khởi tạo lại Messenger sau khi đã xóa nó.

Tải Messenger mà không cần khởi tạo.

Đối với các ứng dụng cần kiểm soát nhiều hơn quá trình khởi tạo, hãy sử dụng loadNotiondesk():

Hầu hết các ứng dụng nên sử dụng initNotiondesk() thay thế.

loadNotiondesk() rất hữu ích khi việc tải SDK Messenger và khởi động Messenger cần diễn ra ở các thời điểm khác nhau trong vòng đời của ứng dụng.

Truy cập API Messenger đã được tải sẵn.

Sử dụng getNotiondesk() để truy cập API một cách đồng bộ khi Messenger đã được tải xong:

Nếu Messenger chưa được tải, getNotiondesk() sẽ trả về null.

Để khởi tạo ứng dụng thông thường, hãy ưu tiên initNotiondesk().

Điều khiển và trạng thái React

Các ứng dụng React nên sử dụng:

useNotiondesk() cung cấp cả các điều khiển Messenger và trạng thái tải hiện tại của nó.

Ví dụ:

Các giá trị khả dụng bao gồm:

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

Hãy sử dụng api khi bạn cần các API như đăng ký sự kiện:

Hãy giữ các thuộc tính cấu hình như theme và locale ổn định trên NotiondeskProvider nếu có thể.

Đối với các thay đổi trong thời gian chạy, nên ưu tiên sử dụng setTheme(), setLanguage() hoặc updateConfig() thay vì liên tục thay đổi cấu hình nhà cung cấp.

Vue điều khiển và trạng thái

Các ứng dụng Vue có thể truy cập Messenger bằng cách sử dụng:

Ví dụ:

Việc tích hợp Vue cũng cung cấp API Messenger, trạng thái, lỗi và các điều khiển thời gian chạy tương tự như SDK cốt lõi.

Công thức SDK phổ biến

Tạo nút Trợ giúp tùy chỉnh

Tắt trình khởi chạy mặc định trong cài đặt Messenger của bạn:

Mở trung tâm trợ giúp của bạn trực tiếp

Mở trợ lý AI của bạn trực tiếp

Mô-đun Tin nhắn phải được kích hoạt và cấu hình trong Messenger.

Mở biểu mẫu liên hệ trực tiếp

Mở nhật ký thay đổi của bạn từ liên kết "Có gì mới".

Ẩn Messenger trên một tuyến ứng dụng cụ thể

Di chuyển Messenger ra xa khỏi một phần tử nổi khác

Theo dõi việc sử dụng Messenger

Cập nhật Messenger sau khi đăng nhập

Xóa thông tin người dùng sau khi đăng xuất.

Khắc phục sự cố

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