Hướng dẫn này mô tả cách các ứng dụng Google Chat có thể thu thập và xử lý thông tin của người dùng bằng cách tạo dữ liệu đầu vào của biểu mẫu trong giao diện dựa trên thẻ.
Trong Google Chat, các tiện ích bổ sung sẽ xuất hiện với người dùng dưới dạng ứng dụng Google Chat. Để tìm hiểu thêm, hãy xem bài viết Tổng quan về việc mở rộng Google Chat.
Ứng dụng nhắn tin yêu cầu người dùng cung cấp thông tin để thực hiện các thao tác trong hoặc ngoài ứng dụng Chat, bao gồm cả những cách sau:
- Định cấu hình chế độ cài đặt. Ví dụ: để cho phép người dùng tuỳ chỉnh chế độ cài đặt thông báo hoặc định cấu hình và thêm ứng dụng Chat vào một hoặc nhiều không gian.
- Tạo hoặc cập nhật thông tin trong các ứng dụng khác của Google Workspace. Ví dụ: cho phép người dùng tạo sự kiện trên Lịch Google.
- Cho phép người dùng truy cập và cập nhật tài nguyên trong các ứng dụng hoặc dịch vụ web khác. Ví dụ: ứng dụng Chat có thể giúp người dùng cập nhật trạng thái của phiếu yêu cầu hỗ trợ ngay trong không gian Chat.
Điều kiện tiên quyết
Node.js
Một tiện ích bổ sung của Google Workspace hoạt động trong Google Chat. Để tạo một ứng dụng, hãy hoàn tất phần Bắt đầu nhanh về HTTP.
Apps Script
Một tiện ích bổ sung của Google Workspace hoạt động trong Google Chat. Để tạo một ứng dụng, hãy hoàn tất phần Bắt đầu nhanh với Apps Script.
Tạo biểu mẫu bằng thẻ
Để thu thập thông tin, các ứng dụng Chat thiết kế các biểu mẫu và dữ liệu đầu vào, đồng thời tạo các biểu mẫu đó thành thẻ. Để hiển thị thẻ cho người dùng, ứng dụng Chat có thể sử dụng các giao diện Chat sau:
- Tin nhắn trò chuyện chứa một hoặc nhiều thẻ.
- Hộp thoại là các thẻ mở trong một cửa sổ mới từ tin nhắn và trang chủ.
Ứng dụng trò chuyện có thể tạo thẻ bằng các tiện ích sau:
Tiện ích nhập dữ liệu biểu mẫu yêu cầu người dùng cung cấp thông tin. Bạn có thể thêm tính năng xác thực vào các tiện ích nhập để đảm bảo người dùng nhập và định dạng thông tin chính xác. Ứng dụng trò chuyện có thể sử dụng các tiện ích nhập dữ liệu dạng biểu mẫu sau:
- Thành phần nhập văn bản (
textInput) cho văn bản tự do hoặc văn bản đề xuất. - Dữ liệu đầu vào lựa chọn (
selectionInput) là các thành phần trên giao diện người dùng có thể chọn được, chẳng hạn như hộp đánh dấu, nút chọn và trình đơn thả xuống. Tiện ích nhập lựa chọn cũng có thể điền các mục từ nguồn dữ liệu tĩnh hoặc động. Ví dụ: người dùng có thể chọn trong danh sách các phòng Chat mà họ là thành viên.
- Bộ chọn ngày giờ (
dateTimePicker) cho các mục nhập ngày và giờ.
- Thành phần nhập văn bản (
Tiện ích nút để người dùng có thể gửi các giá trị mà họ đã nhập vào thẻ. Sau khi người dùng nhấp vào nút này, ứng dụng Chat có thể xử lý thông tin mà ứng dụng nhận được.
Trong ví dụ sau, một thẻ thu thập thông tin liên hệ bằng cách sử dụng phương thức nhập văn bản, bộ chọn ngày giờ và phương thức nhập lựa chọn:
Để biết thêm ví dụ về các tiện ích tương tác mà bạn có thể sử dụng để thu thập thông tin, hãy xem phần Thiết kế thẻ hoặc hộp thoại tương tác trong tài liệu về API Google Chat.
Nhận dữ liệu từ các tiện ích tương tác
Bất cứ khi nào người dùng nhấp vào một nút, hành động của ứng dụng Chat sẽ được kích hoạt bằng thông tin về lượt tương tác đó. Trong commonEventObject của tải trọng sự kiện, đối tượng formInputs chứa mọi giá trị mà người dùng nhập.
Bạn có thể truy xuất các giá trị từ đối tượng commonEventObject.formInputs.WIDGET_NAME, trong đó WIDGET_NAME là trường name mà bạn đã chỉ định cho tiện ích.
Các giá trị được trả về dưới dạng một loại dữ liệu cụ thể cho tiện ích.
Phần sau đây cho thấy một phần của đối tượng sự kiện mà người dùng đã nhập giá trị cho mỗi tiện ích:
{
"commonEventObject": { "formInputs": {
"contactName": { "stringInputs": {
"value": ["Kai 0"]
}},
"contactBirthdate": { "dateInput": {
"msSinceEpoch": 1000425600000
}},
"contactType": { "stringInputs": {
"value": ["Personal"]
}}
}}
}
Để nhận dữ liệu, ứng dụng Chat của bạn sẽ xử lý đối tượng sự kiện để lấy các giá trị mà người dùng nhập vào tiện ích. Bảng sau đây cho biết cách lấy giá trị cho một tiện ích nhập dữ liệu dạng nhất định. Đối với mỗi tiện ích, bảng cho biết loại dữ liệu mà tiện ích chấp nhận, nơi lưu trữ giá trị trong đối tượng sự kiện và giá trị mẫu.
| Tiện ích nhập dữ liệu vào biểu mẫu | Loại dữ liệu đầu vào | Giá trị đầu vào từ đối tượng sự kiện | Giá trị mẫu |
|---|---|---|---|
textInput |
stringInputs |
event.commonEventObject.formInputs.contactName.stringInputs.value[0] |
Kai O |
selectionInput |
stringInputs |
Để lấy giá trị đầu tiên hoặc giá trị duy nhất, event.commonEventObject.formInputs.contactType.stringInputs.value[0] |
Personal |
dateTimePicker chỉ chấp nhận ngày. |
dateInput |
event.commonEventObject.formInputs.contactBirthdate.dateInput.msSinceEpoch. |
1000425600000 |
Chuyển dữ liệu sang thẻ khác
Sau khi người dùng gửi thông tin từ một thẻ, bạn có thể cần trả về các thẻ bổ sung để thực hiện bất kỳ thao tác nào sau đây:
- Giúp người dùng hoàn tất các biểu mẫu dài hơn bằng cách tạo các phần riêng biệt.
- Cho phép người dùng xem trước và xác nhận thông tin trên thẻ ban đầu để họ có thể xem lại câu trả lời trước khi gửi.
- Tự động điền các phần còn lại của biểu mẫu. Ví dụ: để nhắc người dùng tạo cuộc hẹn, ứng dụng Chat có thể hiển thị một thẻ ban đầu yêu cầu lý do của cuộc hẹn, sau đó điền vào một thẻ khác cung cấp thời gian có sẵn dựa trên loại cuộc hẹn.
Để chuyển dữ liệu đầu vào từ thẻ ban đầu, bạn có thể tạo tiện ích button bằng actionParameters chứa name của tiện ích và giá trị mà người dùng nhập, như minh hoạ trong ví dụ sau:
{
"buttonList": { "buttons": [{
"text": "Submit",
"onClick": { "action": {
"function": "submitForm",
"parameters": [
{
"key": "WIDGET_NAME",
"value": "USER_INPUT_VALUE"
},
// Can specify multiple parameters
]
}}
}]}
}
Trong đó WIDGET_NAME là name của tiện ích và USER_INPUT_VALUE là nội dung mà người dùng nhập. Ví dụ: đối với một mục nhập văn bản thu thập tên của một người, tên tiện ích là contactName và giá trị mẫu là Kai O.
Khi người dùng nhấp vào nút này, ứng dụng Chat sẽ nhận được một đối tượng sự kiện mà bạn có thể nhận dữ liệu từ đó.
Phản hồi nội dung gửi qua biểu mẫu
Sau khi nhận được dữ liệu từ một thông báo thẻ hoặc hộp thoại, ứng dụng Chat sẽ phản hồi bằng cách xác nhận đã nhận hoặc trả về lỗi.
Trong ví dụ sau, ứng dụng Chat sẽ gửi một thông báo văn bản để xác nhận rằng ứng dụng đã nhận được thành công một biểu mẫu được gửi từ thông báo thẻ.
Node.js
/**
* Google Cloud Function that handles all Google Workspace Add On events for
* the contact manager app.
*
* @param {Object} req Request sent from Google Chat space
* @param {Object} res Response to send back
*/
exports.contactManager = function contactManager(req, res) {
const chatEvent = req.body.chat;
const chatMessage = chatEvent.messagePayload.message;
// Handle MESSAGE events
if(chatEvent.messagePayload) {
return res.send(handleMessage(chatMessage, chatEvent.user));
// Handle CARD_CLICKED events
} else if(chatEvent.buttonClickedPayload) {
switch(req.body.commonEventObject.parameters.actionName) {
case "openDialog":
return res.send(openDialog());
case "openNextCard":
return res.send(openNextCard(req.body));
case "submitForm":
return res.send(submitForm(req.body));
}
}
};
/**
* Submits information from a dialog or card message.
*
* @param {Object} event the interactive event with form inputs.
* @return {Object} a message response that posts a private message.
*/
function submitForm(event) {
const chatUser = event.chat.user;
const contactName = event.commonEventObject.parameters["contactName"];
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
privateMessageViewer: chatUser,
text: "✅ " + contactName + " has been added to your contacts."
}}}}};
}
Apps Script
/**
* Sends private text message that confirms submission.
*
* @param {Object} event the interactive event with form inputs.
* @return {Object} a message response that posts a private message.
*/
function submitForm(event) {
const chatUser = event.chat.user;
const contactName = event.commonEventObject.parameters["contactName"];
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
privateMessageViewer: chatUser,
text: "✅ " + contactName + " has been added to your contacts."
}}}}};
}
Để xử lý và đóng hộp thoại, bạn trả về một đối tượng RenderActions chỉ định xem bạn có muốn gửi thông báo xác nhận, cập nhật thông báo hoặc thẻ ban đầu hay chỉ đóng hộp thoại. Để biết các bước, hãy xem phần Đóng hộp thoại.
Khắc phục sự cố
Khi ứng dụng Google Chat hoặc thẻ trả về lỗi, giao diện Chat sẽ hiển thị thông báo "Đã xảy ra lỗi". hoặc "Không thể xử lý yêu cầu của bạn". Đôi khi, giao diện người dùng Chat không hiển thị thông báo lỗi nào, nhưng ứng dụng Chat hoặc thẻ lại tạo ra kết quả không mong muốn; ví dụ: thông báo thẻ có thể không xuất hiện.
Mặc dù thông báo lỗi có thể không hiển thị trong giao diện người dùng Chat, nhưng bạn có thể xem thông báo lỗi mô tả và dữ liệu nhật ký để khắc phục lỗi khi bật tính năng ghi nhật ký lỗi cho ứng dụng Chat. Để được trợ giúp xem, gỡ lỗi và khắc phục lỗi, hãy xem bài viết Khắc phục và khắc phục lỗi Google Chat.