# Cách gửi thông tin người dùng bổ sung đến SquareHub bằng SDK?

> Tami · Cập nhật lần cuối ngày 24 thg 7, 2025

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[​](https://docs.squareomni.com/docs/product/channels/live-chat/sdk/setup#sdk-settings "Direct link to heading")

Để ẩ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[​](https://docs.squareomni.com/docs/product/channels/live-chat/sdk/setup#dark-mode "Direct link to heading")

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](https://docs.squareomni.com/docs/product/channels/live-chat/sdk/live-chat-dark-mode).

### Thiết kế widget[​](https://docs.squareomni.com/docs/product/channels/live-chat/sdk/setup#widget-designs "Direct link to heading")

SquareHub hỗ trợ hai thiết kế cho widget.

1.  Tiêu chuẩn (mặc định)
    
2.  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[​](https://docs.squareomni.com/docs/product/channels/live-chat/sdk/setup#enable-popout-window "Direct link to heading")

Để 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[​](https://docs.squareomni.com/docs/product/channels/live-chat/sdk/setup#enable-popout-window "Direct link to heading")

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[​](https://docs.squareomni.com/docs/product/channels/live-chat/sdk/setup#programatically-open-the-popout-window "Direct link to heading")

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[​](https://docs.squareomni.com/docs/product/channels/live-chat/sdk/setup#toggle-the-widget-bubble-visibility "Direct link to heading")

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[​](https://docs.squareomni.com/docs/product/channels/live-chat/sdk/setup#set-the-user-in-the-widget "Direct link to heading")

```
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[​](https://docs.squareomni.com/docs/product/channels/live-chat/sdk/setup#identity-validation-using-hmac "Direct link to heading")

Để 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](https://docs.squareomni.com/docs/product/channels/live-chat/sdk/identity-validation). 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[​](https://docs.squareomni.com/docs/product/channels/live-chat/sdk/setup#set-custom-attributes "Direct link to heading")

Để đặ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](https://docs.squareomni.com/hc/squarehub-user-guide-cloud-version/en/features-explained/470).

Để đặ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[​](https://docs.squareomni.com/docs/product/channels/live-chat/sdk/setup#set-language-manually "Direct link to heading")

```
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[​](https://docs.squareomni.com/docs/product/channels/live-chat/sdk/setup#set-labels-on-the-conversation "Direct link to heading")

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)[​](https://docs.squareomni.com/docs/product/channels/live-chat/sdk/setup#refresh-the-session-use-this-while-you-logout-the-user-from-your-app "Direct link to heading")

```
window.$squarehub.reset();
```

### Lỗi widget[​](https://docs.squareomni.com/docs/product/channels/live-chat/sdk/setup#widget-errors "Direct link to heading")

Để 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
 };
```