أول رسالة فورية للبث المتعدد باستخدام مواضيع "المراسلة عبر السحابة الإلكترونية من Firebase"

1- مقدمة

الأهداف

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

بعد الانتهاء، سيكون بإمكانك الاستفادة من البنية الأساسية لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" لإدارة هذه المجموعات الفرعية، بالإضافة إلى الرسائل الفورية التي يتم إرسال الرسائل باستخدام البث المتعدد إليها على المجموعات الفرعية.

نظرة عامة على المواضيع

المواضيع هي بنية أساسية متوافقة مع "المراسلة عبر السحابة الإلكترونية من Firebase" للوصول إلى المجموعات الفرعية من نُسخ تطبيقك من خلال الرسائل.

توفّر خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" واجهات برمجة التطبيقات لإرسال الرسائل بالإضافة إلى الاحتفاظ بالاشتراكات في هذه المواضيع. يُطلق على عملية ربط نسخة التطبيق وإلغاء ربطها بالموضوع "اشتراك" و"إلغاء الاشتراك" على التوالي.

يجب استخدام المواضيع للمحتوى المتاح للجميع. مثل، الرسائل المتعلّقة بالطقس. إذا كنت تريد إرسال رسائل حساسة للمستخدم، استخدِم حزمة تطوير البرامج (SDK) لمشرف Firebase من أجل بث الرسائل المتعددة على أجهزة متعددة.

تم تحسين البث المتعدد المستنِد إلى المواضيع لمعالجة سرعة معالجة البيانات.

المعلومات التي ستطّلع عليها

• كيفية اشتراك (وإلغاء اشتراك) المستخدمين في مواضيع من تطبيق للأجهزة الجوّالة.
• كيفية إرسال رسائل فورية للبث المتعدد باستخدام المواضيع
• كيفية إرسال الرسائل إلى مجموعة من المواضيع باستخدام شروط المواضيع
• كيفية إدارة اشتراكات المواضيع من جهة الخادم وإجراء الاشتراكات وإلغاء الاشتراكات بشكلٍ مجمّع.

ما الذي ستنشئه

• تطبيق Android يشترك في المواضيع أو يلغي الاشتراك فيها ويتلقّى الرسائل عند إرسالها إلى المواضيع.
• عملية دمج من جهة الخادم باستخدام حزمة تطوير البرامج (SDK) لمشرف Firebase، والتي سيتم استخدامها لإرسال رسائل بشأن المواضيع من خلال واجهات برمجة تطبيقات "المراسلة عبر السحابة الإلكترونية من Firebase".

المتطلبات

• متصفّح من اختيارك، مثل Chrome
• IntelliJ IDEA IDE لتطوير تطبيقات Java
  • تأكد من الموافقة على دعم Gradle أثناء التثبيت.
• Android Studio لتطوير تطبيقات Android.
• جهاز لتشغيل تطبيق Android. أيٌّ مما يلي:
  • محاكي Android (يتطلّب ذلك إجراء عملية الإعداد في استوديو Android).
  • جهاز Android فعلي متصل بجهاز الكمبيوتر وتم ضبطه على "وضع مطوّر البرامج".
• حساب على Google لإنشاء مشروعك على Firebase وإدارته

2- بدء الإعداد

الحصول على الرمز

استنسِخ مستودع GitHub من سطر الأوامر:

git clone https://github.com/firebase/quickstart-android.git fcm-codelab

سيتم نسخ الرمز النموذجي في الدليل fcm-codelab.

cd fcm-codelab

يتوفّر تطبيق المبتدئين لهذا الدرس التطبيقي حول الترميز في دليل messaging لفرع fcm-topics-codelab. اتّبِع الخطوات التالية للوصول إلى رمز التفعيل. يتضمن الدليل دليلين StockNewsApp وStockNewsServer. يحتوي الأول على تطبيق Android للمبتدئين، بينما يحتوي الثاني على رمز جانب خادم البدء.

git checkout fcm-topics-codelab
cd messaging/fcm-topics-codelab/starter

تم وضع النسخة المكتملة من هذا الدرس التطبيقي في دليل messaging/fcm-topics-codelab/completed.

إنشاء مشروع على Firebase

1. في وحدة تحكُّم Firebase، انقر على إضافة مشروع، وأدخِل اسمًا لمشروع Firebase StockNews ثم انقر على "متابعة". ملاحظة: تذكّر رقم تعريف المشروع لمشروعك على Firebase (أو انقر على رمز تعديل لضبط رقم تعريف المشروع الذي تفضّله).

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

تهانينا لقد أنشأتَ للتو مشروعك على Firebase. الآن، يمكنك النقر فوق اسم المشروع للدخول إلى وحدة التحكم.

ملاحظة مهمّة: تتمّ تسمية مشروعك في Firebase باسم StockNews، لكنّ Firebase يعيّنه تلقائيًا رقم تعريف مشروع فريد على شكل stocknews-1234. هذا المعرّف الفريد هو كيفية تحديد مشروعك فعليًا (بما في ذلك واجهة سطر الأوامر)، في حين أن StockNews هو مجرد اسم معروض.

3- إعدادات تطبيق Firebase الخاص بالنظام الأساسي

تم مسبقًا التحقّق من معظم تغييرات الرموز المطلوبة لتفعيل دعم Firebase في المشروع الذي تعمل عليه. ومع ذلك، لإضافة دعم للأنظمة الأساسية للجوّال، يجب عليك:

• تسجيل النظام الأساسي المطلوب في مشروع Firebase
• نزِّل ملف الإعداد الخاص بالنظام الأساسي وأضِفه إلى الرمز البرمجي.

ملاحظة مهمة: عليك تسجيل جميع المنصّات التي تريد استخدامها ضمن مشروع Firebase نفسه.

لأغراض هذا الدرس التطبيقي، سنضيف تطبيق Android Firebase.

ضبط Android

1. في وحدة تحكُّم Firebase، اختَر إعدادات المشروع في أعلى شريط التنقّل الأيمن في إعدادات المسنين، ثم انقر على رمز Android ضمن تطبيقاتك في الصفحة الإعدادات العامة.

ملاحظة: إذا سبق لك إضافة تطبيق Firebase في مشروعك، انقر على إضافة تطبيق واختَر الزر Android.

من المفترض أن يظهر لك مربّع الحوار التالي :

2. القيمة المهمة التي يجب تقديمها هي اسم حزمة Android. اضبط السمة على com.ticker.stocknews.
   1. يجب أن يكون اسم الحزمة المقدّم هنا مطابقًا لاسم الحزمة الوارد في AndroidManifest.xml في رمز StockNewsApp الخاص بإجراء التفعيل. إذا كنت تريد تحديد موقعه أو تغييره، يُرجى اتباع الخطوات التالية:
      1. في دليل StockNewsApp، افتح الملف app/src/main/AndroidManifest.xml.
      2. في العنصر manifest، ابحث عن قيمة السلسلة للسمة package. هذه القيمة هي اسم حزمة Android.

ملاحظة: اطّلِع على مقالة ضبط رقم تعريف التطبيق للحصول على مزيد من المعلومات عن أرقام تعريف الحِزم والتطبيقات.

3. في مربع حوار Firebase، الصق اسم الحزمة المنسوخة في حقل اسم حزمة Android.
4. لست بحاجة إلى شهادة توقيع تصحيح الأخطاء SHA-1 لهذا الدرس التطبيقي، لأنه لن يتم إصدار هذا التطبيق. اترك هذا الحقل فارغًا.
5. انقر على تسجيل التطبيق.
6. المتابعة في "وحدة تحكُّم Firebase"، اتّبِع التعليمات لتنزيل ملف الإعداد "google-services.json".
7. يمكنك تخطّي خطوات الإعداد المتبقية، لأنّه سبق أن تم ضبط جميع الإعدادات الأخرى في رمز تطبيق إجراء التفعيل. ستجد تطبيقك مُدرجًا في الصفحة الرئيسية لـ "وحدة تحكُّم Firebase".
8. انسخ ملف google-services.json (الذي نزّلته للتو) إلى الدليل messaging/fcm-topics-codelab/starter/StockNewsApp/app.

4. إنشاء تطبيقك وتشغيله

يمكنك الآن بدء العمل على تطبيقك. أولاً، أنشئ التطبيق وشغِّله.

استيراد تطبيق إجراء التفعيل

شغِّل تطبيق Android Studio، واستورِد messaging/fcm-topics-codelab/starter/StockNewsApp من دليل رموز البدء.

بعد تحميل المشروع، قد يظهر لك أيضًا تنبيه بأن برنامج Git لا يتتبّع جميع التغييرات المحلية، ويمكنك النقر على تجاهل أو "X" في أعلى اليمين. (لن يتم إرسال أي تغييرات إلى مستودع Git.)

في الزاوية العلوية اليمنى من نافذة المشروع، من المفترض أن ترى شيئًا مثل الصورة أدناه إذا كنت في طريقة عرض Android. (إذا كنت تستخدم طريقة عرض المشروع، ستحتاج إلى توسيع المشروع لرؤية الشيء نفسه)

تجدر الإشارة إلى أنّ إنشاء المشروع في الخلفية على "استوديو Android" قد يستغرق عدّة ثوانٍ للمرّة الأولى. خلال هذه الفترة، ستظهر علامة دوّارة في شريط الحالة في أسفل "استوديو Android":

ننصحك بالانتظار إلى أن ينتهي هذا الإجراء قبل إجراء تغييرات على الرمز. سيسمح ذلك لـ "استوديو Android" بسحب جميع المكوّنات اللازمة.

بالإضافة إلى ذلك، إذا ظهرت رسالة تطلب منك "هل تريد إعادة التحميل لتطبيق التغييرات على اللغة؟" أو ما شابه ذلك، حدد "نعم".

إعداد المحاكي

إذا كنت بحاجة إلى مساعدة في إعداد محاكي Android، يمكنك الرجوع إلى مقالة تشغيل تطبيقك.

التعرّف على رمز إجراء التفعيل لتطبيق Android

• رمز إجراء التفعيل هو تطبيق Android خفيف بوظائف وواجهة مستخدم بسيطة.
• سبق أن تمت إضافة اعتمادية إلى حزمة تطوير البرامج (SDK) لمراسلة Firebase إلى ملف app/build.gradle.

• في AndroidManifest.xml، سبق أن تمت إضافة معالج معاودة الاتصال MESSAGING_EVENT.
  • يعمل المعالج "StockNewsMessagingService.java" على توسيع فئة FirebaseMessagingService التي توفّر العديد من الوظائف ذات الصلة بخدمة "المراسلة عبر السحابة الإلكترونية من Firebase". اطّلِع على مستندات FirebaseMessagingService لمعرفة مزيد من المعلومات.
  
  • يتم استدعاء الدالة onNewToken عند إنشاء الرمز المميز للتسجيل في خدمة FCM أو إعادة تحميله. لمزيد من المعلومات، راجِع مقالة مراقبة إنشاء الرموز المميّزة.
  • يتم استدعاء الدالة onMessageReceived عند تلقّي رسالة ويكون التطبيق في المقدّمة. في الوقت الحالي، يسجِّل النظام الرسالة المُستلَمة.
    • يمكنك الاطّلاع على تلقّي الرسائل في تطبيق Android لمعرفة المزيد من المعلومات عن الاختلافات بين تسليم الرسائل في الخلفية ومعالجتها في الخلفية.
• في AndroidManifest.xml، تم أيضًا توفير فئة Application من نظام التشغيل Android باسم StockNewsApplication.
  • سيكون هذا الصف أول صف يتم إنشاء مثيل له عند بدء تشغيل التطبيق.
  • في دالة onCreate للفئة StockNewsApplication، تتم إضافة استدعاء إنشاء الرمز المميّز للتسجيل في FCM. سينشئ هذا الرمز رمزًا مميّزًا صالحًا للتسجيل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" وسيتم تسجيله.
• تضيف MainActivity.java السمة RecyclerView التي تعرض خيارات فئة المخزون.
• تنفِّذ SubscriptionAdapter.java الدالة RecyclerView.Adapter التي ترسم شاشة اختيار "فئة الأسهم".
  • لكل فئة من فئات الأسهم اسم ومفتاح تبديل اشتراك بجانبها.
  • من المفترض أن يؤدي تغيير مفتاح التبديل إلى إجراء مكالمة بشأن الاشتراك في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" أو إلغاء الاشتراك.
  • سيتم تنفيذ هذه الاستدعاءات في الأقسام القادمة.
• تحتوي الفئة model/StockCategories.java على قائمة بجميع فئات الأسهم وأسماء المواضيع المرتبطة بها.

تشغيل تطبيق إجراء التفعيل

1. وصِّل جهاز Android بجهاز الكمبيوتر أو ابدأ محاكيًا.
2. في شريط الأدوات العلوي، حدد جهاز Android أو المحاكي المستهدف واضغط على الزر "تشغيل".

3. ستبدو واجهة مستخدم التطبيق على النحو التالي:

4. سينشئ التطبيق رمزًا مميَّزًا للتسجيل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" ويسجِّله. ومع ذلك، لن يحدث أي تغيير في واجهة مستخدم التطبيق.
   1. انسخ الرمز المميّز للتسجيل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" واحفظه لأنّه سيتم استخدامه في الخطوات التالية.

5- إرسال رسالة اختبار

أنت الآن جاهز لإرسال رسالة اختبار إلى مثيل التطبيق الذي أعددته في الخطوة الأخيرة.

استيراد رمز خادم إجراء التفعيل

شغِّل IntelliJ IDEA وافتح مشروع messaging/fcm-topics-codelab/starter/StockNewsServer.

من المفترض أن يبدو عرض المشروع في شريط التنقل الأيمن على النحو التالي:

لاحظ، قد يستغرق الأمر بضع دقائق حتى تتمكن IntellIj IDEA من إنشاء مشروعك، بما في ذلك سحب التبعيات المطلوبة.

التعرّف على رمز إجراء التفعيل الخاص بالخادم

• رمز البداية للخادم هو مشروع Java مستند إلى Gradle.
• يعتمد ملف build.gradle بالفعل على حزمة تطوير البرامج (SDK) الخاصة بـ Firebase-admin التي تمت إضافتها إليه. توفّر حزمة تطوير البرامج (SDK) هذه إمكانية الوصول إلى العديد من وظائف إرسال الرسائل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase".

• أخيرًا، هناك فئتان، بمعنى:
  • FcmSender.java: تحتوي هذه الفئة على طرق الملاحظة التالية:
    • initFirebaseSDK: لإعداد حزمة تطوير البرامج (SDK) الخاصة بـ firebase-admin
    • sendMessageToFcmRegistrationToken: أرسِل رسالة إلى الرمز المميّز للتسجيل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase".
    • sendMessageToFcmTopic: إرسال رسالة إلى موضوع "المراسلة عبر السحابة الإلكترونية من Firebase".
    • sendMessageToFcmTopicCondition: إرسال رسالة إلى أحد شروط موضوع "المراسلة عبر السحابة الإلكترونية من Firebase".
  • FcmSubscriptionManager.java: تحتوي هذه الفئة على طرق تتيح إدارة الاشتراكات في المواضيع من جهة الخادم.
    • initFirebaseSDK: لإعداد حزمة تطوير البرامج (SDK) الخاصة بـ firebase-admin
    • subscribeFcmRegistrationTokensToTopic: الاشتراك الرموز المميّزة للتسجيل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" في موضوع خدمة "المراسلة عبر السحابة الإلكترونية من Firebase".
    • unsubscribeFcmRegistrationTokensFromTopic: إلغاء الاشتراك في الرموز المميّزة للتسجيل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" من موضوع في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase".

إعداد رمز الخادم

1. نحتاج أولاً إلى إعداد حساب على خدمة Firebase يسمح لحزمة تطوير البرامج (SDK) لمشرف Firebase بالسماح باستدعاءات واجهات برمجة تطبيقات المراسلة عبر السحابة الإلكترونية من Firebase.
   1. انتقِل إلى "وحدة تحكُّم Firebase"، وانقر على رمز الترس بجانب نظرة عامة على المشروع في شريط التنقّل الأيمن، واختَر إعدادات المشروع.
   2. في صفحة الإعدادات، اختَر حسابات الخدمة وانقر على إنشاء حساب خدمة.
   3. انقر الآن على الزر إنشاء مفتاح خاص جديد وسيبدأ التنزيل التلقائي لملف المفتاح.
   4. أعِد تسمية ملف المفتاح إلى "service-account.json" وانسخه في المجلد "messaging/fcm-topics-codelab/starter/StockNewsServer/src/main/resources".
   5. يُحمّل كل من FcmSender.java وFcmSubscriptionManager.java ملف service-account.json من classpath باستخدام الرمز التالي.
2. في هذه المرحلة، يكون رمز الخادم جاهزًا. تشغيل الإصدار -> إنشاء مشروع من شريط القوائم العلوي.

إرسال رسالة اختبار

1. في FcmSender.java، ابحث عن الدالة sendMessageToFcmRegistrationToken وأدخِل الرمز المميّز لتسجيل خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" الذي نسخته من القسم تشغيل تطبيق إجراء التفعيل في الحقل registrationToken.
2. في الدالة main، ألغِ التعليق على الدالة sendMessageToFcmRegistrationToken فقط وانقر على "تشغيل" لتنفيذ الرمز البرمجي.
   1. لاحظ كيفية ضبط الرمز المميّز للتسجيل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" في الحقل Token للكائن message.
   2. يمكنك أيضًا الاطّلاع على كيفية استخدامنا لواجهة برمجة تطبيقات send الخاصة بواجهة FirebaseMessaging.

3. من المفترض أن يؤدي ذلك إلى إرسال رسالة إلى مثيل التطبيق الذي أعددته في الخطوة السابقة.
4. عندما يكون مثيل التطبيق في المقدّمة، من المفترض أن يظهر لك محتوى الرسالة الذي تم تسجيله.

5. وعندما يكون مثيل التطبيق في الخلفية، ستلاحظ ظهور الرسالة في حاوية الإشعارات.

رائع، لقد استخدمت حزمة تطوير البرامج (SDK) لمشرف Firebase لإرسال الرسائل إلى مثيل تطبيق. اطّلِع على المزيد من المعلومات عن استخدام حزمة تطوير البرامج (SDK) لمشرف Firebase في خادمك.

6- تنفيذ الاشتراك في المواضيع / إلغاء الاشتراك

في هذه الخطوة، ستنفّذ إجراءات الاشتراك في المواضيع وإلغاء الاشتراك في خيار "فئة الأسهم" في تطبيق Android.

عندما يبدّل أحد مستخدمي التطبيق مفتاح التبديل لفئةٍ معيّنة من الأسهم، سيتم إجراء طلب اشتراك في أحد المواضيع أو إلغاء الاشتراك.

رمز المراجعة

• انتقِل إلى الصف SubscriptionAdapter.java باستخدام رمز تطبيق Android وحدِّد مكان الصف RecyclerViewViewHolder.

• تُعدّ الدالة الإنشائية للفئة مستمعًا لتبديل الاشتراك باستخدام setOnCheckedChangeListener.
• استنادًا إلى مفتاح التبديل، يتم تنفيذ إجراءَي الاشتراك وإلغاء الاشتراك من خلال الاتصال بالطريقتين subscribeToStockCategory وunsubscribeFromStockCategory على التوالي.
• يتم استدعاء طريقة setData بواسطة onBindViewHolder في محوّل RecyclerView لربط ViewHolder بفئة المخزون المناسبة.

تطبيق ميزة الاشتراك في المواضيع

1. في طريقة subscribeToStockCategory، عليك تنفيذ طلب البيانات من واجهة برمجة التطبيقات subscribeToTopic للكائن FirebaseMessaging. قد تبدو التعليمة البرمجية كما يلي:

   void subscribeToStockCategory() {
      // Making call to FCM for subscribing to the topic for stockCategory
     FirebaseMessaging.getInstance().subscribeToTopic(stockCategory.getTopicName()).addOnSuccessListener(
          unused -> {
            // Subscribing action successful
            Log.i(TAG, "Subscribed to topic: " + stockCategory.getTopicName());
            Toast.makeText(itemView.getContext(), "Subscribed to " + stockCategory.getCategoryName(),
                Toast.LENGTH_SHORT).show();
          });
    }

تطبيق إلغاء الاشتراك في المواضيع

1. وبالمثل، في حال استيفاء الشرط الآخر، عليك تنفيذ طلب البيانات إلى واجهة برمجة تطبيقات unsubscribeFromTopic. شيء ما على طول سطور ما يلي:

void unsubscribeFromStockCategory() {
      // Making call to FCM for unsubscribing from the topic for stockCategory
      FirebaseMessaging.getInstance().unsubscribeFromTopic(stockCategory.getTopicName())
          .addOnSuccessListener(unused -> {
            // Unsubscribing action successful
            Log.i(TAG, "Unsubscribed from topic: " + stockCategory.getTopicName());
            Toast.makeText(itemView.getContext(), "Unsubscribed from " + stockCategory.getCategoryName(),
                Toast.LENGTH_SHORT).show();
          });
    }

بدء تجربة

1. شغِّل التطبيق وبدِّل بين خياري "فئة الأسهم" لتنفيذ إجراءي "الاشتراك" و"إلغاء الاشتراك". ستبدو كما يلي:

الاشتراك	إلغاء الاشتراك

7- إرسال رسالة الموضوع الأولى

في هذه الخطوة، ستُنفذ رمز جانب الخادم لإرسال رسالة موضوع خدمة "المراسلة عبر السحابة الإلكترونية من Firebase".

تنفيذ الدمج من جانب الخادم لإرسال رسالة الموضوع

1. في رمز الخادم، انتقِل إلى FcmSender.java وحدِّد موقع الطريقة المسماة sendMessageToFcmTopic.

2. في السطر الأول، حدِّد موضوع "المراسلة عبر السحابة الإلكترونية من Firebase" الذي تريد إرسال الرسالة إليه.
   • وهي سلسلة من النموذج: /topics/<Topic Name>. مثلاً: /topics/Technology
3. في الأسطر التالية، أنشِئ كائن message جديدًا (مشابهًا للكائن المحدّد في الدالة sendMessageToFcmRegistrationToken).
   • سيكون الاختلاف هو ضبط الحقل Topic بدلاً من ضبط الحقل Token لكائن message.

Message message = Message.builder()
        .putData("FOOTECH", "$1000")
        .setNotification(
            Notification.builder()
                .setTitle("Investor confidence in Tech Stocks growing")
                .setBody("Foo Tech leading the way in stock growth for Tech sector.")
                .build())
        .setTopic(topicName)
        .build();

4. الآن أضف الاستدعاء إلى مثيل FirebaseMessaging لإرسال الرسالة (يتطابق مع استدعاء الإرسال الذي يتم إجراؤه في الدالة sendMessageToFcmRegistrationToken).

FirebaseMessaging.getInstance().send(message);

5. أخيرًا، عليك تعديل الدالة main وتفعيل الطلب إلى الدالة sendMessageToFcmTopic فقط.

إرسال رسالة والتحقق من صحة الإيصال

1. قبل إرسال رسالة الموضوع، تأكَّد أولاً من اشتراك مثيل تطبيقك في الموضوع الذي تريد الإرسال إليه.
   1. ويمكن إجراء ذلك من خلال قلب مفتاح التبديل المقابل. على سبيل المثال:
   
2. يمكنك الآن إرسال رسالة الموضوع عن طريق تنفيذ الوظيفة main في FcmSender.java.
3. وكما هو الحال قبل أن تتمكن من ملاحظة إيصال الرسالة على مثيل التطبيق.
   1. مثيل التطبيق في المقدّمة
   
   2. النسخة الافتراضية للتطبيق في الخلفية
   
4. ميزة إضافية: حاوِل إلغاء الاشتراك في الموضوع الذي أرسلت إليه ثم أعِد إرسال الرسالة. ستلاحظ أن الرسالة لا يتم تسليمها إلى مثيل التطبيق.

8- إرسال أول رسالة عن حالة الموضوع

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

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

تسمح لك Topics بالتعبير عن مجموعتك في شكل تعبير منطقي باستخدام عوامل التشغيل التالية

• & : منطقية AND. على سبيل المثال، 'Technology' in topics && 'Automotive' in topics: يستهدف فقط النُسخ الافتراضية من التطبيق المرتبطة بكل من "مواضيع التكنولوجيا" و"مواضيع السيارات".
• || : منطقي OR. على سبيل المثال، 'Technology' in topics || 'Automotive' in topics: استهداف النُسخ الافتراضية من التطبيقات التي اشتركت في مواضيع التكنولوجيا أو السيارات.
• () : أقواس التجميع. على سبيل المثال، 'Technology' in topics && ('Automotive' in topics || 'Energy' in topics): يستهدف هذا النوع من التطبيقات فقط النُسخ الافتراضية من التطبيق المشتركين في "التكنولوجيا" و"السيارات" أو "الطاقة".

اطّلِع على مزيد من المعلومات عن كيفية إنشاء طلبات إرسال لاستخدام هذه الوظيفة.

تنفيذ الدمج من جهة الخادم لإرسال رسالة شرط الموضوع

1. ارجع إلى رمز الخادم، وانتقل إلى FcmSender.java وحدِّد موقع الطريقة المسماة sendMessageToFcmTopicCondition.

2. في السطر الأول، بالنسبة إلى المتغيّر topicCondition، قدِّم شرط الموضوع الذي تريد إرسال الرسالة إليه. يمكنك ضبطها على: 'Technology' in topics && 'Automotive' in topics.
3. في الأسطر التالية، أنشِئ كائن message جديدًا (مشابهًا للكائن المحدّد في الدالة sendMessageToFcmTopic).
   1. سيكون الاختلاف هو ضبط الحقل Condition بدلاً من ضبط الحقل Topic للعنصر.

    Message message = Message.builder()
        .putData("FOOCAR", "$500")
        .setNotification(
            Notification.builder()
                .setTitle("Foo Car shows strong Q2 results")
                .setBody("Foo Car crosses 1B miles. Stocks rally.")
                .build())
        .setCondition(topicCondition)
        .build();

4. الآن أضف الاستدعاء إلى مثيل FirebaseMessaging لإرسال الرسالة (يتطابق مع استدعاء الإرسال الذي يتم إجراؤه في الدالة sendMessageToFcmTopic).

FirebaseMessaging.getInstance().send(message);

5. أخيرًا، عليك تعديل الدالة main وتفعيل الطلب إلى الدالة sendMessageToFcmTopicCondition فقط.

إرسال الرسالة والتحقق من صحة الإيصال

1. قبل إرسال رسالة الموضوع، تأكَّد أولاً من أنّ مثيل تطبيقك يفي بشرط الموضوع المحدّد من خلال اشتراك نسخة التطبيق الافتراضية في كل من موضوعَي التكنولوجيا والسيارات.
2. يمكنك الآن إرسال رسالة الموضوع عن طريق تنفيذ الوظيفة main في FcmSender.java.
3. وكما في السابق، يجب أن يكون بإمكانك ملاحظة إيصال الرسالة على مثيل التطبيق.
   1. مثيل التطبيق في المقدّمة
   
   2. النسخة الافتراضية للتطبيق في الخلفية
   
4. ميزة إضافية: يمكنك الآن إلغاء الاشتراك في موضوع التكنولوجيا وإعادة إرسال رسالة حالة الموضوع. يجب ملاحظة أنّ مثيل التطبيق لا يتلقّى الرسالة.

9- ملخص المباراة

لنلخص سريعًا ما تعلمته حتى هذه النقطة.

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

ملاحظة: يُرجى تخصيص بعض الوقت للتفكير في كيفية استخدام المواضيع وشروطها لتعزيز تفاعل مستخدمي تطبيقك.

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

10- إدارة الاشتراكات في المواضيع من جهة الخادم

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

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

في هذا القسم، ستتعلّم كيفية استخدام حزمة تطوير البرامج (SDK) لمشرف Firebase للاشتراك وإلغاء الاشتراك في مجموعة من الرموز المميّزة لتسجيل خدمة FCM في موضوع معيّن من خلال إجراء اتصالات من جهة الخادم.

تنفيذ اشتراك من جهة الخادم للرموز المميّزة للتسجيل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" في موضوع المراسلة عبر السحابة الإلكترونية من Firebase

1. في رمز الخادم، انتقِل إلى صف واحد (FcmSubscriptionManager.java). حدِّد موقع الطريقة المسماة subscribeFcmRegistrationTokensToTopic. سيتم تنفيذ طلب واجهة برمجة تطبيقات subscribeToTopic هنا.

2. لنشترك مثيل التطبيق في موضوع "Energy" (الطاقة). لإجراء ذلك، عليك أولاً توفير بيانات للحقلَين التاليَين:
   1. registrationTokens: قائمة مفصولة بفواصل من السلاسل تمثّل الرموز المميّزة للتسجيل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" التي تريد إنشاء اشتراكات مواضيع لها.
   2. topicName: اسم الموضوع لموضوع "الطاقة"، أي /topics/Energy.
3. في الأسطر القليلة التالية، نفِّذ المكالمة، على النحو التالي:

TopicManagementResponse response = FirebaseMessaging.getInstance().subscribeToTopic(
        registrationTokens, topicName);

4. يمكنك فحص TopicManagementResponse للاطّلاع على بعض إحصاءات النتائج العالية المستوى. مثل طباعة عدد اشتراكات المواضيع التي تم إنشاؤها بنجاح باستخدام getSuccessCount.

System.out.printf("Num tokens successfully subscribed %d", response.getSuccessCount());

5. وأخيرًا، في الدالة main، فعِّل عمليات الاستدعاء للدالة subscribeFcmRegistrationTokensToTopic فقط.

إنشاء اشتراك وإرسال رسالة حول الموضوع

1. في هذه المرحلة، ستكون جاهزًا لإنشاء الاشتراك في الموضوع وإرسال رسالة إليه.
2. نفِّذ الدالة main لفئة FcmSubscriptionManager.java. سيؤدي هذا الإجراء إلى إنشاء اشتراك في موضوع.
3. والآن، يجب إعداد الرمز لإرسال الرسالة. على غرار ما سبق،
   1. في FcmSender.java، حدِّد موقع الدالة sendMessageToFcmTopic.
   2. اضبط السمة topicName على موضوع "الطاقة"، أي /topics/Energy
   3. أنشِئ كائن Message ووجّهه إلى الموضوع باستخدام setTopic.
   4. وأخيرًا، عدِّل الطريقة main لتفعيل الدالة sendMessageToFcmTopic فقط.
4. نفِّذ الدالة main لـ FcmSender.java. سيؤدي ذلك إلى إرسال الرسالة إلى مثيل تطبيقك ويمكنك ملاحظتها في تطبيقك على النحو التالي.
   1. مثيل التطبيق في المقدّمة
   
   2. النسخة الافتراضية للتطبيق في الخلفية
   

إلغاء الاشتراك من جهة الخادم للرموز المميّزة للتسجيل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" لموضوع خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"

1. لإلغاء الاشتراك في المواضيع من جهة الخادم، استخدِم واجهة برمجة التطبيقات unsubscribeFromTopic هذه. عليك إضافة الرمز ذي الصلة إلى الدالة unsubscribeFcmRegistrationTokensFromTopic في الفئة FcmSubscriptionManager.java.

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

11- تهانينا

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

ما هي الخطوات التالية؟

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

• مواضيع "المراسلة عبر السحابة الإلكترونية من Firebase" لنظام التشغيل iOS
• مواضيع "المراسلة عبر السحابة الإلكترونية من Firebase" للويب

المستندات المرجعية

• مرجع واجهة برمجة تطبيقات Android ( Java / Kotlin)
• مرجع واجهة برمجة تطبيقات iOS ( ObjectiveC / Swift)
• مرجع واجهة برمجة تطبيقات JavaScript ( الإصدار 9 / الإصدار 8)
• مرجع SDK للمشرف ( Node.js / Java / Python / .NET)