לאסוף ולעבד מידע ממשתמשי 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

הצגת הקוד ב-GitHub

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

הצגת הקוד ב-GitHub

# 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

הצגת הקוד ב-GitHub

// 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

הצגת הקוד ב-GitHub

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

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

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

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

חשוב: אם אפליקציית Chat נוצרה באמצעות Apps Script, צריך להוסיף את הערך [""] אחרי שם הווידג'ט, לדוגמה formInputs.contactName[""].stringInputs.value[0].

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

הצגת הקוד ב-GitHub

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

הצגת הקוד ב-GitHub

'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

הצגת הקוד ב-GitHub

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

הצגת הקוד ב-GitHub

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

הצגת הקוד ב-GitHub

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

הצגת הקוד ב-GitHub

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

הצגת הקוד ב-GitHub

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

הצגת הקוד ב-GitHub

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 מוסבר איך מציגים, מאתרים באגים ומתקנים שגיאות.

נושאים קשורים

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