פרטי עיבוד שמשתמשים מזינים

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

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

---

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

לפתיחת הכלי ליצירת כרטיסים

---

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

• עדכון בקשות לשירות לקוחות.
• יצירת הזמנות עבודה.
• אימות באמצעות שירותי אינטרנט.

הסבר על קבלת נתונים

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

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

• EventType הוא CARD_CLICKED.
• DialogEventType הוא SUBMIT_DIALOG (רק לתיבות דו-שיח).

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

האפליקציה שלך יכולה לגשת לערך הראשון שהוזן על ידי המשתמש ב-event.common.formInputs.NAME.stringInputs.value[0], כאשר NAME הוא השדה name בווידג'ט TextInput.

אם האפליקציה Chat שלך מבוססת על Apps Script, צריך להשתמש ב-event.common.formInputs.NAME[""].stringInputs.value[0] במקום זאת.

קבלת נתונים מכרטיסים

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

JSON

{
  "type": enum (EventType),
  "eventTime": string,
  "threadKey": string,
  "message": {
    object (Message)
  },
  "user": {
    object (User)
  },
  "space": {
    object (Space)
  },
  "action": {
    object (FormAction)
  },
  "configCompleteRedirectUrl": string,
  "common": {

    // Represents user data entered in a card.
    "formInputs": {

      // Represents user data entered for a specific field in a card.
      "NAME": {

        // Represents string data entered in a card, like text input fields
        // and check boxes.
        "stringInputs": {

          // An array of strings entered by the user in a card.
          "value": [
            string
          ]
        }
      }
    },
    "parameters": {
      string: string,
      ...
    },
    "invokedFunction": string
  }
}

קבלת נתונים מתיבות דו-שיח

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

JSON

{
  "type": enum (EventType),
  "eventTime": string,
  "threadKey": string,
  "message": {
    object (Message)
  },
  "user": {
    object (User)
  },
  "space": {
    object (Space)
  },
  "action": {
    object (FormAction)
  },
  "configCompleteRedirectUrl": string,

  // Indicates that this event is dialog-related.
  "isDialogEvent": true,

  // Indicates that a user clicked a button, and all data
  // they entered in the dialog is included in Event.common.formInputs.
  "dialogEventType": "SUBMIT_DIALOG",
  "common": {
    "userLocale": string,
    "hostApp": enum (HostApp),
    "platform": enum (Platform),
    "timeZone": {
      object (TimeZone)
    },

    // Represents user data entered in a dialog.
    "formInputs": {

      // Represents user data entered for a specific field in a dialog.
      "NAME": {

        // Represents string data entered in a dialog, like text input fields
        // and check boxes.
        "stringInputs": {

          // An array of strings entered by the user in a dialog.
          "value": [
            string
          ]
        }
      }
    },
    "parameters": {
      string: string,
      ...
    },
    "invokedFunction": string
  }
}

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

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

• כדי לאשר שהקבלה הצליחה, צריך להשיב בפרמטר ActionResponse שמכיל את "actionStatus": "OK".
• על מנת להחזיר שגיאה, צריך להשיב בפרמטר ActionResponse שכולל "actionStatus": "ERROR MESSAGE".

דוגמה

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

Node.js

/**
 * Checks for a form input error, the absence of
 * a "name" value, and returns an error if absent.
 * Otherwise, confirms successful receipt of a dialog.
 *
 * Confirms successful receipt of a dialog.
 *
 * @param {Object} event the event object from Chat API.
 *
 * @return {object} open a Dialog in Google Chat.
 */
function receiveDialog(event) {

  // Checks to make sure the user entered a name
  // in a dialog. If no name value detected, returns
  // an error message.
  if (event.common.formInputs.WIDGET_NAME.stringInputs.value[0] == "") {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "Don't forget to name your new contact!"
        }
      }
    });

  // Otherwise the app indicates that it received
  // form data from the dialog. Any value other than "OK"
  // gets returned as an error. "OK" is interpreted as
  // code 200, and the dialog closes.
  } else {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    });
  }
}

Apps Script

בדוגמה הזו נשלחת הודעת כרטיס על ידי החזרת card JSON. אפשר גם להשתמש בשירות של כרטיסי Apps Script.

/**
 * Checks for a form input error, the absence of
 * a "name" value, and returns an error if absent.
 * Otherwise, confirms successful receipt of a dialog.
 *
 * Confirms successful receipt of a dialog.
 *
 * @param {Object} event the event object from Chat API.
 *
 * @return {object} open a Dialog in Google Chat.
 */
function receiveDialog(event) {

  // Checks to make sure the user entered a name
  // in a dialog. If no name value detected, returns
  // an error message.
  if (event.common.formInputs.WIDGET_NAME[""].stringInputs.value[0] == "") {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "Don't forget to name your new contact!"
        }
      }
    };

  // Otherwise the app indicates that it received
  // form data from the dialog. Any value other than "OK"
  // gets returned as an error. "OK" is interpreted as
  // code 200, and the dialog closes.
  } else {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    };
  }
}

Python

def receive_dialog(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Checks for a form input error, the absence of a "name" value, and returns
     an error if absent. Otherwise, confirms successful receipt of a dialog.

  Args:
      event (Mapping[str, Any]): the event object from Chat API.

  Returns:
      Mapping[str, Any]: the response.
  """

  if common := event.get('common'):
    if form_inputs := common.get('formInputs'):
      if contact_name := form_inputs.get('WIDGET_NAME'):
        if string_inputs := contact_name.get('stringInputs'):
          if name := string_inputs.get('value')[0]:
            return {
              'actionResponse': {
                'type': 'DIALOG',
                'dialogAction': {
                  'actionStatus': 'OK'
                }
              }
            }
          else:
            return {
              'actionResponse': {
                'type': 'DIALOG',
                'dialogAction': {
                  'actionStatus': 'Don\'t forget to name your new contact!'
                }
              }
            }

פתרון בעיות

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

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