ربط تطبيق Chat بخدمات وأدوات أخرى

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

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

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

طلب إعداد تطبيق Chat من مستخدم

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

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}

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

إكمال طلب الإعداد

يتضمّن كل حدث تفاعلي في MESSAGE وADDED_TO_SPACE وAPP_COMMAND يتلقّاه تطبيق Chat أيضًا الحقل configCompleteRedirectUrl. يجب ترميز عنوان URL هذا في عنوان URL الخاص بالإعداد لاستخدامه عند اكتمال العملية. يشير التوجيه إلى عنوان URL هذا إلى أنّ Google Chat قد استوفى طلب الإعداد.

عند بدء تطبيق Chat، يعتمد مسار العمل على الرسالة المحدّدة التي تم تلقّيها. استجابةً لرسالة مثل @app help، يجب أن يستجيب تطبيق Chat برسالة بدون الحاجة إلى إعدادات إضافية.

عندما تتم إعادة توجيه المستخدم بنجاح إلى configCompleteRedirectUrl المقدَّم في الرسالة الأصلية، يتّخذ Google Chat الخطوات التالية:

  1. محو الطلب الذي تم عرضه على المستخدم الذي بدأ المحادثة
  2. حوِّل الرسالة الأصلية إلى رسالة عامة لتصبح مرئية للأعضاء الآخرين في المساحة.
  3. أرسِل الرسالة الأصلية إلى تطبيق Chat نفسه مرة ثانية.

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

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

مصادقة مستخدم Chat خارج Chat

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

استخدِم رمز التعريف الذي تم إصداره أثناء تسجيل الدخول للحصول على معرّف المستخدم. يحتوي عنصر sub على المعرّف الفريد للمستخدم ويمكن ربطه بمعرّف المستخدم من Google Chat.

على الرغم من أنّ المعرّفَين ليسا متطابقَين تمامًا، يمكن إجبارهما على التطابق. لفرض قيمة المطالبة sub على users/{user} في Google Chat، أضِف users/ قبل القيمة. على سبيل المثال، تكون قيمة المطالبة 123 مساوية لاسم المستخدم users/123 في الرسائل إلى تطبيق Chat.