Hướng dẫn cài đặt ứng dụng nhắn tin Notiondesk bằng React và Next.js

Notiondesk cung cấp bộ SDK JavaScript chính thức để cài đặt Messenger trong các ứng dụng React và Next.js.

Hãy sử dụng SDK thay vì đoạn mã Messenger <script> tiêu chuẩn khi trang web của bạn được xây dựng bằng React, Next.js hoặc một ứng dụng trang đơn khác.

Trước khi bạn bắt đầu

Bạn cần:

• Một ứng dụng nhắn tin Notiondesk được cấu hình trong không gian làm việc của bạn

• ID Messenger của bạn

• Một ứng dụng React hoặc Next.js

• Truy cập vào mã nguồn ứng dụng của bạn

Bạn có thể tìm thấy ID Messenger và các tùy chọn cài đặt trong cài đặt Messenger của mình tại địa chỉ Notiondesk .

Cài đặt Messenger SDK

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

Với sợi len:

Với pnpm:

Gói phần mềm chính thức có sẵn trên npm .

Cài đặt Messenger trong React

Nhập NotiondeskProvider và bao bọc phần ứng dụng của bạn nơi Messenger cần được tích hợp.

Đối với hầu hết các ứng dụng, hãy đặt provider gần thư mục gốc của ứng dụng:

Thay thế YOUR_MESSENGER_ID bằng ID Messenger từ không gian làm việc Notiondesk của bạn.

Messenger hiện đã khả dụng cho các thành phần được hiển thị bên trong NotiondeskProvider.

Mở Messenger từ một thành phần React

Hãy sử dụng hook useNotiondesk khi bạn cần điều khiển Messenger từ giao diện của mình.

Ví dụ, bạn có thể tạo nút hỗ trợ của riêng mình:

Thành phần sử dụng useNotiondesk phải được hiển thị bên trong NotiondeskProvider.

Cài đặt Messenger trong Next.js

Notiondesk Messenger chạy trên trình duyệt, vì vậy việc tích hợp Messenger phải được khởi tạo từ một thành phần phía máy khách.

Ví dụ sau sử dụng App Router của Next.js.

1. Tạo một thành phần máy khách Notiondesk

Tạo một thành phần như notiondesk-setup.tsx:

Thay thế YOUR_MESSENGER_ID bằng ID Messenger của bạn Notiondesk.

npm install @notiondesk-so/messenger-js-sdk

yarn add @notiondesk-so/messenger-js-sdk

pnpm add @notiondesk-so/messenger-js-sdk

import { NotiondeskProvider } from "@notiondesk-so/messenger-js-sdk/react";

export function App({ children }) {
  return (
    <NotiondeskProvider messengerId="YOUR_MESSENGER_ID">
      {children}
    </NotiondeskProvider>
  );
}

import { useNotiondesk } from "@notiondesk-so/messenger-js-sdk/react";

export function SupportButton() {
  const { show } = useNotiondesk();

  return (
    <button onClick={() => void show()}>
      Contact support
    </button>
  );
}

"use client";

import {
  NotiondeskProvider,
  useNotiondesk,
} from "@notiondesk-so/messenger-js-sdk/react";
import type { ReactNode } from "react";

function SupportButton() {
  const { show } = useNotiondesk();

  return (
    <button onClick={() => void show()}>
      Contact support
    </button>
  );
}

export function NotiondeskSetup({
  children,
}: {
  children: ReactNode;
}) {
  return (
    <NotiondeskProvider messengerId="YOUR_MESSENGER_ID">
      {children}
      <SupportButton />
    </NotiondeskProvider>
  );
}

2. Thêm nhà cung cấp vào bố cục của bạn

Hiển thị thành phần phía máy khách từ bố cục gốc của bạn:

Việc đặt NotiondeskSetup vào bố cục gốc giúp Messenger khả dụng trong toàn bộ ứng dụng.

Nếu Messenger chỉ nên khả dụng ở những phần cụ thể trong ứng dụng của bạn, hãy đặt nhà cung cấp này vào một bố cục hoặc trang cụ thể hơn.

Điều khiển chương trình Messenger

Hook của React cung cấp các điều khiển Messenger mà bạn có thể sử dụng từ các component của mình.

Ví dụ:

Bạn có thể sử dụng các phương pháp này để kết nối Messenger với các nút, thanh điều hướng, menu hỗ trợ hoặc giao diện người dùng ứng dụng khác của riêng bạn.

Bộ SDK cũng hỗ trợ các cấu hình và điều khiển bổ sung như thay đổi ngôn ngữ hoặc chủ đề.

Tải Messenger có điều kiện

Bạn có thể ngăn Messenger tải đối với những người dùng không được phép truy cập bằng tùy chọn enabled:

Hãy để logic phân quyền riêng của ứng dụng chịu trách nhiệm quyết định xem Messenger có nên được bật hay không.

Tính năng này hữu ích khi Messenger chỉ dành cho khách hàng đã đăng nhập, các gói dịch vụ cụ thể hoặc các khu vực nhất định trong ứng dụng của bạn.

import { NotiondeskSetup } from "./notiondesk-setup";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <NotiondeskSetup>
          {children}
        </NotiondeskSetup>
      </body>
    </html>
  );
}

const notiondesk = useNotiondesk();

await notiondesk.show();
await notiondesk.hide();
await notiondesk.toggle();

<NotiondeskProvider
  messengerId="YOUR_MESSENGER_ID"
  enabled={currentUser.canUseSupportWidget}
>
  {children}
</NotiondeskProvider>

Xác định người dùng đã đăng nhập

Ứng dụng Messenger có thể xác định người dùng đã được xác thực bằng cách sử dụng mã thông báo người dùng đã ký được tạo bởi hệ thống phụ trợ của bạn.

Chuyển mã thông báo cho nhà cung cấp:

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

Mã bí mật ứng dụng phải được lưu trữ trên máy chủ của bạn. Giao diện người dùng (frontend) chỉ nên nhận mã thông báo người dùng có thời hạn ngắn đã được ký điện tử do máy chủ (backend) của bạn tạo ra.

Xác minh quá trình cài đặt

Sau khi cài đặt SDK:

<NotiondeskProvider
  messengerId="YOUR_MESSENGER_ID"
  userToken={userToken}
>
  {children}
</NotiondeskProvider>

1. Khởi chạy hoặc triển khai ứng dụng của bạn.

2. Mở một trang được hiển thị bên trong NotiondeskProvider

3. Hãy xác nhận rằng Messenger tải đúng cách.

4. Nếu bạn đã thêm nút hỗ trợ tùy chỉnh, hãy nhấp vào nút đó và xác nhận rằng Messenger sẽ mở.

5. Kiểm tra chức năng điều hướng giữa các trang trong ứng dụng của bạn.

6. Kiểm tra bảng điều khiển trình duyệt để tìm lỗi JavaScript.

Đối với Next.js, hãy kiểm tra cả bản dựng dành cho môi trường sản xuất vì hành vi hiển thị trên máy khách/máy chủ có thể khác so với môi trường phát triển cục bộ.

Khắc phục sự cố

"use client";

<NotiondeskProvider messengerId="YOUR_MESSENGER_ID">
  <SupportButton />
</NotiondeskProvider>

const { show } = useNotiondesk();

<button onClick={() => void show()}>
  Contact support
</button>