Cách Thêm Chatbot AI Asyntai vào Docusaurus

Hướng dẫn từng bước cho trang tài liệu Docusaurus

Nền tảng:

Bước 1: Lấy Mã Nhúng của Bạn

Đầu tiên, đi đến Bảng điều khiển Asyntai và cuộn xuống phần "Mã Nhúng". Sao chép mã nhúng duy nhất của bạn sẽ trông như thế này:

<script async src="https://asyntai.com/static/js/chat-widget.js" data-asyntai-id="YOUR_WIDGET_ID"></script>

Lưu ý: Mã ở trên chỉ là ví dụ. Bạn phải sao chép mã nhúng duy nhất của riêng mình từ Bảng điều khiển vì nó chứa ID tiện ích cá nhân của bạn.

Bước 2: Thêm Script vào docusaurus.config.js (Khuyến nghị)

Cách tốt nhất để thêm chatbot vào tất cả trang Docusaurus là qua tệp cấu hình:

Mở dự án Docusaurus trong trình biên tập mã
Tìm và mở tệp docusaurus.config.js trong thư mục gốc dự án
Tìm đối tượng const config = { }
Thêm hoặc cập nhật trường scripts với tiện ích Asyntai:

const config = {
  // ... other config options

  scripts: [
    // Other scripts if any
    {
      src: 'https://asyntai.com/static/js/chat-widget.js',
      'data-asyntai-id': 'YOUR_WIDGET_ID',
      async: true,
    },
  ],

  // ... rest of config
};

Lưu tệp docusaurus.config.js
Xây dựng lại trang web bằng cách chạy npm run build hoặc yarn build
Khởi động lại máy chủ phát triển nếu đang chạy cục bộ

Mẹo: Trường scripts chấp nhận mảng các nguồn JavaScript. Thẻ script sẽ được chèn vào phần HTML head của mọi trang tự động. Đây là phương pháp sạch nhất và dễ bảo trì nhất cho trang Docusaurus.

Phương pháp Thay thế 1: Định dạng Chuỗi (Cú pháp Đơn giản hơn)

Nếu bạn thích cách tiếp cận đơn giản hơn, bạn có thể sử dụng định dạng chuỗi trong mảng scripts:

const config = {
  scripts: [
    'https://asyntai.com/static/js/chat-widget.js',
  ],
};

Lưu ý: Khi sử dụng định dạng chuỗi, bạn sẽ cần sửa đổi URL script để bao gồm ID tiện ích dưới dạng tham số truy vấn, hoặc sử dụng định dạng đối tượng trong Bước 2 cho phép bạn đặt thuộc tính data-asyntai-id trực tiếp.

Phương pháp Thay thế 2: Thẻ Head Tùy chỉnh

Bạn cũng có thể thêm script bằng trường headTags trong docusaurus.config.js:

const config = {
  headTags: [
    {
      tagName: 'script',
      attributes: {
        src: 'https://asyntai.com/static/js/chat-widget.js',
        'data-asyntai-id': 'YOUR_WIDGET_ID',
        async: true,
      },
    },
  ],
};

Mẹo: Trường headTags cung cấp nhiều quyền kiểm soát hơn đối với các thẻ HTML chính xác được chèn vào phần <head>. Phương pháp này tương đương về chức năng với việc sử dụng trường scripts.

Phương pháp Thay thế 3: Mẫu HTML Tùy chỉnh (Nâng cao)

Dành cho người dùng nâng cao cần kiểm soát hoàn toàn mẫu HTML:

Tạo thư mục mới: src/theme (nếu chưa tồn tại)
Tạo tệp: src/theme/Root.js
Thêm mã sau để chèn script động:

import React, { useEffect } from 'react';

export default function Root({children}) {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://asyntai.com/static/js/chat-widget.js';
    script.setAttribute('data-asyntai-id', 'YOUR_WIDGET_ID');
    script.async = true;
    document.head.appendChild(script);

    return () => {
      // Cleanup when component unmounts
      document.head.removeChild(script);
    };
  }, []);

  return <>{children}</>;
}

Lưu tệp và xây dựng lại trang web

Quan trọng: Thành phần Root.js bao bọc toàn bộ ứng dụng. Phương pháp nâng cao này chỉ nên sử dụng nếu bạn cần logic JavaScript tùy chỉnh hoặc có yêu cầu cụ thể không thể đáp ứng bằng cách tiếp cận tệp cấu hình.

Phương pháp Thay thế 4: Swizzle Thành phần Chân trang

Bạn có thể tùy chỉnh chân trang để bao gồm script:

Chạy lệnh swizzle: npm run swizzle @docusaurus/theme-classic Footer -- --eject
Điều này tạo bản sao thành phần Footer trong src/theme/Footer/
Chỉnh sửa thành phần Footer để bao gồm thẻ script
Thêm script trước thẻ đóng của chân trang
Lưu và xây dựng lại trang web

Lưu ý: Swizzling cho bạn toàn quyền kiểm soát các thành phần Docusaurus, nhưng điều đó có nghĩa là bạn sẽ cần tự bảo trì thành phần đó. Các cập nhật Docusaurus sẽ không tự động cập nhật các thành phần đã swizzle.

Bước 3: Xây dựng và Triển khai

Sau khi thêm mã, xây dựng và triển khai trang Docusaurus của bạn:

# Build the site
npm run build

# Or with Yarn
yarn build

# Deploy to your hosting platform
# (Vercel, Netlify, GitHub Pages, etc.)

Mẹo: Trong quá trình phát triển, chạy npm start hoặc yarn start để xem trước thay đổi cục bộ. Chatbot sẽ xuất hiện ở góc dưới bên phải trên tất cả các trang.

Bước 4: Xác minh Cài đặt

Sau khi triển khai thay đổi, mở trang tài liệu trong tab trình duyệt mới. Bạn sẽ thấy nút tiện ích trò chuyện ở góc dưới bên phải. Nhấp vào nó để đảm bảo nó mở và hoạt động chính xác.

Không thấy tiện ích? Đảm bảo bạn đã xây dựng lại trang web sau khi thay đổi. Kiểm tra bạn đã thay thế YOUR_WIDGET_ID bằng ID tiện ích thực tế từ bảng điều khiển. Xóa bộ nhớ đệm trình duyệt hoặc xem ở chế độ ẩn danh. Mở bảng điều khiển trình duyệt (F12) để kiểm tra lỗi JavaScript.

Tài liệu