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

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

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

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

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

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

  • مدخلات نصية (textInput) للنص الذي لا يتّبع تنسيقًا معيّنًا أو النص المقترَح
  • مدخلات الاختيار (selectionInput) هي عناصر واجهة مستخدم قابلة للاختيار، مثل مربّعات الاختيار، وأزرار الاختيار، والقوائم المنسدلة. يمكن أيضًا لأداة الاختيار المخصّصة لإدخال البيانات تعبئة العناصر من مصادر بيانات ثابتة أو ديناميكية. على سبيل المثال، يمكن للمستخدمين الاختيار من قائمة مساحات Chat التي ينتمون إليها.
  • أداة اختيار التاريخ والوقت (dateTimePicker) لإدخال التاريخ والوقت

• تطبيق مصغّر زر لكي يتمكّن المستخدمون من إرسال القيم التي أدخلوها في البطاقة بعد أن ينقر المستخدم على الزر، يمكن لتطبيق Chat معالجة المعلومات التي يتلقّاها.

في المثال التالي، تجمع بطاقة معلومات الاتصال باستخدام إدخال نصي وأداة اختيار التاريخ والوقت وإدخال اختيار:

للحصول على مثال على تطبيق 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/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.

عندما ينقر المستخدمون على زر، تتلقّى تطبيقات Chat حدث تعامل يعتمد على موضع الزر:

• إذا كان الزرّ في رسالة أو مربّع حوار، تتلقّى تطبيقات 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"]
      }}
    }}
  }
  

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

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

• إذا كان الزر معروضًا على صفحة رئيسية،تلقّى تطبيقات Chat SUBMIT_FORM حدث تفاعل. تحتوي الحمولة لحدث التفاعل على عنصر commonEventObject.formInputs مع أي قيم يُدخلها المستخدم.

  يمكنك استرداد القيم من العنصر commonEventObject.formInputs.WIDGET_NAME، حيث WIDGET_NAME هو حقل name الذي حدّدته للتطبيق المصغّر. يتم عرض القيم كنوع بيانات محدّد للتطبيق المصغّر (يتم تمثيله ككائن Inputs).

  يعرض ما يلي جزءًا من حدث تفاعُل SUBMIT_FORM حيث أدخَل المستخدِم قيمًا لكلّ تطبيق مصغّر:

  HTTP

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

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

  {
    "type": "SUBMIT_FORM",
    "commonEventObject": { "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 عرض بطاقة أولية تطلب سبب الموعد، ثم preenchimentoبطاقة أخرى تقدّم الأوقات المتاحة استنادًا إلى نوع الموعد.

لنقل بيانات الإدخال من البطاقة الأولية، يمكنك إنشاء 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/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.
const errorMessage = "Don't forget to name your new contact!";
if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { actionStatus: {
      statusCode: "INVALID_ARGUMENT",
      userFacingMessage: 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.
error_message = "Don't forget to name your new contact!"
if contact_name == "" and "SUBMIT_DIALOG" == event.get('dialogEventType'):
  return { 'actionResponse': {
    'type': "DIALOG",
    'dialogAction': { 'actionStatus': {
      'statusCode': "INVALID_ARGUMENT",
      'userFacingMessage': 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.
String errorMessage = "Don't forget to name your new contact!";
if (contactName.isEmpty() && 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))));
}

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

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.
const errorMessage = "Don't forget to name your new contact!";
if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { actionStatus: {
      statusCode: "INVALID_ARGUMENT",
      userFacingMessage: errorMessage
    }}
  }};
}

لمعالجة مربّع حوار وإغلاقه، يمكنك عرض عنصر ActionResponse يحدّد ما إذا كنت تريد إرسال رسالة تأكيد أو تعديل الرسالة أو البطاقة الأصلية أو إغلاق مربّع الحوار فقط. لمعرفة الخطوات، يُرجى الاطّلاع على مقالة إغلاق مربّع حوار.

تحديد المشاكل وحلّها

عندما يعرض تطبيق Google Chat أو البطاقة خطأ، تظهر رسالة في واجهة Chat تفيد بأنّ "حدث خطأ". أو "تعذّرت معالجة طلبك". في بعض الأحيان، لا يعرض واجهة مستخدم Chat أي رسالة خطأ، ولكن ينتج عن تطبيق Chat أو البطاقة نتيجة غير متوقّعة، على سبيل المثال، قد لا تظهر رسالة البطاقة.

على الرغم من أنّه قد لا تظهر رسالة خطأ في واجهة مستخدم Chat، تتوفّر رسائل خطأ وصفية وبيانات السجلّ لمساعدتك في حلّ الأخطاء عند تفعيل تسجيل الأخطاء في تطبيقات Chat. للحصول على مساعدة في عرض الأخطاء وتصحيحها وتحديد الأخطاء البرمجية، يُرجى الاطّلاع على مقالة تحديد أخطاء Google Chat وحلّها.

مواضيع ذات صلة

• الاطّلاع على نموذج "مدير جهات الاتصال"، وهو تطبيق Chat يطلب من المستخدمين إكمال نموذج اتصال من رسائل البطاقات ومحادثات المستخدمين
• فتح مربّعات حوار تفاعلية