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

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

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

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

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

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

تطبيق Google 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 وحلّها.