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

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

في Google Chat، تظهر الإضافات للمستخدمين على أنّها تطبيقات Google Chat. لمزيد من المعلومات، راجِع نظرة عامة على توسيع نطاق Google Chat.

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

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

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

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

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

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

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

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

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

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

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

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

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

عندما ينقر المستخدمون على زر، يتم بدء الإجراء في تطبيقات Chat مع تضمين معلومات عن التفاعل. في commonEventObject حمولة الحدث، يحتوي العنصر formInputs على أي قيم يُدخلها المستخدِم.

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

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

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

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

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

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

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

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

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "submitForm",
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

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

عندما ينقر مستخدم على الزر، يتلقّى تطبيق Chat عنصر حدث يمكنك من خلاله تلقّي البيانات.

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

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

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

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  const chatMessage = chatEvent.messagePayload.message;

  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(chatMessage, chatEvent.user));
  // Handle CARD_CLICKED events
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openDialog":
            return res.send(openDialog());
        case "openNextCard":
            return res.send(openNextCard(req.body));
        case "submitForm":
            return res.send(submitForm(req.body));
    }
  }
};

/**
 * Submits information from a dialog or card message.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

/**
 * Sends private text message that confirms submission.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

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

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

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

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