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

توضّح هذه الصفحة كيف يمكن لتطبيق Google 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.

إذا كنت قد أنشأت تطبيق Chat تفاعليًا، عليك ضبط Google Chat API لكي يرسل إليك Google Chat أحداث تفاعل:

  1. في Google Cloud Console، افتح صفحة Google Chat API:

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

  2. انقر على علامة التبويب الإعداد.
  3. في قسم الميزات التفاعلية، انقر على مفتاح التبديل تفعيل الميزات التفاعلية لتفعيله.
  4. في الوظائف، ضَع علامة في أحد مربّعَي الاختيار التاليَين أو كليهما:
    1. تلقّي الرسائل بين شخصين: يسمح ذلك للمستخدمين بالتفاعل مع تطبيق Chat في مساحات الرسائل المباشرة. يتلقّى تطبيقك في Chat أحداث التفاعل في أي وقت يُرسِل فيه أحد المستخدمين رسالة في مساحة الرسائل المباشرة.
    2. الانضمام إلى المساحات والمحادثات الجماعية: يسمح هذا الخيار للمستخدمين بإضافة تطبيقك على Chat وإزالته إلى المساحات التي تضم أكثر من مستخدم واحد. يتلقّى تطبيقك في Chat أحداث التفاعل عند إضافته أو إزالته من المساحة، وعندما يشير المستخدمون باستخدام @أو يستخدمون أمرًا شرطة مائلة في المساحة.
  5. في إعدادات الربط، حدِّد المكان الذي يرسل فيه Google Chat أحداث التفاعل مع تطبيق Chat.
  6. اختياري: في أوامر الشرطة المائلة، يمكنك إضافة أمر واحد أو أكثر من الأوامر التي تبدأ بشرطة مائلة وإعداده. لمزيد من المعلومات، يُرجى الاطّلاع على إعداد الأوامر التي تبدأ بشرطة مائلة.
  7. اختياري: في معاينات الروابط، يمكنك إضافة وضبط نمط عنوان URL واحد أو أكثر لتعاينه في تطبيق Chat. لمزيد من المعلومات، يُرجى الاطّلاع على روابط المعاينة.
  8. انقر على حفظ.

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

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

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

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

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

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

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

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

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

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

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

لإنشاء استجابات متزامنة لأحداث التفاعل، راجِع الأدلة التالية:

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

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

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

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