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

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

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

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

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

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

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

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

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

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

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

  • קלטי טקסט (textInput) לטקסט חופשי או לטקסט מוצג.

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

  • בוררי תאריך ושעה (dateTimePicker) לרשומות של תאריך ושעה.

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

בדוגמה הבאה, כרטיס אוסף פרטי איש קשר באמצעות קלט טקסט, בורר תאריך ושעה וקלט בחירה:

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

הוספת תפריט לבחירת מספר פריטים

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

אפשר לאכלס פריטים בתפריט עם אפשרות לבחירת כמה פריטים ממקורות הנתונים הבאים:

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

איך מאכלסים פריטים ממקור נתונים של Google Workspace

כדי להשתמש במקורות נתונים של Google Workspace, צריך לציין את השדה platformDataSource בווידג'ט SelectionInput. בניגוד לסוגים אחרים של קלט של אפשרויות בחירה, צריך להשמיט אובייקטים מסוג SelectionItem, כי הפריטים האלה של אפשרויות הבחירה מגיעים באופן דינמי מ-Google Workspace.

בקוד הבא מוצג תפריט של משתמשי Google Workspace לבחירת כמה משתמשים בו-זמנית. כדי לאכלס משתמשים, קלט הבחירה מגדיר את commonDataSource כ-USER:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

הקוד הבא מציג תפריט לבחירת כמה מרחבים משותפים ב-Chat. כדי לאכלס את המרחבים, מזינים את השדה hostAppDataSource בתור קלט הבחירה. תפריט הבחירה בכמה פריטים מגדיר גם את defaultToCurrentSpace כ-true, כך שהמרחב המשותף הנוכחי יהיה ברירת המחדל בתפריט:

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

איך מאכלסים פריטים ממקור נתונים חיצוני

אפשר גם לאכלס פריטים מתפריט עם בחירה מרובה ממקור נתונים חיצוני או מצד שלישי. כדי להשתמש במקור נתונים חיצוני, מציינים את השדה externalDataSource בווידג'ט SelectionInput שמכיל את הפונקציה ששולחת שאילתות למקור הנתונים ומחזירה פריטים ממנו.

כדי לצמצם את הבקשות למקור נתונים חיצוני, אפשר לכלול הצעות לפריטים שיופיעו בתפריט לבחירת מספר פריטים לפני שהמשתמשים יטפסו בתפריט. לדוגמה, אפשר לאכלס את אנשי הקשר שהמשתמש חיפש לאחרונה. כדי לאכלס הצעות לפריטים ממקור נתונים חיצוני, מציינים אובייקטים סטטיים מסוג SelectionItem.

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

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "externalDataSource": { "function": "FUNCTION" },
    // Suggested items loaded by default.
    // The list is static here but it could be dynamic.
    "items": [FUNCTION]
  }
}

מחליפים את FUNCTION בכתובת ה-URL של ה-HTTP או בשם הפונקציה ב-Apps Script שמפעילה שאילתה במסד הנתונים החיצוני. לדוגמה מלאה שמראה איך להחזיר הצעות לפריטים, אפשר לעיין בקטע הצעת פריטים לבחירה בכמה אפשרויות.

קבלת נתונים מווידג'טים אינטראקטיביים

בכל פעם שמשתמשים לוחצים על לחצן, הפעולה שלו באפליקציות 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 מקבלת נתונים, היא יכולה לבצע את הפעולות הבאות:

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

הצעות לפריטים לבחירה מרובה

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

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

1. טיפול באובייקט אירוע, שאפליקציית Chat מקבלת כשמשתמשים מקלידים בתפריט.
2. מאובייקט האירוע, מקבלים את הערך שהמשתמש מקלידים, שמיוצג בשדה event.commonEventObject.parameters["autocomplete_widget_query"].
3. שולחים שאילתה למקור הנתונים באמצעות ערך הקלט של המשתמש כדי לקבל SelectionItems אחד או יותר להצעה למשתמש.
4. כדי להחזיר את הפריטים המוצעים, מחזירים את הפעולה RenderActions עם אובייקט modifyCard.

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

/**
 * Google Cloud Function that responds to events sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.selectionInput = function selectionInput(req, res) {
  if (req.method === 'GET' || !req.body.chat) {
    return res.send('Hello! This function is meant to be used ' +
        'in a Google Chat Space.');
  }
  // Stores the Google Chat event
  const chatEvent = req.body.chat;

  // Handle user interaction with multiselect.
  if(chatEvent.widgetUpdatedPayload) {
    return res.send(queryContacts(req.body));
  }
  // Replies with a card that contains the multiselect menu.
  return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "FUNCTION_URL" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}});
};

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a selection item in the menu.
 */
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

/**
* Responds to a Message trigger in Google Chat.
*
* @param {Object} event the event object from Google Chat
* @return {Object} Response from the Chat app.
*/
function onMessage(event) {
  // Replies with a card that contains the multiselect menu.
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "queryContacts" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact"3")]
        }
      }]}]}
    }]
  }}}}};
}

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the interactive event.
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
* Generate a suggested contact given an ID.
*
* @param {String} id The ID of the contact to return.
* @return {Object} The contact formatted as a selection item in the menu.
*/
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

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

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

• כדי לעזור למשתמשים למלא טפסים ארוכים, כדאי ליצור קטעים נפרדים.
• כדאי לאפשר למשתמשים לראות תצוגה מקדימה של המידע מהכרטיס הראשוני ולאשר אותו, כדי שיוכלו לבדוק את התשובות שלהם לפני השליחה.
• לאכלס באופן דינמי את שאר החלקים בטופס. לדוגמה, כדי להנחות משתמשים ליצור פגישה, אפליקציית 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 payloads in the event object
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(chatMessage, chatEvent.user));
  // Handle button clicks on the card
  } 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 מופיעה ההודעה "משהו השתבש". או "לא ניתן לעבד את הבקשה שלך". לפעמים בממשק המשתמש של Chat לא מוצגת הודעת שגיאה, אבל באפליקציה או בכרטיס של Chat מתקבלת תוצאה לא צפויה. לדוגמה, יכול להיות שלא תוצג הודעה בכרטיס.

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