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 từ người dùng bằng cách tạo các trường nhập biểu mẫu trong giao diện dựa trên thẻ.

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

Các ứng dụng Chat yêu cầu người dùng cung cấp thông tin để thực hiện các hành động trong hoặc ngoài Chat, bao gồm cả các 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 phòng.
  • 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 một phiếu yêu cầu hỗ trợ ngay từ một phòng Chat.

Điều kiện tiên quyết

Node.js

Ứng dụng Google Chat nhận và phản hồi các sự kiện tương tác. Để tạo ứng dụng Chat tương tác bằng dịch vụ HTTP, hãy hoàn tất hướng dẫn bắt đầu nhanh này.

Python

Ứng dụng Google Chat nhận và phản hồi các sự kiện tương tác. Để tạo ứng dụng Chat tương tác bằng dịch vụ HTTP, hãy hoàn tất hướng dẫn bắt đầu nhanh này.

Java

Ứng dụng Google Chat nhận và phản hồi các sự kiện tương tác. Để tạo ứng dụng Chat tương tác bằng dịch vụ HTTP, hãy hoàn tất hướng dẫn bắt đầu nhanh này.

Apps Script

Ứng dụng Google Chat nhận và phản hồi các sự kiện tương tác. Để tạo ứng dụng Chat tương tác trong Apps Script, hãy hoàn tất hướng dẫn bắt đầu nhanh này.

Tạo biểu mẫu bằng thẻ

Để thu thập thông tin, các ứng dụng Chat thiết kế biểu mẫu và trường nhập của biểu mẫu, đồng thời tạo các biểu mẫu này thành thẻ. Để hiển thị thẻ cho người dùng, các ứ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 trên thẻ Trang chủ trong tin nhắn trực tiếp với ứng dụng Chat.
  • Hộp thoại là các thẻ mở ra trong một cửa sổ mới từ tin nhắn và trang chủ.

Các ứng dụng 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 người dùng cung cấp thông tin. Bạn có thể tùy chọn thêm tính năng xác thực vào tiện ích nhập biểu mẫu để đảm bảo người dùng nhập và định dạng thông tin đúng cách. Các ứng dụng Chat có thể sử dụng các tiện ích nhập biểu mẫu sau:

    • Trường nhập văn bản (textInput) cho văn bản dạng tự do hoặc văn bản đề xuất.
    • Trường nhập lựa chọn (selectionInput) là các phần tử giao diện người dùng có thể chọn, 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 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ể sau đó 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 trường nhập văn bản, bộ chọn ngày giờ và trường nhập lựa chọn:

Để xem ví dụ về ứng dụng Chat sử dụng biểu mẫu liên hệ này, hãy xem mã sau:

Node.js

node/contact-form-app/index.js
/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "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
        }
      ]
    }
  }
];

Python

python/contact-form-app/main.py
# The section of the contact card that contains the form input widgets. Used in a dialog and card message.
# To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
CONTACT_FORM_WIDGETS = [
  {
    "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
        }
      ]
    }
  }
]

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
// The section of the contact card that contains the form input widgets. Used in a dialog and card message.
// To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
final static private List<GoogleAppsCardV1Widget> CONTACT_FORM_WIDGETS = List.of(
  new GoogleAppsCardV1Widget().setTextInput(new GoogleAppsCardV1TextInput()
    .setName("contactName")
    .setLabel("First and last name")
    .setType("SINGLE_LINE")),
  new GoogleAppsCardV1Widget().setDateTimePicker(new GoogleAppsCardV1DateTimePicker()
    .setName("contactBirthdate")
    .setLabel("Birthdate")
    .setType("DATE_ONLY")),
  new GoogleAppsCardV1Widget().setSelectionInput(new GoogleAppsCardV1SelectionInput()
    .setName("contactType")
    .setLabel("Contact type")
    .setType("RADIO_BUTTON")
    .setItems(List.of(
      new GoogleAppsCardV1SelectionItem()
        .setText("Work")
        .setValue("Work")
        .setSelected(false),
      new GoogleAppsCardV1SelectionItem()
        .setText("Personal")
        .setValue("Personal")
        .setSelected(false)))));

Apps Script

apps-script/contact-form-app/contactForm.gs
/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "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
        }
      ]
    }
  }
];

Để xem thêm ví dụ về các tiện ích tương tác mà bạn có thể dùng để thu thập thông tin, hãy xem bài viết Thiết kế thẻ hoặc hộp thoại tương tác.

Nhận dữ liệu từ 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, các ứng dụng Chat sẽ nhận được một sự kiện tương tác tuỳ thuộc vào vị trí của nút:

  • Nếu nút nằm trong một tin nhắn hoặc hộp thoại, các ứng dụng Chat sẽ nhận được một CARD_CLICKED sự kiện tương tác chứa thông tin về lượt tương tác đó. Tải trọng của CARD_CLICKED sự kiện tương tác chứa một common.formInputs đối tượng 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 kiểu dữ liệu cụ thể cho tiện ích (được biểu thị dưới dạng một Inputs đối tượng).

    Sau đây là một phần của sự kiện tương tác CARD_CLICKED trong đó người dùng đã nhập 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"]
    }}}
  }}
}

  • Nếu nút nằm trên trang chủ, các ứng dụng Chat sẽ nhận được một SUBMIT_FORM sự kiện tương tác. Tải trọng của sự kiện tương tác chứa một commonEventObject.formInputs đối tượng 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 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 kiểu dữ liệu cụ thể cho tiện ích (được biểu thị dưới dạng một Inputs đối tượng).

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

    HTTP

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

    Apps Script 

    {
  "type": "SUBMIT_FORM",
  "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ý 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. Bảng sau đây cho biết cách lấy 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 kiểu 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 event.common.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs Để lấy giá trị đầu tiên hoặc giá trị duy nhất, event.common.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker chỉ chấp nhận ngày. dateInput event.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:

  • 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 từ thẻ ban đầu để họ có thể xem lại câu trả lời trước khi gửi.
  • Tự động điền sẵ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 một cuộc hẹn, ứng dụng Chat có thể hiển thị một thẻ ban đầu yêu cầu lý do hẹn, sau đó điền 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 button tiện ích bằng actionParameters chứa name của tiện ích và giá trị mà người dùng nhập, như trong ví dụ sau:

Node.js

node/contact-form-app/index.js
buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

Python

python/contact-form-app/main.py
'buttonList': { 'buttons': [{
  'text': "Submit",
  'onClick': { 'action': {
    'function': "submitForm",
    'parameters': [{
      'key': "contactName", 'value': name }, {
      'key': "contactBirthdate", 'value': birthdate }, {
      'key': "contactType", 'value': type
    }]
  }}
}]}

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
new GoogleAppsCardV1Widget().setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
  .setText("Submit")
  .setOnClick(new GoogleAppsCardV1OnClick().setAction(new GoogleAppsCardV1Action()
    .setFunction("submitForm")
    .setParameters(List.of(
      new GoogleAppsCardV1ActionParameter().setKey("contactName").setValue(name),
      new GoogleAppsCardV1ActionParameter().setKey("contactBirthdate").setValue(birthdate),
      new GoogleAppsCardV1ActionParameter().setKey("contactType").setValue(type))))))))));

Apps Script

apps-script/contact-form-app/main.gs
buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

Khi người dùng nhấp vào nút, ứng dụng Chat của bạn sẽ nhận được một CARD_CLICKED sự kiện tương tác mà bạn có thể nhận dữ liệu.

Phản hồi việc gửi biểu mẫu

Sau khi nhận được dữ liệu từ tin nhắn 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 được hoặc trả về lỗi.

Trong ví dụ sau, ứng dụng Chat gửi một tin nhắn văn bản để xác nhận rằng ứng dụng đã nhận được biểu mẫu được gửi từ một hộp thoại hoặc tin nhắn thẻ.

Node.js

node/contact-form-app/index.js
const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
const errorMessage = "Don't forget to name your new contact!";
if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { actionStatus: {
      statusCode: "INVALID_ARGUMENT",
      userFacingMessage: errorMessage
    }}
  }};
}

Python

python/contact-form-app/main.py
contact_name = event.get('common').get('parameters')["contactName"]
# Checks to make sure the user entered a contact name.
# If no name value detected, returns an error message.
error_message = "Don't forget to name your new contact!"
if contact_name == "" and "SUBMIT_DIALOG" == event.get('dialogEventType'):
  return { 'actionResponse': {
    'type': "DIALOG",
    'dialogAction': { 'actionStatus': {
      'statusCode': "INVALID_ARGUMENT",
      'userFacingMessage': error_message
    }}
  }}

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
String contactName = event.at("/common/parameters/contactName").asText();
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
String errorMessage = "Don't forget to name your new contact!";
if (contactName.isEmpty() && event.at("/dialogEventType") != null && "SUBMIT_DIALOG".equals(event.at("/dialogEventType").asText())) {
  return new Message().setActionResponse(new ActionResponse()
    .setType("DIALOG")
    .setDialogAction(new DialogAction().setActionStatus(new ActionStatus()
      .setStatusCode("INVALID_ARGUMENT")
      .setUserFacingMessage(errorMessage))));
}

Apps Script

apps-script/contact-form-app/main.gs
const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
const errorMessage = "Don't forget to name your new contact!";
if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { actionStatus: {
      statusCode: "INVALID_ARGUMENT",
      userFacingMessage: errorMessage
    }}
  }};
}

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

Khắc phục sự cố

Khi ứng dụng hoặc thẻ Google Chat 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 hoặc thẻ Chat lại tạo ra kết quả không mong muốn; ví dụ: tin nhắn thẻ có thể không xuất hiện.

Mặc dù thông báo lỗi có thể không xuất hiện trong giao diện người dùng Chat, nhưng bạn có thể xem các thông báo lỗi mang tính mô tả và dữ liệu nhật ký để giúp khắc phục lỗi khi tính năng ghi nhật ký lỗi cho các ứng dụng Chat được bật. Để được trợ giúp về cách xem, gỡ lỗi và khắc phục lỗi, hãy xem bài viết Khắc phục và sửa lỗi Google Chat.