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

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

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

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

  • تعديل حالات خدمة العملاء
  • إنشاء أوامر العمل.
  • المصادقة باستخدام خدمات الويب

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

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

مربّع حوار يعرض مجموعة متنوعة من التطبيقات المصغّرة المختلفة

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

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

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

تلقّي البيانات من البطاقات

عندما يُدخِل المستخدم البيانات في رسالة بطاقة، يتلقّى تطبيق 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"
        }
      }
    });
  }
}

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

/**
 * 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 وحلّها.