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

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

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

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

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

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

Node.js

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

Python

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

Java

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

Apps Script

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

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

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

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

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

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

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

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

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

Node.js

node/contact-form-app/index.js
/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "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
        }
      ]
    }
  }
];

Python

python/contact-form-app/main.py
# The section of the contact card that contains the form input widgets. Used in a dialog and card message.
# To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
CONTACT_FORM_WIDGETS = [
  {
    "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
        }
      ]
    }
  }
]

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
// The section of the contact card that contains the form input widgets. Used in a dialog and card message.
// To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
final static private List<GoogleAppsCardV1Widget> CONTACT_FORM_WIDGETS = List.of(
  new GoogleAppsCardV1Widget().setTextInput(new GoogleAppsCardV1TextInput()
    .setName("contactName")
    .setLabel("First and last name")
    .setType("SINGLE_LINE")),
  new GoogleAppsCardV1Widget().setDateTimePicker(new GoogleAppsCardV1DateTimePicker()
    .setName("contactBirthdate")
    .setLabel("Birthdate")
    .setType("DATE_ONLY")),
  new GoogleAppsCardV1Widget().setSelectionInput(new GoogleAppsCardV1SelectionInput()
    .setName("contactType")
    .setLabel("Contact type")
    .setType("RADIO_BUTTON")
    .setItems(List.of(
      new GoogleAppsCardV1SelectionItem()
        .setText("Work")
        .setValue("Work")
        .setSelected(false),
      new GoogleAppsCardV1SelectionItem()
        .setText("Personal")
        .setValue("Personal")
        .setSelected(false)))));

Apps Script

apps-script/contact-form-app/contactForm.gs
/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "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 מכיל אובייקט common.formInputs עם הערכים שהמשתמש מזין.

אפשר לאחזר את הערכים מהאובייקט common.formInputs.WIDGET_NAME, כאשר WIDGET_NAME הוא השדה name שציינתם לווידג'ט. הערכים מוחזרים כסוג נתונים ספציפי של הווידג'ט (המיוצג כאובייקט Inputs).

בהמשך מוצג קטע מאירוע אינטראקציה מסוג 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 event.common.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs כדי לקבל את הערך הראשון או היחיד, event.common.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker שמקבל רק תאריכים. dateInput event.common.formInputs.contactBirthdate.dateInput.msSinceEpoch. 1000425600000

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

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

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

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

Node.js

node/contact-form-app/index.js
buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

Python

python/contact-form-app/main.py
'buttonList': { 'buttons': [{
  'text': "Submit",
  'onClick': { 'action': {
    'function': "submitForm",
    'parameters': [{
      'key': "contactName", 'value': name }, {
      'key': "contactBirthdate", 'value': birthdate }, {
      'key': "contactType", 'value': type
    }]
  }}
}]}

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
new GoogleAppsCardV1Widget().setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
  .setText("Submit")
  .setOnClick(new GoogleAppsCardV1OnClick().setAction(new GoogleAppsCardV1Action()
    .setFunction("submitForm")
    .setParameters(List.of(
      new GoogleAppsCardV1ActionParameter().setKey("contactName").setValue(name),
      new GoogleAppsCardV1ActionParameter().setKey("contactBirthdate").setValue(birthdate),
      new GoogleAppsCardV1ActionParameter().setKey("contactType").setValue(type))))))))));

Apps Script

apps-script/contact-form-app/main.gs
buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

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

איך עונים לשליחת טופס

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

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

Node.js

node/contact-form-app/index.js
const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
if (!contactName) {
  const errorMessage = "Don't forget to name your new contact!";
  if (event.dialogEventType === "SUBMIT_DIALOG") {
    return { actionResponse: {
      type: "DIALOG",
      dialogAction: { actionStatus: {
        statusCode: "INVALID_ARGUMENT",
        userFacingMessage: errorMessage
      }}
    }};
  } else {
    return {
      privateMessageViewer: event.user,
      text: errorMessage
    };
  }
}

Python

python/contact-form-app/main.py
contact_name = event.get('common').get('parameters')["contactName"]
# Checks to make sure the user entered a contact name.
# If no name value detected, returns an error message.
if contact_name == "":
  error_message = "Don't forget to name your new contact!"
  if "SUBMIT_DIALOG" == event.get('dialogEventType'):
    return { 'actionResponse': {
      'type': "DIALOG",
      'dialogAction': { 'actionStatus': {
        'statusCode': "INVALID_ARGUMENT",
        'userFacingMessage': error_message
      }}
    }}
  else:
    return {
      'privateMessageViewer': event.get('user'),
      'text': error_message
    }

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
String contactName = event.at("/common/parameters/contactName").asText();
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
if (contactName.isEmpty()) {
  String errorMessage = "Don't forget to name your new contact!";
  if (event.at("/dialogEventType") != null && "SUBMIT_DIALOG".equals(event.at("/dialogEventType").asText())) {
    return new Message().setActionResponse(new ActionResponse()
      .setType("DIALOG")
      .setDialogAction(new DialogAction().setActionStatus(new ActionStatus()
        .setStatusCode("INVALID_ARGUMENT")
        .setUserFacingMessage(errorMessage))));
  } else {
    return new Message()
      .setPrivateMessageViewer(new User().setName(event.at("/user/name").asText()))
      .setText(errorMessage);
  }
}

Apps Script

apps-script/contact-form-app/main.gs
const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
if (!contactName) {
  const errorMessage = "Don't forget to name your new contact!";
  if (event.dialogEventType === "SUBMIT_DIALOG") {
    return { actionResponse: {
      type: "DIALOG",
      dialogAction: { actionStatus: {
        statusCode: "INVALID_ARGUMENT",
        userFacingMessage: errorMessage
      }}
    }};
  } else {
    return {
      privateMessageViewer: event.user,
      text: errorMessage
    };
  }
}

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

פתרון בעיות

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

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