דף זה תורגם על ידי Cloud Translation API.

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

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

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

**איור 1**: אפליקציה ל-Chat שפותחת תיבת דו-שיח לאיסוף פרטים ליצירת קשר.

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

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

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

HTTP

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

Apps Script

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

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

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

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

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

ווידג'טים של קלט טופס שמבקשים מידע מהמשתמשים. אפשר גם להוסיף אימות לווידג'טים של שדות קלט בטופס, כדי לוודא שהמשתמשים מזינים את המידע בפורמט הנכון. אפליקציות צ'אט יכולות להשתמש בווידג'טים הבאים של קלט טופס:
- קלט טקסט (textInput) לטקסט חופשי או לטקסט מוצע.
- מקורות קלט לבחירה (selectionInput) הם רכיבים בממשק המשתמש שאפשר לבחור, כמו תיבות סימון, לחצני בחירה ותפריטים נפתחים. אמצעי קלט לבחירה יכולים גם לאכלס ולהציע פריטים מנתונים של Google Workspace (כמו מרחב ב-Chat) או ממקור נתונים דינמי. פרטים נוספים זמינים בקטע הוספת תפריט עם אפשרות לבחירה מרובה.
- Date time pickers (dateTimePicker) for date and time entries.
ווידג'ט של לחצן כדי שהמשתמשים יוכלו לשלוח את הערכים שהזינו בכרטיס. אחרי שהמשתמש לוחץ על הלחצן, אפליקציית 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:

JSON

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

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

JSON

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

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

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

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

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

JSON

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

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

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

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

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

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

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

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

Node.js

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

מחליפים את FUNCTION_URL בנקודת הקצה של HTTP ששולחת שאילתות למקור הנתונים החיצוני.

Apps Script

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

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

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

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

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

Node.js

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "FUNCTION_URL", // Must be an `https` endpoint.
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

Apps Script

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

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.

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

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

HTTP

Apps Script

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

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

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

JSON

JSON

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

JSON

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

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

Node.js

Apps Script

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

Node.js

Apps Script

איך עונים על טופס

Node.js

Apps Script

פתרון בעיות

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