Tiện ích website

Tiện ích website đưa khung trò chuyện Genie lên trang web của bạn, chẳng hạn một trang intranet. Khách truy cập trò chuyện được mà không cần đăng nhập Genie; tiện ích trả lời qua một agent do bạn chọn, dựa trên các kho tri thức của agent đó. Bạn tạo tiện ích trong Cài đặt, rồi dán một đoạn mã ngắn vào trang của mình.

Trước khi bắt đầu

Bạn cần vai trò Quản trị viên hoặc Chủ sở hữu để tạo hay sửa tiện ích.
Chọn agent cho tiện ích. Kho tri thức của agent quyết định khách hỏi được về những gì, vì vậy hãy chọn hoặc tạo một agent phù hợp với đối tượng người xem, ví dụ Trợ lý nhân sự cho trang nhân sự. Xem Agent và trợ lý mặc định.
Khách truy cập tiện ích chỉ thấy tài liệu không bị giới hạn. Tài liệu có phân quyền tài liệu không bao giờ xuất hiện trong câu trả lời cho họ.

Tạo tiện ích

Mở Cài đặt → Tiện ích website (trong nhóm Phát hành & tích hợp).
Bấm Kênh nhúng mới. Quá trình thiết lập có năm bước; bấm Tiếp theo để chuyển bước.
Thông tin kênh: chọn Agent đã liên kết, ví dụ Trợ lý nhân sự. Bạn có thể nhập thêm Tên.
Bảo mật: ở Nguồn gốc được phép, nhập địa chỉ của từng website sẽ hiển thị tiện ích, mỗi dòng một địa chỉ, ví dụ https://intranet.contoso.test. Nhập địa chỉ intranet của bạn, không phải địa chỉ Genie. Mục *.contoso.test cho phép mọi tên miền con của contoso.test. Nếu cần, điều chỉnh Số yêu cầu mỗi phút (theo từng địa chỉ IP của khách, mặc định 30) và Giới hạn yêu cầu mỗi ngày (cho cả tiện ích, mặc định 10000).
Khả năng: nhập Lời chào và chọn có hiện Câu hỏi gợi ý, Hiện nút bật/tắt tìm kiếm web và Hiện nút tải tệp lên hay không.
Giao diện: đặt Tiêu đề trang, Tiêu đề đầu trang, Vị trí tiện ích, Ngôn ngữ mặc định (English, Tiếng Việt hoặc Mặc định của trình duyệt / trang chứa) và Màu chủ đạo. Phần Xem trước tiện ích hiển thị kết quả.
Webhook (tùy chọn): nhập Webhook URL trên máy chủ của bạn và Khóa bí mật webhook để nhận sự kiện message_sent cho mỗi câu hỏi và message_received cho mỗi câu trả lời.
Bấm Lưu. Genie tạo tiện ích và mở bước Triển khai.

Cài đặt → Tiện ích website: nơi thêm tiện ích cho một agent và lấy mã nhúng

Thêm tiện ích vào trang

Ở bước Triển khai, trong mục Sao chép mã nhúng, chọn một kiểu nhúng rồi bấm Sao chép mã:

iframe: toàn bộ khung trò chuyện nằm trong một vùng cố định của trang.
Tiện ích: một nút nổi ở góc trang, bấm vào để mở khung trò chuyện.
Chế độ bảo mật (khuyến nghị): nút nổi như trên, nhưng khóa kênh không nằm trong trang.

Với kiểu Tiện ích, dán đoạn mã ngay trước thẻ </body> của trang intranet. Đoạn mã có dạng như sau, trong đó ID kênh và khóa là của bạn:

html

<script src="https://genie.contoso.test/genie-widget.js"
        data-channel="2b9f6c3a-7d41-4e0b-9c2d-8a5e1f0b6d73"
        data-token="em_..."
        data-position="bottom-right"
        data-title="HR assistant"></script>

Giá trị data-token chính là khóa kênh. Bất kỳ ai mở trang đều đọc được giá trị này trong mã nguồn.

Chế độ bảo mật

Ở chế độ bảo mật, khóa kênh nằm trên máy chủ intranet của bạn, còn trang chỉ nhận token ngắn hạn. Hãy dùng chế độ này bất cứ khi nào tiện ích nằm trên website yêu cầu đăng nhập.

Sao chép đoạn mã Chế độ bảo mật. Đoạn mã trỏ tới một địa chỉ trên máy chủ của bạn thay vì chứa khóa:

html

<script src="https://genie.contoso.test/genie-widget.js"
        data-channel="2b9f6c3a-7d41-4e0b-9c2d-8a5e1f0b6d73"
        data-token-endpoint="https://intranet.contoso.test/genie/embed-token"
        data-position="bottom-right"></script>

Trên máy chủ intranet, tạo endpoint tại địa chỉ đó (ở đây là /genie/embed-token). Tiện ích gọi địa chỉ này bằng GET từ trình duyệt của khách, kèm cookie của intranet. Mã của bạn cần:
1. kiểm tra khách đã đăng nhập intranet và được phép dùng tiện ích;
2. đổi khóa kênh lấy một token ngắn hạn:
  bash
```
curl -s -X POST "https://genie.contoso.test/api/v1/embed/2b9f6c3a-7d41-4e0b-9c2d-8a5e1f0b6d73/exchange" \
  -H "Authorization: Embed $GENIE_CHANNEL_KEY" \
  -H "Origin: https://intranet.contoso.test"
```
  Genie trả về {"success":true,"data":{"session_token":"ems_...","expires_in":1800}}. Header Origin phải là một trong các Nguồn gốc được phép của tiện ích.
3. trả {"token":"ems_...","expiresIn":1800} về cho trình duyệt.
Dán đoạn mã vào trang.

Token có hiệu lực 30 phút, và tiện ích tự lấy token mới trước khi hết hạn. Bước Triển khai có sẵn ví dụ đầy đủ về mã phía máy chủ này bằng Node.js và Go.

Sau khi script đã tải xong, trang của bạn có thể gọi:

Genie.setLocale('vi-VN')                                  // chuyển tiện ích sang tiếng Việt ('en-US' cho tiếng Anh)
Genie.openWithQuery('How many days of annual leave do I get?') // mở khung trò chuyện và đặt câu hỏi
Genie.setContext({ page: location.pathname })             // gửi kèm ngữ cảnh của trang với mỗi câu hỏi

Genie.open(), Genie.close() và Genie.toggle() dùng để mở và đóng khung trò chuyện.

Khách truy cập thấy gì và làm được gì

Khách không đăng nhập Genie. Trình duyệt của khách ghi nhớ hội thoại, nên hội thoại vẫn còn khi tải lại trang.
Quản trị viên và Chủ sở hữu của workspace đọc được hội thoại qua tiện ích trong Genie để theo dõi câu hỏi của khách (xem Ai đọc được hội thoại trên các kênh). Hãy cho khách biết điều này ngay trên trang.
Genie chỉ trả lời qua agent đã liên kết và các kho tri thức của agent đó. Trang web không thể đổi agent, kho tri thức hay mô hình.
Câu trả lời chỉ dùng tài liệu không bị giới hạn.
Khách không truy vấn được Cơ sở dữ liệu hay Power BI, và Genie không chạy mã cho họ.
Tìm trên web chỉ dùng được khi agent đã bật tìm kiếm web và bạn đã chọn Hiện nút bật/tắt tìm kiếm web; mặc định tính năng này tắt với từng khách.
Khách chỉ đính kèm được tệp khi bạn đã chọn Hiện nút tải tệp lên và agent hỗ trợ hình ảnh.

Quản lý tiện ích

Khóa kênh: nằm ở cuối bước Triển khai. Bấm Hiện khóa và Sao chép khóa kênh để xem khóa, hoặc Đặt lại khóa kênh nếu khóa bị lộ. Sau khi đặt lại, khóa cũ ngừng hoạt động ngay, nên hãy cập nhật mọi trang và máy chủ đang dùng khóa đó.
Tắt hoặc bật tiện ích: trong danh sách, mở menu của tiện ích và chọn Tắt hoặc Bật, hoặc dùng công tắc Bật kênh trong cài đặt của tiện ích. Tiện ích đã tắt sẽ từ chối mọi yêu cầu.
Xóa: tiện ích trên mọi trang đang nhúng sẽ ngừng hoạt động.

Lưu ý

Hãy coi khóa kênh trong đoạn mã iframe hoặc Tiện ích là công khai: ai vào trang cũng sao chép được. Đừng bao giờ liên kết agent có kho tri thức không dành cho mọi người xem trang đó; luôn đặt Nguồn gốc được phép cùng các giới hạn yêu cầu, và ưu tiên dùng Chế độ bảo mật.
Nguồn gốc được phép ngăn website khác hiển thị tiện ích của bạn trên trình duyệt. Tuy nhiên, cài đặt này không ngăn được người đã sao chép khóa gọi thẳng tới Genie; chỉ chế độ bảo mật và các giới hạn yêu cầu mới làm được điều đó.
Khi một khách vượt Số yêu cầu mỗi phút hoặc cả tiện ích vượt Giới hạn yêu cầu mỗi ngày, Genie tạm thời từ chối yêu cầu.
Câu hỏi qua tiện ích được tính vào hạn mức hằng tháng của workspace, nếu workspace có đặt hạn mức.
Chỉ Quản trị viên và Chủ sở hữu của workspace mới thấy trang Tiện ích website và khóa kênh của các tiện ích.

Tiện ích website ​

Trước khi bắt đầu ​

Tạo tiện ích ​

Thêm tiện ích vào trang ​

Chế độ bảo mật ​

Điều khiển tiện ích từ trang của bạn ​

Khách truy cập thấy gì và làm được gì ​

Quản lý tiện ích ​

Lưu ý ​

Trang liên quan ​