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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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