جمع المعلومات من مستخدمي 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، أكمِل الخطوات الأساسية هذه.

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

تطبيق Google Chat مفعَّل للميزات التفاعلية لإنشاء تطبيق Chat تفاعلي في "برمجة تطبيقات Google"، أكمِل البدء السريع هذا.

إنشاء نماذج باستخدام البطاقات

لجمع المعلومات، تعمل تطبيقات Chat على تصميم النماذج وإدخالاتها، ودمجها في بطاقات. لعرض البطاقات للمستخدمين، يمكن لتطبيقات Chat استخدام واجهات Chat التالية:

  • الرسائل التي تتضمّن بطاقة واحدة أو أكثر.
  • الصفحات الرئيسية: وهي بطاقة تظهر من علامة التبويب الصفحة الرئيسية في الرسائل المباشرة باستخدام تطبيق Chat.
  • المحادثات، وهي بطاقات يتم فتحها في نافذة جديدة من الرسائل والصفحات الرئيسية

يمكن لتطبيقات Chat إنشاء البطاقات باستخدام التطبيقات المصغّرة التالية:

  • التطبيقات المصغّرة لإدخال البيانات في النماذج التي تطلب معلومات من المستخدِمين يمكنك اختياريًا إضافة عمليات التحقّق إلى التطبيقات المصغّرة لإنشاء نماذج إدخال، لضمان إدخال المستخدمين للمعلومات وتنسيقها بشكلٍ صحيح. يمكن لتطبيقات Chat استخدام أدوات الإدخال التالية:

    • مدخلات نصية (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/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 حيث CARD_CLICKEDأدخَل المستخدِم قيمًا لكلّ تطبيق مصغّر:

HTTP

{
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

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

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