SDK trang web SquareHub cho phép bạn gửi thông tin người dùng bổ sung đến SquareHub.
Nếu bạn đã cài đặt mã của chúng tôi trên trang web, SDK sẽ hiển thị đối tượng window.$squarehub . Để đảm bảo SDK đã được tải hoàn toàn, hãy đảm bảo bạn lắng nghe sự kiện squarehub:ready như sau:
window.addEventListener("squarehub:ready", function () {
// Use window.$squarehub here
// ...
});
Nếu bạn muốn lắng nghe các tin nhắn trong widget, bạn có thể sử dụng sự kiện sau.
window.addEventListener('squarehub:on-message', function(e) {
console.log('squarehub:on-message', e.detail)
})
Cài đặt SDK
Để ẩn bong bóng chat, bạn có thể sử dụng cài đặt được đề cập bên dưới.
Lưu ý: Nếu bạn sử dụng điều này, bạn cũng phải kích hoạt widget.
window.squarehubSettings = {
hideMessageBubble: false,
showUnreadMessagesDialog: false, // Disable the unread message dialog
position: "left", // This can be left or right
locale: "en", // Language to be set
useBrowserLanguage: false, // Set widget language from user's browser
type: "standard", // [standard, expanded_bubble]
darkMode: "auto", // [light, auto]
// baseDomain: "yourdomain.com" // configure if you want to track users across subdomains
};
Tự động sử dụng ngôn ngữ trình duyệt trong live chat widget
Để hiển thị live chat widget theo ngôn ngữ trình duyệt của người dùng, hãy đặt useBrowserLanguage thành true trong window.squarehubSettings đã đề cập ở trên.
Lưu ý: Nếu useBrowserLanguage được đặt thành true, giá trị locale được chỉ định sẽ bị bỏ qua. Nếu ngôn ngữ trình duyệt không được SquareHub hỗ trợ, giá trị locale được chỉ định dưới locale sẽ được sử dụng. Nếu giá trị đó cũng không có, widget sẽ dùng locale của bảng điều khiển nhân viên hỗ trợ.
Chế độ tối
Widget live chat SquareHub hỗ trợ chế độ tối từ phiên bản v2.4.0 trở đi. Để bật chế độ tối, hãy làm theo các bước được đề cập tại đây.
Thiết kế widget
SquareHub hỗ trợ hai thiết kế cho widget.
-
Tiêu chuẩn (mặc định)
-
Bong bóng mở rộng
Nếu bạn đang sử dụng bong bóng mở rộng, bạn có thể tùy chỉnh văn bản hiển thị trong bong bóng bằng cách đặt tham số launcherTitle trong squarehubSettings như mô tả bên dưới.
window.squarehubSettings = {
type: "expanded_bubble",
launcherTitle: "Chat with us",
};
Bật cửa sổ bật ra
Để bật cửa sổ bật ra, hãy thêm cấu hình sau vào squarehubSettings. Tùy chọn này bị tắt theo mặc định.
window.squarehubSettings = {
// ...Other Config
showPopoutButton: true,
}
You can also popout the chat window programatically with the `popoutChatWindow()` method.
Tin nhắn tùy chỉnh
Tùy chỉnh tin nhắn chào mừng và tin nhắn sẵn sàng hỗ trợ hiển thị trong tiêu đề widget và chỉ số trạng thái nhóm.
window.squarehubSettings = {
// ...Other Config
welcomeTitle: "Need help?", // Custom widget header
welcomeDescription: "We're here to support you.", // Header subtitle
availableMessage: "We're online and ready to chat!", // When team is online
unavailableMessage: "We're currently offline." // When team is unavailable
};
Bật/tắt tính năng
Bật hoặc tắt các tính năng giao diện tùy chọn bên trong widget:
window.squarehubSettings = {
// ...Other Config
enableFileUpload: true, // Show file attachment button
enableEmojiPicker: true, // Enable emoji picker in the chat input
enableEndConversation: true // Let users end the conversation
};
Mở cửa sổ bật ra theo chương trình
Bạn có thể mở cửa sổ bật ra theo chương trình bằng phương thức popoutChatWindow() .
Để thực hiện điều này, gọi phương thức như bên dưới.
window.$squarehub.popoutChatWindow();
Bật/tắt hiển thị bong bóng widget
Nếu bạn muốn ẩn/hiện bong bóng widget SquareHub, bạn có thể thực hiện với toggleBubbleVisibility('show/hide')
Ví dụ
window.$squarehub.toggleBubbleVisibility("show"); // to display the bubble
window.$squarehub.toggleBubbleVisibility("hide"); // to hide the bubble
Kích hoạt widget theo chương trình
Nếu bạn muốn mở cửa sổ chat bằng cách nhấp vào một liên kết trên trang web, hãy làm theo phương pháp bên dưới. Trong hành động của bạn, gọi SDK SquareHub như mô tả bên dưới.
window.$squarehub.toggle();
// Toggle widget by passing state
window.$squarehub.toggle("open"); // To open widget
window.$squarehub.toggle("close"); // To close widget
Đặt người dùng trong widget
window.$squarehub.setUser("<unique-identifier-key-of-the-user>", {
email: "<[email protected]>",
name: "<name-of-the-user>",
avatar_url: "<avatar-url-of-the-user>",
phone_number: "<phone-number-of-the-user>",
});
setUser chấp nhận một định danh có thể là user_id trong cơ sở dữ liệu của bạn hoặc bất kỳ tham số duy nhất nào đại diện cho người dùng. Bạn có thể truyền email, name, avatar_url, phone_number làm tham số. Hỗ trợ cho các tham số bổ sung đang được phát triển.
Đảm bảo bạn đặt lại phiên khi người dùng đăng xuất khỏi ứng dụng của bạn.
Xác thực danh tính bằng HMAC
Để ngăn chặn mạo danh và giữ cuộc hội thoại với khách hàng ở chế độ riêng tư, chúng tôi khuyến nghị thiết lập xác thực danh tính trong SquareHub. Xác thực danh tính được bật bằng cách tạo HMAC (mã xác thực tin nhắn dựa trên băm) dựa trên thuộc tính identifier , sử dụng SHA256. Cùng với identifier bạn cũng có thể truyền identifier_hash như minh họa bên dưới để đảm bảo đây là người dùng đúng.
window.$squarehub.setUser(`<unique-identifier-key-of-the-user>`, {
name: "", // Name of the user
avatar_url: "", // Avatar URL
email: "", // Email of the user
identifier_hash: "", // Identifier Hash generated based on the webwidget hmac_token
phone_number: "", // Phone Number of the user
description: "", // description about the user
country_code: "", // Two letter country code
city: "", // City of the user
company_name: "", // company name
social_profiles: {
twitter: "", // Twitter user name
linkedin: "", // LinkedIn user name
facebook: "", // Facebook user name
github: "", // Github user name
},
});
Để tạo HMAC, hãy đọc xác thực danh tính. Lưu ý rằng việc triển khai xác thực HMAC sẽ cho phép lịch sử chat được lưu trữ qua các phiên.
Đặt thuộc tính tùy chỉnh
Để đặt thông tin bổ sung về khách hàng, bạn có thể sử dụng trường thuộc tính tùy chỉnh của khách hàng. Đọc thêm về thuộc tính tùy chỉnh tại đây.
Để đặt thuộc tính tùy chỉnh, gọi setCustomAttributes như sau
window.$squarehub.setCustomAttributes({
accountId: 1,
pricingPlan: "paid",
// Here the key which is already defined in custom attribute
// Value should be based on type (Currently support Number, Date, String and Number)
});
Bạn có thể xem thông tin này trong bảng bên của cuộc hội thoại.
Để xóa thuộc tính tùy chỉnh, sử dụng deleteCustomAttribute như sau
window.$squarehub.deleteCustomAttribute("attribute-key");
Đặt ngôn ngữ thủ công
window.$squarehub.setLocale("en");
Để đặt ngôn ngữ thủ công, sử dụng hàm setLocale .
Đặt nhãn cho cuộc hội thoại
Lưu ý rằng nhãn sẽ được đặt cho cuộc hội thoại nếu người dùng chưa bắt đầu cuộc hội thoại. Trong trường hợp đó, các mục sau sẽ không có hiệu lực:
window.$squarehub.setLabel("support-ticket");
window.$squarehub.removeLabel("support-ticket");
Làm mới phiên (sử dụng khi đăng xuất người dùng khỏi ứng dụng)
window.$squarehub.reset();
Lỗi widget
Để xem các lỗi trong widget, hãy đảm bảo bạn lắng nghe sự kiện squarehub:event như sau:
window.addEventListener("squarehub:error", function () {
// ...
});
Lưu ý: Tính năng này có sẵn trong phiên bản v2.3.0 và các phiên bản sau.
Tùy chỉnh tiêu đề chào mừng và mô tả
Bạn có thể thay đổi:
-
Tiêu đề và mô tả chào mừng
-
Tin nhắn hiển thị khi nhóm của bạn trực tuyến hoặc ngoại tuyến
-
Bật có chọn lọc các tính năng giao diện như tải file, bộ chọn emoji và nút kết thúc cuộc hội thoại
window.squarehubSettings = {
welcomeTitle: 'Need help?',
welcomeDescription: 'We’re here to support you.',
availableMessage: 'We’re online and ready to chat!',
unavailableMessage: 'We’re currently offline.',
enableFileUpload: true,
enableEmojiPicker: true,
enableEndConversation: true
};