รวบรวมและประมวลผลข้อมูลจากผู้ใช้ Google Chat

คำแนะนำนี้จะอธิบายวิธีที่แอป Google Chat สามารถรวบรวมและประมวลผลข้อมูลจากผู้ใช้โดยการสร้างอินพุตแบบฟอร์มในอินเทอร์เฟซแบบการ์ด

ใน Google Chat ส่วนเสริมจะปรากฏต่อผู้ใช้เป็นแอป Google Chat ดูข้อมูลเพิ่มเติมได้ที่ภาพรวมการขยาย Google Chat

แอปใน Chat จะขอข้อมูลจากผู้ใช้เพื่อดำเนินการในหรือนอก Chat ซึ่งรวมถึงการดำเนินการต่อไปนี้

• กำหนดการตั้งค่า เช่น อนุญาตให้ผู้ใช้ปรับแต่งการตั้งค่าการแจ้งเตือน หรือกำหนดค่าและเพิ่มแอป Chat ไปยังพื้นที่ทำงานอย่างน้อย 1 แห่ง
• สร้างหรืออัปเดตข้อมูลในแอปพลิเคชันอื่นๆ ของ Google Workspace เช่น อนุญาตให้ผู้ใช้สร้างกิจกรรมใน Google ปฏิทิน
• อนุญาตให้ผู้ใช้เข้าถึงและอัปเดตทรัพยากรในแอปหรือบริการเว็บอื่นๆ เช่น แอป Chat ช่วยให้ผู้ใช้อัปเดตสถานะคำขอแจ้งปัญหาได้โดยตรงจากพื้นที่ทำงานใน Chat

ข้อกำหนดเบื้องต้น

สร้างแบบฟอร์มโดยใช้การ์ด

แอปใน Chat จะออกแบบแบบฟอร์มและอินพุตของแบบฟอร์ม รวมถึงสร้างเป็นการ์ดเพื่อรวบรวมข้อมูล หากต้องการแสดงการ์ดต่อผู้ใช้ แอปใน Chat สามารถใช้อินเทอร์เฟซ Chat ต่อไปนี้

• ข้อความใน Chat ที่มีการ์ดอย่างน้อย 1 ใบ
• กล่องโต้ตอบ ซึ่งเป็นการ์ดที่เปิดขึ้นในหน้าต่างใหม่จากข้อความและหน้าแรก

แอปแชทสามารถสร้างการ์ดได้โดยใช้วิดเจ็ตต่อไปนี้

• วิดเจ็ตการป้อนข้อมูลแบบฟอร์มที่ขอข้อมูลจากผู้ใช้ คุณอาจเพิ่มการตรวจสอบเพื่อจัดรูปแบบวิดเจ็ตอินพุตเพื่อให้ผู้ใช้ป้อนและจัดรูปแบบข้อมูลได้อย่างถูกต้อง แอปแชทสามารถใช้วิดเจ็ตการป้อนข้อมูลแบบฟอร์มต่อไปนี้

  • อินพุตข้อความ (textInput) สำหรับข้อความรูปแบบอิสระหรือข้อความที่แนะนำ
  • อินพุตการเลือก (selectionInput) คือองค์ประกอบ UI ที่เลือกได้ เช่น ช่องทําเครื่องหมาย ปุ่มตัวเลือก และเมนูแบบเลื่อนลง วิดเจ็ตการป้อนข้อมูลแบบเลือกยังสร้างรายการจากแหล่งข้อมูลแบบคงที่หรือแบบไดนามิกได้ด้วย เช่น ผู้ใช้สามารถเลือกจากรายการพื้นที่ใน Chat ของตน
  • เครื่องมือเลือกวันที่และเวลา (dateTimePicker) สำหรับรายการวันที่และเวลา

• วิดเจ็ตปุ่มเพื่อให้ผู้ใช้ส่งค่าที่ป้อนในการ์ดได้ หลังจากผู้ใช้คลิกปุ่มแล้ว แอป Chat จะประมวลผลข้อมูลที่รับได้

ในตัวอย่างต่อไปนี้ การ์ดจะรวบรวมข้อมูลติดต่อโดยใช้การป้อนข้อความ เครื่องมือเลือกวันที่และเวลา และอินพุตแบบเลือก

ดูตัวอย่างวิดเจ็ตแบบอินเทอร์แอกทีฟเพิ่มเติมที่คุณสามารถใช้เพื่อรวบรวมข้อมูลได้ที่หัวข้อออกแบบการ์ดหรือกล่องโต้ตอบแบบอินเทอร์แอกทีฟในเอกสารประกอบของ Google Chat API

รับข้อมูลจากวิดเจ็ตแบบอินเทอร์แอกทีฟ

เมื่อใดก็ตามที่ผู้ใช้คลิกปุ่ม แอป Chat ของปุ่มนั้นก็จะทริกเกอร์การดําเนินการพร้อมข้อมูลเกี่ยวกับการโต้ตอบ ใน commonEventObject ของเพย์โหลดเหตุการณ์ ออบเจ็กต์ formInputs จะมีค่าที่ผู้ใช้ป้อน

คุณสามารถดึงค่าจากออบเจ็กต์ commonEventObject.formInputs.WIDGET_NAME โดยที่ WIDGET_NAME คือช่อง name ที่คุณระบุไว้สำหรับวิดเจ็ต ระบบจะแสดงผลค่าเป็นประเภทข้อมูลเฉพาะสำหรับวิดเจ็ต

ต่อไปนี้แสดงส่วนหนึ่งของออบเจ็กต์เหตุการณ์ที่ผู้ใช้ป้อนค่าสําหรับวิดเจ็ตแต่ละรายการ

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

หากต้องการรับข้อมูล แอป Chat จะจัดการออบเจ็กต์เหตุการณ์เพื่อรับค่าที่ผู้ใช้ป้อนลงในวิดเจ็ต ตารางต่อไปนี้แสดงวิธีรับค่าสําหรับวิดเจ็ตการป้อนข้อมูลแบบฟอร์มหนึ่งๆ สําหรับวิดเจ็ตแต่ละรายการ ตารางจะแสดงประเภทข้อมูลที่วิดเจ็ตยอมรับ ตําแหน่งที่จัดเก็บค่าในออบเจ็กต์เหตุการณ์ และค่าตัวอย่าง

โอนข้อมูลไปยังการ์ดอื่น

หลังจากผู้ใช้ส่งข้อมูลจากการ์ดแล้ว คุณอาจต้องส่งการ์ดเพิ่มเติมเพื่อดำเนินการต่อไปนี้

• ช่วยให้ผู้ใช้กรอกแบบฟอร์มที่ยาวขึ้นได้โดยการสร้างส่วนที่แตกต่างกัน
• อนุญาตให้ผู้ใช้ดูตัวอย่างและยืนยันข้อมูลจากการ์ดแรกเพื่อให้ผู้ใช้ตรวจสอบคำตอบก่อนส่งได้
• ป้อนข้อมูลส่วนที่เหลือของแบบฟอร์มแบบไดนามิก ตัวอย่างเช่น หากต้องการแจ้งให้ผู้ใช้สร้างการนัดหมาย แอป Chat อาจแสดงการ์ดแรกเพื่อขอเหตุผลในการนัดหมาย จากนั้นจึงแสดงการ์ดอื่นที่ระบุเวลาว่างตามประเภทการนัดหมาย

หากต้องการโอนข้อมูลที่ป้อนจากการ์ดเริ่มต้น ให้สร้างbutton วิดเจ็ตด้วย actionParameters ที่มี name ของวิดเจ็ตและค่าที่ผู้ใช้ป้อน ดังที่แสดงในตัวอย่างต่อไปนี้

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "submitForm",
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

โดยที่ WIDGET_NAME คือ name ของวิดเจ็ต และ USER_INPUT_VALUE คือสิ่งที่ผู้ใช้ป้อน เช่น สําหรับอินพุตข้อความที่รวบรวมชื่อบุคคล ชื่อวิดเจ็ตคือ contactName และค่าตัวอย่างคือ Kai O

เมื่อผู้ใช้คลิกปุ่ม แอป Chat ของคุณจะได้รับออบเจ็กต์เหตุการณ์ที่คุณสามารถรับข้อมูลได้

ตอบกลับการส่งแบบฟอร์ม

หลังจากได้รับข้อมูลจากข้อความการ์ดหรือกล่องโต้ตอบ แอป Chat จะตอบกลับด้วยการรับทราบหรือแสดงข้อผิดพลาด

ในตัวอย่างต่อไปนี้ แอป Chat ส่งข้อความเพื่อยืนยันว่าได้รับแบบฟอร์มที่ส่งจากข้อความการ์ดเรียบร้อยแล้ว

/**
 * 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."
  }}}}};
}

/**
 * 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."
  }}}}};
}

หากต้องการประมวลผลและปิดกล่องโต้ตอบ ให้แสดงผลออบเจ็กต์ RenderActions ที่ระบุว่าคุณต้องการส่งข้อความยืนยัน อัปเดตข้อความหรือการ์ดต้นฉบับ หรือแค่ปิดกล่องโต้ตอบ โปรดดูขั้นตอนที่หัวข้อปิดกล่องโต้ตอบ

แก้ปัญหา

เมื่อแอป Google Chat หรือการ์ดแสดงข้อผิดพลาด อินเทอร์เฟซของ Chat จะแสดงข้อความว่า "เกิดข้อผิดพลาด" หรือ "ดำเนินการตามคำขอของคุณไม่ได้" บางครั้ง UI ของ Chat ไม่แสดงข้อความแสดงข้อผิดพลาด แต่แอป Chat หรือการ์ดให้ผลลัพธ์ที่ไม่คาดคิด เช่น ข้อความการ์ดอาจไม่ปรากฏ

แม้ว่าข้อความแสดงข้อผิดพลาดอาจไม่แสดงใน UI ของ Chat แต่ข้อความแสดงข้อผิดพลาดที่อธิบายรายละเอียดและข้อมูลบันทึกจะพร้อมให้ใช้งานเพื่อช่วยคุณแก้ไขข้อผิดพลาดเมื่อเปิดการบันทึกข้อผิดพลาดสำหรับแอป Chat หากต้องการความช่วยเหลือในการดู แก้ไขข้อบกพร่อง และแก้ไขข้อผิดพลาด โปรดดูแก้ปัญหาและแก้ไขข้อผิดพลาดของ Google Chat