تلقّي تفاعلات المستخدمين والاستجابة لها

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

توضّح هذه الصفحة كيفية إجراء ما يلي:

  • ضبط تطبيق Chat لتلقّي التفاعل أحداث.
  • معالجة حدث التفاعل على البنية الأساسية.
  • إذا كان ذلك مناسبًا، قم بالرد على أحداث التفاعل.

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

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

آلية عمل أحداث التفاعل

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

على سبيل المثال، تستخدم تطبيقات Chat أحداث التفاعل لتنفيذ أي من التالي:

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

لكل نوع من تفاعل المستخدم، يرسل Google Chat نوعًا مختلفًا من حدث تفاعل يساعد تطبيق Chat على التعامل مع كل ونوع الحدث وفقًا لذلك. على سبيل المثال، يستخدم Google Chat نوع الحدث ADDED_TO_SPACE لأي تفاعل يضيف فيه المستخدم تطبيق Chat على مساحة، حتى يمكن لتطبيق Chat التعامل مع الردود، مثل نشر رسالة ترحيب في المساحة. للاطّلاع على جميع أحداث التفاعل المتوافقة، يمكنك الاطّلاع على مرجع واحد (EventType) المستندات.

تلقّي أحداث التفاعل مع تطبيق Chat

يصف هذا القسم كيفية تلقّي أحداث التفاعل ومعالجتها لحسابك. تطبيق Chat

ضبط تطبيق Chat لتلقّي أحداث التفاعل

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

لكل ميزة من الميزات التفاعلية التي تريد إنشاءها، يجب عليك تحديث إعداداتك في Chat API لكي يتمكّن Google Chat من إرسال الرسائل أحداث التفاعل ذات الصلة بتطبيق Chat:

  1. في Google Cloud Console، انتقِل إلى صفحة Chat API وانقر على صفحة الإعداد:

    الانتقال إلى صفحة إعدادات Chat API

  2. ضِمن الميزات التفاعلية، راجِع الإعدادات وعدِّلها استنادًا إلى الميزات التي تريد إنشاءها:

    الحقل الوصف
    الوظائف مطلوب. مجموعة من الحقول التي تحدّد الطريقة التي يمكن أن يتفاعل بها تطبيق Chat مع المستخدمين:
    • تلقّي رسائل بين شخصين: يمكن للمستخدمين العثور على تطبيق Chat ومراسلته مباشرةً في Google Chat.
    • الانضمام إلى المساحات والمحادثات الجماعية: يمكن للمستخدمين إضافة تطبيق Chat إلى المساحات والمحادثات الجماعية.
    إعدادات الربط مطلوب. نقطة النهاية لتطبيق Chat، وهي واحدة مما يلي:
    • عنوان URL للتطبيق: نقطة نهاية HTTPS تستضيف تنفيذ تطبيق Chat.
    • مشروع "برمجة تطبيقات Google": رقم تعريف نشر لمشروع "برمجة تطبيقات Google" الذي ينفِّذ تطبيق Chat.
    • اسم موضوع Cloud Pub/Sub: موضوع النشر/الاشتراك الذي يشترك فيه تطبيق Chat كنقطة نهاية.
    • Dialogflow: لتسجيل تطبيق Chat من خلال عملية دمج Dialogflow. لمزيد من المعلومات، راجِع إنشاء تطبيق Google Chat من Dialogflow يفهم اللغة الطبيعية.
    الأوامر التي تبدأ بشرطة مائلة اختياريّ. الأوامر التي يمكن إظهارها للمستخدمين ضمن Google Chat يسمح هذا الإعداد للمستخدمين بالاطّلاع على الإجراءات الأساسية لتطبيق Chat في Google Chat، واختيار إجراء محدّد يريدون التفاعل معه. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الرد على الأوامر التي تبدأ بشرطة مائلة كتطبيق في Chat.
    معاينات الروابط اختياريّ. أنماط عناوين URL التي يتعرّف عليها تطبيق Chat ويقدّم محتوى إضافيًا عندما يرسل المستخدمون الروابط. لمزيد من المعلومات، يُرجى الاطّلاع على روابط المعاينة.
    مستوى الرؤية اختياريّ. ما يصل إلى خمسة أفراد أو مجموعة واحدة أو أكثر من "مجموعات Google" التي يمكنها عرض تطبيق Chat وتثبيته. استخدِم هذا الحقل لاختبار تطبيق Chat أو لمشاركة تطبيق Chat مع فريقك. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة اختبار الميزات التفاعلية.

  3. انقر على حفظ. عند حفظ تطبيق Chat هو تطبيق Chat المتاح للجميع مستخدمين محدّدين في مؤسستك على Google Workspace.

تم إعداد تطبيق Chat الآن لتلقّي التفاعل الأحداث من Google Chat.

التعامل مع محاولات إعادة محاولة استدعاء HTTP إلى الخدمة

في حال تعذُّر إرسال طلب HTTPS إلى خدمتك (مثلاً عند انتهاء المهلة، أو ظهور اتصال مؤقت بالشبكة أو رمز حالة HTTPS غير تابع لـ 2xx)، قد يعيد Google Chat محاولة التسليم بضع دقائق في غضون بضع دقائق (ولكن هذا الأمر ليس مضمونًا). نتيجةً لذلك، قد يتلقى تطبيق Chat الرسالة نفسها بضع مرات لمواقف معينة. إذا اكتمل الطلب بنجاح ولكن تم عرض رسالة حمولة الرسائل، لا يعيد Google Chat الطلب.

معالجة أحداث التفاعل أو الاستجابة لها

يوضّح هذا القسم كيف يمكن لتطبيقات Google Chat معالجة الطلبات والاستجابة لها. أحداث التفاعل.

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

للاستجابة بشكل متزامن، يجب أن يستجيب تطبيق Chat خلال 30 ثانية، ويجب نشر الرد في المساحة التي حدث تفاعل. بخلاف ذلك، يمكن لتطبيق Chat تعمل بشكل غير متزامن.

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

يوضح الرسم التخطيطي التالي كيف يعالج تطبيق Google Chat عادةً أنواعًا مختلفة من أحداث التفاعل:

بنية كيفية معالجة تطبيقات Google Chat لأحداث التفاعل

الردّ في الوقت الفعلي

من خلال أحداث التفاعل، يمكن لتطبيقات Chat الردّ في الوقت الفعلي. بشكل متزامن: الردود المتزامنة لا تتطلب المصادقة.

الرد للانضمام إلى مساحة

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

إرسال رسالة نصية عندما يضيف مستخدم تطبيق Chat الخاص بك إلى مساحة، تطبيق Chat الاستجابة إلى ADDED_TO_SPACE حدث تفاعل. للرد على من أحداث تفاعل ADDED_TO_SPACE مع رسالة نصية، استخدِم الرمز التالي:

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar
      from Google Chat. Take a look at your schedule today by typing
      `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
      learn what else I can do, type `/help`.'
    });
  }
};

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

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. An onboarding message that
 * introduces the app and helps people get started with it.
 */
function onAddToSpace(event) {

  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar
    from Google Chat. Take a look at your schedule today by typing
    `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
    what else I can do, type `/help`.'
  }
}

يعرض نموذج الرمز البرمجي الرسالة النصية التالية:

مثال على رسالة الإعداد

أمثلة أخرى للرد على التفاعلات

لإنشاء ردود متزامنة على أحداث التفاعل، يُرجى الاطّلاع على ما يلي: الأدلة:

الرد بشكل غير متزامن

في بعض الأحيان، يجب أن تستجيب التطبيقات في Chat لحدث تفاعل بعد 30 ثانية. أو تنفيذ مهام خارج المساحة التي كان حدث التفاعل فيها التي تم إنشاؤها. على سبيل المثال، قد يحتاج تطبيق Chat إلى ما يلي: الاستجابة للمستخدم بعد إكمال مهمة طويلة الأمد. وفي هذه الحالة، يمكن لتطبيقات Chat الرد بشكل غير متزامن من خلال طلب واجهة برمجة تطبيقات Google Chat.

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