לאסוף ולעבד מידע ממשתמשי Google Chat

במדריך הזה מוסבר איך אפליקציות ב-Google Chat יכולות לאסוף ולעבד מידע ממשתמשים על ידי יצירת נכסי קלט של טפסים בממשקים שמבוססים על כרטיסים.

בתוספים ב-Google Chat, המשתמשים רואים אותם כאפליקציות של Google Chat. מידע נוסף זמין בקטע סקירה כללית על הרחבת Google Chat.

תיבת דו-שיח עם מגוון ווידג'טים שונים.
איור 1: אפליקציית Chat שפותחת תיבת דו-שיח לאיסוף פרטי התקשרות.

אפליקציות צ'אט מבקשות מהמשתמשים מידע כדי לבצע פעולות ב-Chat או מחוץ ל-Chat, כולל בדרכים הבאות:

  • מגדירים את ההגדרות. לדוגמה, כדי לאפשר למשתמשים להתאים אישית את הגדרות ההתראות או להגדיר ולהוסיף את אפליקציית Chat למרחב משותף אחד או יותר.
  • ליצור או לעדכן מידע באפליקציות אחרות של Google Workspace. לדוגמה, אפשר לאפשר למשתמשים ליצור אירוע ביומן Google.
  • לתת למשתמשים גישה למשאבים באפליקציות או בשירותי אינטרנט אחרים ולאפשר להם לעדכן אותם. לדוגמה, אפליקציית Chat יכולה לעזור למשתמשים לעדכן את סטטוס כרטיס התמיכה ישירות ממרחב משותף ב-Chat.

דרישות מוקדמות

Node.js

תוסף ל-Google Workspace שפועל ב-Google Chat. כדי ליצור אחד, תוכלו להיעזר במדריך למתחילים בנושא HTTP.

Apps Script

תוסף ל-Google Workspace שפועל ב-Google Chat. כדי ליצור אחד, תוכלו לעיין במדריך למתחילים ב-Apps Script.

יצירת טפסים באמצעות כרטיסים

כדי לאסוף מידע, אפליקציות ב-Chat מעצבות טפסים ואת מקורות הקלט שלהם, ומטמיעות אותם בכרטיסים. כדי להציג למשתמשים כרטיסים, אפליקציות Chat יכולות להשתמש בממשקי Chat הבאים:

  • הודעות בצ'אט שמכילות כרטיס אחד או יותר.
  • Dialogs, שהם כרטיסים שנפתחים בחלון חדש מהודעות ומדפי בית.

אפליקציות צ'אט יכולות ליצור את הכרטיסים באמצעות הווידג'טים הבאים:

  • ווידג'טים להזנת טופס שמבקשים מידע מהמשתמשים. אפשר גם להוסיף אימות לווידג'טים של קלט בטופס, כדי לוודא שהמשתמשים מזינים את המידע בפורמט הנכון. אפליקציות צ'אט יכולות להשתמש בווידג'טים הבאים להזנת טפסים:

    • קלטי טקסט (textInput) לטקסט חופשי או לטקסט מוצג.
    • מקורות קלט לבחירה (selectionInput) הם רכיבים בממשק המשתמש שאפשר לבחור בהם, כמו תיבות סימון, לחצני בחירה ותפריטים נפתחים. ווידג'טים של קלט לבחירה יכולים גם לאכלס פריטים ממקורות נתונים סטטיים או דינמיים. לדוגמה, המשתמשים יכולים לבחור מתוך רשימה של מרחבים משותפים ב-Chat שהם חברים בהם.

  • ווידג'ט של לחצן כדי שהמשתמשים יוכלו לשלוח את הערכים שהם מזינים בכרטיס. אחרי שמשתמש לוחץ על הלחצן, אפליקציית 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 מטפלת באובייקט האירוע כדי לקבל את הערכים שהמשתמשים מזינים בווידג'טים. בטבלה הבאה מוסבר איך לקבל את הערך של ווידג'ט קלט נתון בטופס. לכל ווידג'ט, בטבלה מוצגים סוג הנתונים שהווידג'ט מקבל, המיקום שבו הערך מאוחסן באובייקט האירוע וערך לדוגמה.

ווידג'ט להזנת קלט בטופס סוג נתוני הקלט הזנת ערך מאובייקט האירוע ערך לדוגמה
textInput stringInputs event.commonEventObject.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs כדי לקבל את הערך הראשון או היחיד, event.commonEventObject.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker שמקבל רק תאריכים. dateInput event.commonEventObject.formInputs.contactBirthdate.dateInput.msSinceEpoch. 1000425600000

העברת נתונים לכרטיס אחר

אחרי שמשתמש שולח מידע מכרטיס, יכול להיות שתצטרכו להחזיר כרטיסים נוספים כדי לבצע אחת מהפעולות הבאות:

  • כדי לעזור למשתמשים למלא טפסים ארוכים, כדאי ליצור קטעים נפרדים.
  • כדאי לאפשר למשתמשים לראות תצוגה מקדימה של המידע מהכרטיס הראשוני ולאשר אותו, כדי שיוכלו לבדוק את התשובות שלהם לפני השליחה.
  • לאכלס באופן דינמי את שאר החלקים בטופס. לדוגמה, כדי להנחות משתמשים ליצור פגישה, אפליקציית 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 שולחת הודעת טקסט כדי לאשר שהיא קיבלה טופס שנשלח מהודעה בכרטיס.

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

כדי לעבד ולסגור תיבת דו-שיח, מחזירים אובייקט RenderActions שמציין אם רוצים לשלוח הודעת אישור, לעדכן את ההודעה או הכרטיס המקוריים או פשוט לסגור את תיבת הדו-שיח. במאמר סגירה של תיבת דו-שיח מוסבר איך לעשות זאת.

פתרון בעיות

כשכרטיס או אפליקציית Google Chat מחזירים שגיאה, בממשק Chat מופיעה ההודעה "משהו השתבש". או "לא ניתן לעבד את הבקשה שלך". לפעמים בממשק המשתמש של Chat לא מוצגת הודעת שגיאה, אבל באפליקציה או בכרטיס של Chat מתקבלת תוצאה לא צפויה. לדוגמה, יכול להיות שלא תוצג הודעה בכרטיס.

יכול להיות שהודעת שגיאה לא תוצג בממשק המשתמש של Chat, אבל כשיומני השגיאות של אפליקציות Chat מופעלים, יהיו זמינות הודעות שגיאה תיאוריות ונתוני יומנים שיעזרו לכם לתקן שגיאות. במאמר פתרון בעיות ושגיאות ב-Google Chat מוסבר איך מציגים, מאתרים באגים ומתקנים שגיאות.