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

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

กล่องโต้ตอบที่มีวิดเจ็ตต่างๆ มากมาย
รูปที่ 1: A ตัวอย่าง แอปแชทที่ จะเปิดกล่องโต้ตอบเพื่อรวบรวมข้อมูลติดต่อ

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

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

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

แอป Google Chat ที่เปิดใช้ฟีเจอร์แบบอินเทอร์แอกทีฟ วิธีสร้าง แอป Chat แบบอินเทอร์แอกทีฟ ทำตามการเริ่มต้นใช้งานอย่างรวดเร็วต่อไปนี้ เกี่ยวกับสถาปัตยกรรมแอปที่คุณต้องการใช้

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

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

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

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

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

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

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

ตัวอย่างต่อไปนี้แสดงการ์ดที่มีอินพุตวันที่และเวลา 3 ประเภท ได้แก่

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

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

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

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

{
  "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
      }
    ]
  }
}

จัดการเหตุการณ์การโต้ตอบ

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

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

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"]
    }}}
  }}
}

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

วิดเจ็ตการป้อนข้อมูลในแบบฟอร์ม ประเภทข้อมูลอินพุต ป้อนค่าจากเหตุการณ์การโต้ตอบ ค่าตัวอย่าง
textInput stringInputs events.common.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs หากต้องการรับค่าแรกหรือค่าเดียว ให้ใช้ events.common.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker ที่ยอมรับเฉพาะวันที่ dateInput events.common.formInputs.contactBirthdate.dateInput.msSinceEpoch 1000425600000

โอนข้อมูลไปยังบัตรอื่น

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

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

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

{
  "buttonList": {
    "buttons": [{
      "text": "Submit",
      "onClick": {
        "action": {
          "function": "openNextCard",
          "parameters": [{
            "key": "WIDGET_NAME",
            "value": "USER_INPUT_VALUE"
          }]
        }
      }
    }]
  }
}

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

เมื่อผู้ใช้คลิกปุ่ม แอป Chat ของคุณจะได้รับ CARD_CLICKEDเหตุการณ์การโต้ตอบ หากต้องการดึงค่า คุณสามารถใช้ event.common.parameters ออบเจ็กต์

ตัวอย่างต่อไปนี้แสดงวิธีส่งพารามิเตอร์ที่มีข้อมูลอินพุตของผู้ใช้ไปยังฟังก์ชันที่เปิดการ์ดถัดไป

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);
  }
}

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

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

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

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
      }
}

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

แก้ปัญหา

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

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