Widget web
Thêm giao diện chat của trợ lý vào website bằng một đoạn script.
Widget web hiển thị trợ lý dưới dạng cửa sổ chat nổi trên website. Assistant Core cung cấp sẵn giao diện, streaming, lịch sử hội thoại, Markdown, chế độ tối và bố cục mobile.
Trước khi bắt đầu
- Bạn có quyền quản lý trợ lý trong Admin Panel.
- Gói hiện tại có tính năng Widget web.
- Bạn biết origin chính xác của website, ví dụ
https://www.example.com.
Origin gồm protocol, hostname và port nếu có. Origin không chứa path, query parameter hoặc fragment.
1. Cho phép website
- Mở Admin Panel và chọn trợ lý.
- Vào Kênh kết nối → Widget web.
- Trong 1. Cho phép website, nhập origin đầy đủ.
- Chọn Thêm website, sau đó chọn Lưu thay đổi.
Ví dụ origin hợp lệ:
https://www.example.com
https://preview.example.com
http://localhost:3000Thêm riêng từng origin production, staging, preview và local development. https://example.com và https://www.example.com là hai origin khác nhau.
2. Cài đặt widget
Trong 2. Cài đặt widget, chọn Sao chép đoạn mã. Đoạn mã có sẵn ID trợ lý và API base phù hợp với môi trường:
<script
src="https://cdn.assistantcore.com/embed/embed.js"
data-assistant-id="ID_TRỢ_LÝ"
data-api-base="https://api.assistantcore.com"
async
></script>Dán script một lần, gần cuối thẻ <body> hoặc trong root layout của framework. Thuộc tính async giúp widget tải mà không chặn nội dung chính của trang.
HTML
<body>
<!-- Nội dung website -->
<script
src="https://cdn.assistantcore.com/embed/embed.js"
data-assistant-id="ID_TRỢ_LÝ"
data-api-base="https://api.assistantcore.com"
async
></script>
</body>Next.js
Thêm script vào root layout để tránh tải lại khi chuyển trang:
import Script from "next/script"
export default function RootLayout({ children }) {
return (
<html lang="vi">
<body>{children}</body>
<Script
src="https://cdn.assistantcore.com/embed/embed.js"
data-assistant-id="ID_TRỢ_LÝ"
data-api-base="https://api.assistantcore.com"
strategy="lazyOnload"
/>
</html>
)
}3. Cho phép khách đính kèm tệp (tùy chọn)
Mặc định, khách truy cập website chỉ gửi được văn bản. Để cho phép đính kèm tệp, bật Tệp đính kèm của khách → Cho phép tải tệp lên trên cùng trang. Cài đặt được lưu ngay khi bạn bật hoặc tắt.
- Tệp hỗ trợ: ảnh (PNG, JPEG, GIF, WebP), PDF, Word, Excel, CSV và tệp văn bản.
- Dung lượng tối đa: 25 MB mỗi tệp.
- Tệp được lưu trong workspace của bạn và tính vào mức sử dụng.
Thuộc tính script
| Thuộc tính | Bắt buộc | Mô tả |
|---|---|---|
src | Có | URL loader của widget. Dùng URL do Admin Panel cung cấp. |
data-assistant-id | Có | UUID của trợ lý. |
data-api-base | Có | API origin của môi trường Assistant Core. |
data-lang | Không | Ngôn ngữ giao diện: vi hoặc en. Mặc định tự phát hiện. |
Nếu trang có <html lang="vi">, widget tự chọn Tiếng Việt khi data-lang không được đặt.
Quyền riêng tư
Widget lưu một mã định danh khách truy cập trong local storage và gửi nội dung chat tới trợ lý để xử lý. Trước khi publish:
- Cập nhật privacy policy của website nếu cần.
- Không đưa secret hoặc dữ liệu không được phép xử lý vào tin nhắn thử nghiệm.
- Kiểm tra consent flow theo yêu cầu pháp lý tại thị trường của bạn.
Kiểm tra cài đặt
- Mở website từ đúng origin đã cho phép.
- Kiểm tra nút mở chat xuất hiện.
- Gửi một tin nhắn thử và xác nhận có phản hồi streaming.
- Kiểm tra trên mobile và trong chế độ tối.
Khắc phục sự cố
| Hiện tượng | Cách xử lý |
|---|---|
| Widget không xuất hiện | Kiểm tra script chỉ được thêm một lần và không bị Content Security Policy chặn. |
| Website không được phép | So sánh origin trên thanh địa chỉ với danh sách trong Admin; kiểm tra www, protocol và port. |
| Widget gọi sai môi trường | Sao chép lại snippet từ Admin Panel và kiểm tra data-api-base. |
| Thay đổi origin chưa có hiệu lực | Chọn Lưu thay đổi, reload trang và thử lại. |
Khi deploy preview URL mới, hãy thêm origin mới trước khi gửi link cho QA hoặc khách hàng.