جمع المعلومات من مستخدمي Google Chat ومعالجتها

يوضّح هذا الدليل الطريقة التي يمكن بها لتطبيقات Google Chat جمع المعلومات ومعالجتها. من المستخدمين من خلال إنشاء إدخالات نماذج في واجهات مستندة إلى البطاقات.

مربّع حوار يعرض مجموعة متنوعة من التطبيقات المصغّرة المختلفة
الشكل 1: أ العيّنة تطبيق Chat يفتح مربّع حوار لجمع معلومات الاتصال.

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

  • اضبط الإعدادات. على سبيل المثال، للسماح للمستخدمين بتخصيص إعدادات الإشعارات أو ضبط تطبيق Chat وإضافته إلى تطبيق واحد أو أكثر المسافات.
  • إنشاء معلومات أو تعديلها في تطبيقات Google Workspace الأخرى على سبيل المثال، يمكنك السماح للمستخدمين بإنشاء حدث في "تقويم Google".
  • يتم السماح للمستخدمين بالوصول إلى الموارد وتعديلها في التطبيقات أو خدمات الويب الأخرى. على سبيل المثال، يمكن أن يساعد تطبيق Chat المستخدمين في تعديل حالة طلب الدعم مباشرةً من مساحة Chat.

المتطلبات الأساسية

تطبيق Google Chat مفعَّل للميزات التفاعلية لإنشاء تطبيق Chat تفاعلي، أكمِل أحد عمليات البدء السريع التالية استنادًا إلى بنية التطبيق التي تريد استخدامها:

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

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

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

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

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

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

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

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

لمزيد من الأمثلة حول التطبيقات المصغّرة التفاعلية التي يمكنك استخدامها لجمع البيانات المعلومات، راجع تصميم بطاقة تفاعلية أو مربع حوار:

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

عندما ينقر المستخدمون على أحد الأزرار، تتلقى تطبيقات Chat حدث تفاعل واحد (CARD_CLICKED) يحتوي على معلومات حول التفاعل. تحتوي الحمولة لأحداث CARD_CLICKED التفاعل على عنصر common.formInputs مع أي قيم يُدخلها المستخدم.

يمكنك استرداد القيم من الكائن common.formInputs.WIDGET_NAME، حيث WIDGET_NAME هو حقل name الذي حدّدته للأداة. ويتم عرض القيم كنوع بيانات محدّد للتطبيق المصغّر (يتم تمثيلها كائن Inputs). في المثال التالي، تجمع البطاقة معلومات الاتصال باستخدام رسالة نصية الإدخال وأداة اختيار التاريخ والوقت والاختيار المصغّر للإدخال:

{
  "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 حيث أدخَل المستخدِم قيمًا لكلّ تطبيق مصغّر:

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 events.common.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs للحصول على القيمة الأولى أو الوحيدة، events.common.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker التي تقبل التواريخ فقط dateInput events.common.formInputs.contactBirthdate.dateInput.msSinceEpoch. 1000425600000

نقل البيانات إلى بطاقة أخرى

بعد أن يرسل المستخدم معلومات من بطاقة، قد تحتاج إلى عرض بطاقات إضافية لإجراء أي مما يلي:

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

لنقل البيانات التي تم إدخالها من البطاقة الأولية، يمكنك إنشاء button. تطبيق مصغّر مع actionParameters التي تحتوي على name للأداة والقيمة التي يُدخلها المستخدم، كما هو موضَّح في المثال التالي:

{
  "buttonList": {
    "buttons": [{
      "text": "Submit",
      "onClick": {
        "action": {
          "function": "openNextCard",
          "parameters": [{
            "key": "WIDGET_NAME",
            "value": "USER_INPUT_VALUE"
          }]
        }
      }
    }]
  }
}

حيث WIDGET_NAME هو name في التطبيق المصغّر تمثّل السمة USER_INPUT_VALUE ما يُدخله المستخدم. على سبيل المثال، بالنسبة إلى إدخال نصي يجمع اسم شخص، يكون اسم التطبيق المصغّر هو contactName وأحد مثالي القيم هو Kai O.

عندما ينقر أحد المستخدِمين على الزر، يتلقّى تطبيق Chat حدث تفاعل CARD_CLICKED. لاسترداد القيم، يمكنك استخدام العنصر event.common.parameters .

يعرض ما يلي مثالاً على كيفية تمرير مَعلمات تحتوي على بيانات إدخال العميل إلى دالة تفتح البطاقة التالية:

Node.js

// Respond to button clicks on cards or dialogs
if (event.type === "CARD_CLICKED") {

  // Open another card.
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    openNextCard(event);
  }
}

Python

  # Respond to button clicks on cards or dialogs
  if request.get('type') == 'CARD_CLICKED':
    if invoked_function := request.get('common', dict()).get('invokedFunction'):
      if invoked_function == 'open_next_card':
        parameters = request.get('common', dict()).get('parameters'),
        return open_next_card(parameters)

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

// Respond to button clicks on cards or dialogs
function onCardClick(event) {
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    return openNextCard(parameters);
  }
}

الردّ على نموذج تم إرساله

بعد تلقّي البيانات من رسالة بطاقة أو مربّع حوار، يردّ تطبيق Chat إما من خلال تأكيد الاستلام أو عرض خطأ.

في المثال التالي، يُرسِل تطبيق Chat رسالة نصية لتأكيد استلامه بنجاح نموذجًا تم إرساله من رسالة بطاقة.

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

function submitCardForm(contactName, contactBirthdate, contactType) {
    return {
      "text": "You entered the following contact information:\n\n" +
      "*Name:* " + contactName + "\n" +
      "*Birthdate:* " + contactBirthdate + "\n" +
      "*Type:* " + contactType
      }
}

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

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

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

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