معلومات المستخدمين التي أدخلوها

يشرح هذا الدليل طريقة تلقّي وقراءة المعلومات التي يُدخلها المستخدمون في رسائل البطاقات ومربعات الحوار. يمكن للمستخدمين إدخال البيانات التي تتلقّاها تطبيقات Chat وتقرأها وتردّ عليها. تشمل التطبيقات المصغّرة التي تسمح للمستخدمين بإدخال المعلومات ما يلي:

• TextInput لإدخال النص بشكل مرن الذي يتوافق أيضًا مع الاقتراحات.
• SelectionInput لعناصر القائمة والقوائم، مثل مربّعات الاختيار وأزرار الاختيار والقوائم المنسدلة
• DateTimePicker للاطّلاع على إدخالات التاريخ والوقت

---

يمكنك استخدام "أداة إنشاء البطاقات" لتصميم رسائل بطاقة JSON ومعاينتها لتطبيقات Chat، وذلك باتّباع الخطوات التالية:

فتح أداة إنشاء البطاقات

---

يؤدي تلقّي البيانات من المستخدمين إلى السماح للتطبيقات في Chat بتنفيذ إجراءات، مثل ما يلي:

• عدِّل طلبات الحصول على خدمة العملاء.
• إنشاء طلبات العمل.
• قم بالمصادقة مع خدمات الويب.

طريقة عمل ميزة تلقّي البيانات

يقدّم تطبيق Chat المعلومات للمستخدم على شكل مربّع حوار أو رسالة بطاقة. في هذا المثال، يطلب مربّع الحوار من المستخدم إدخال معلومات عن جهة الاتصال باستخدام التطبيق المصغّر TextInput وSelectionInput:

عند الانتهاء، يتلقّى تطبيق Chat البيانات التي أدخلها المستخدمون في مربّع الحوار بتنسيق JSON وحدث تفاعل في الحالات التالية:

• الحالة EventType هي CARD_CLICKED.
• DialogEventType هي SUBMIT_DIALOG (لمربعات الحوار فقط).

وللحصول على بيانات عن ما أدخله المستخدمون، استخدِم الحقل Event.common.formInputs في حمولة الحدث. والحقل formInputs هو خريطة تكون فيها المفاتيح عبارة عن أرقام تعريف سلاسل يتم تخصيصها لكل تطبيق مصغّر، وتمثل القيم البيانات التي أدخلها المستخدم لكل أداة. تمثل الكائنات المختلفة أنواعًا مختلفة من بيانات الإدخال. على سبيل المثال، تمثل Event.common.formInputs.stringInputs مدخلات السلسلة.

يمكن لتطبيقك الوصول إلى أول قيمة أدخلها المستخدم في event.common.formInputs.NAME.stringInputs.value[0]، حيث يكون NAME هو الحقل name في أداة TextInput.

إذا تم إنشاء تطبيق Chat باستخدام "برمجة تطبيقات Google"، استخدِم 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"
        }
      }
    });
  }
}

برمجة تطبيقات

في هذا المثال، يتم إرسال رسالة بطاقة من خلال عرض البطاقة JSON. يمكنك أيضًا استخدام خدمة بطاقة "برمجة تطبيقات Google".

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