Thu thập và xử lý thông tin của người dùng Google Chat

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ẻ.

Hộp thoại có nhiều tiện ích khác nhau.
Hình 1: Một ứng dụng Chat mẫu mở một hộp thoại để thu thập thông tin liên hệ.

Ứ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:

  • Thiết lập các 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 một 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

Một ứng dụng Google Chat đã bật các tính năng tương tác. Để tạo một ứng dụng Chat tương tác, hãy hoàn thành một trong các bước bắt đầu nhanh sau đây trên cấu trúc ứng dụng mà bạn muốn sử dụng:

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 chứa một hoặc nhiều thẻ.
  • Trang chủ là một thẻ xuất hiện trong thẻ Trang chủ trong tin nhắn trực tiếp bằng ứng dụng Chat.
  • Hộp thoại, là các thẻ sẽ mở ra trong cửa sổ mới từ tin nhắn và trang chủ.

Các ứng dụng trong Chat có thể tạo thẻ bằng các tiện ích sau:

  • Tiện ích nhập biểu mẫu yêu cầu thông tin từ người dùng. 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 của phần lựa chọn (selectionInput) là các phần tử trên giao diện người dùng có thể chọn, chẳng hạn như hộp đánh dấu, 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 (dateTimePicker) cho các mục nhập ngày và giờ.

  • 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, ứng dụng Chat có thể xử lý thông tin nhận được.

Dưới đây là một thẻ bao gồm ba loại ngày và mục nhập thời gian:

Để xem 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, xem Thiết kế một thẻ hoặc hộp thoại tương tác.

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, ứng dụng Chat sẽ nhận được một sự kiện tương tác CARD_CLICKED chứa thông tin về lượt tương tác đó. Trọng tải của các sự kiện tương tác CARD_CLICKED chứa một đối tượng common.formInputs với 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 common.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 (được biểu thị dưới dạng đối tượng Inputs). Trong ví dụ sau, thẻ thu thập thông tin liên hệ bằng cách sử dụng tin nhắn dữ liệu đầu vào, bộ chọn ngày giờ và tiện ích nhập lựa chọn:

{
  "textInput": {
    "name": "contactName",
    "label": "First and last name",
    "type": "SINGLE_LINE"
  }
}, {
  "dateTimePicker": {
    "name": "contactBirthdate",
    "label": "Birthdate",
    "type": "DATE_ONLY"
  }
}, {
  "selectionInput": {
    "name": "contactType",
    "label": "Contact type",
    "type": "RADIO_BUTTON",
    "items": [
      {
        "text": "Work",
        "value": "Work",
        "selected": false
      },
      {
        "text": "Personal",
        "value": "Personal",
        "selected": false
      }
    ]
  }
}

Xử lý sự kiện tương tác

Khi người dùng nhập dữ liệu vào một thẻ hoặc hộp thoại, ứng dụng Chat sẽ nhận được một sự kiện tương tác CARD_CLICKED của ứng dụng Chat chứa các giá trị do người dùng nhập.

Dưới đây là một phần của sự kiện tương tác CARD_CLICKED trong đó người dùng đã nhập các giá trị cho từng tiện ích:

HTTP

{
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

Apps Script 

{
  "type": "CARD_CLICKED",
  "common": { "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ý sự kiện tương tác để lấy các giá trị mà người dùng nhập vào tiện ích. Nội dung sau đây bảng cho biết cách nhận giá trị cho một tiện ích nhập biểu mẫu nhất định. Đối với mỗi tiện ích, bảng này cho biết loại dữ liệu mà tiện ích chấp nhận, nơi lưu trữ giá trị trong sự kiện tương tác và giá trị mẫu.

Tiện ích nhập biểu mẫu Loại dữ liệu đầu vào Giá trị đầu vào từ sự kiện tương tác Giá trị mẫu
textInput stringInputs events.common.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs Để nhận giá trị đầu tiên hoặc duy nhất, events.common.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker chỉ chấp nhận ngày. dateInput events.common.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:

  • Hãy giúp người dùng hoàn thành các biểu mẫu dài hơn bằng cách tạo các mục 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.
  • Linh độ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 phù hợp 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": "openNextCard",
          "parameters": [{
            "key": "WIDGET_NAME",
            "value": "USER_INPUT_VALUE"
          }]
        }
      }
    }]
  }
}

Trong đó WIDGET_NAME là name của tiện ích và USER_INPUT_VALUE là giá trị mà người dùng nhập vào. 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 sự kiện tương tác CARD_CLICKED. Để truy xuất các giá trị, bạn có thể sử dụng phương thức event.common.parameters .

Sau đây là ví dụ về cách bạn có thể truyền các tham số chứa dữ liệu đầu vào của người dùng đến một hàm mở thẻ tiếp theo:

Node.js

// Respond to button clicks on cards or dialogs
if (event.type === "CARD_CLICKED") {

  // Open another card.
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    openNextCard(event);
  }
}

Python

  # Respond to button clicks on cards or dialogs
  if request.get('type') == 'CARD_CLICKED':
    if invoked_function := request.get('common', dict()).get('invokedFunction'):
      if invoked_function == 'open_next_card':
        parameters = request.get('common', dict()).get('parameters'),
        return open_next_card(parameters)

Apps Script 

// Respond to button clicks on cards or dialogs
function onCardClick(event) {
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    return openNextCard(parameters);
  }
}

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 gửi tin nhắn văn bản để xác nhận rằng trang web đó đã nhận thành công biểu mẫu được gửi từ thông báo trên thẻ.

Apps Script 

function submitCardForm(contactName, contactBirthdate, contactType) {
    return {
      "text": "You entered the following contact information:\n\n" +
      "*Name:* " + contactName + "\n" +
      "*Birthdate:* " + contactBirthdate + "\n" +
      "*Type:* " + contactType
      }
}

Để xử lý và đóng hộp thoại, hãy trả về một ActionResponse đối tượng chỉ định xem bạn có muốn gửi thông báo xác nhận hay không, hãy cập nhật của thư hoặc thẻ ban đầu hay chỉ cần đóng hộp thoại. Để biết các bước thực hiện, hãy xem Đóng hộp thoại.

Khắc phục sự cố

Khi một ứng dụng Google Chat hoặc card trả về một lỗi, thì phương thức Giao diện Chat hiển thị một thông báo với nội dung "Đã 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 của Chat không hiện thông báo lỗi nào ngoài ứng dụng Chat hoặc thẻ 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à sửa lỗi, hãy xem Khắc phục lỗi và khắc phục lỗi của Google Chat.