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

1. مقدمة

الأهداف

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

بعد الانتهاء، ستتمكّن من الاستفادة من البنية الأساسية لخدمة FCM لإدارة هذه المجموعات الفرعية بالإضافة إلى إرسال رسائل الإشعارات المتعددة إلى المجموعات الفرعية.

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

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

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

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

تم تحسين البث المتعدد المستند إلى المواضيع لتحقيق معدل نقل بيانات أفضل.

ما ستتعلمه

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

ما ستنشئه

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

المتطلبات

  • متصفّح من اختيارك، مثل Chrome
  • بيئة التطوير المتكاملة IntelliJ IDEA لتطوير تطبيقات Java
    • احرص على تفعيل دعم Gradle أثناء التثبيت.
  • استوديو Android: بيئة تطوير متكاملة (IDE) لتطوير تطبيقات 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 باستخدام حسابك على Google.
  2. انقر على الزر لإنشاء مشروع جديد، ثم أدخِل اسم المشروع (على سبيل المثال، StockNews).
  3. انقر على متابعة.
  4. إذا طُلب منك ذلك، راجِع بنود Firebase واقبلها، ثم انقر على متابعة.
  5. (اختياري) فعِّل ميزة "المساعدة المستندة إلى الذكاء الاصطناعي" في وحدة تحكّم Firebase (المعروفة باسم "Gemini في Firebase").
  6. في هذا الدرس العملي، لا تحتاج إلى "إحصاءات Google"، لذا أوقِف خيار "إحصاءات Google".
  7. انقر على إنشاء مشروع، وانتظِر إلى أن يتم توفير مشروعك، ثم انقر على متابعة.

تهانينا! لقد أنشأت للتو مشروعك على Firebase.

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

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

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

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

84e0b3199bef6d8a.pngضبط Android

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

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

  1. القيمة المهمة التي يجب تقديمها هي اسم حزمة Android. اضبطه على com.ticker.stocknews.
    1. يجب أن يكون اسم الحزمة المقدَّم هنا هو نفسه المقدَّم في AndroidManifest.xml لرمز StockNewsApp الأوّلي. إذا أردت تحديد موقعها أو تغييرها، اتّبِع الخطوات التالية:
      1. في دليل StockNewsApp، افتح الملف app/src/main/AndroidManifest.xml.
      2. في العنصر manifest، ابحث عن قيمة السلسلة للسمة package. هذه القيمة هي اسم حزمة Android.
  1. في مربّع حوار Firebase، الصِق اسم الحزمة المنسوخ في الحقل اسم حزمة Android.
  2. لست بحاجة إلى شهادة توقيع تصحيح الأخطاء SHA-1 في هذا الدرس العملي، لأنّه لن يتم إصدار هذا التطبيق. اترك هذا الحقل فارغًا.
  3. انقر على تسجيل التطبيق.
  4. في وحدة تحكّم Firebase، اتّبِع التعليمات لتنزيل ملف الإعداد google-services.json.
  5. يمكنك تخطّي خطوات الإعداد المتبقية، لأنّ كل شيء آخر تم إعداده مسبقًا في رمز تطبيق البداية. سيظهر تطبيقك في الصفحة الرئيسية لوحدة تحكّم Firebase.
  6. انسخ الملف google-services.json (الذي نزّلته للتو) إلى الدليل messaging/fcm-topics-codelab/starter/StockNewsApp/app.

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

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

استيراد تطبيق البداية

ابدأ تشغيل Android Studio، واستورِد messaging/fcm-topics-codelab/starter/StockNewsApp من دليل الرموز البرمجية المُعدّة مسبقًا للمبتدئين.

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

في أعلى يمين نافذة المشروع، من المفترض أن يظهر لك ما يشبه الصورة أدناه إذا كنت في طريقة العرض Android. (إذا كنت في طريقة عرض المشروع، عليك توسيع المشروع لرؤية الشيء نفسه)

b574ea0089ee87c6.png

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

4bc64eb3b99eb0ae.png

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

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

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

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

التعرّف على الرمز الأوّلي لتطبيق Android

f04ff8f48d186dff.png

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

b32663ec4e865a18.png

تشغيل تطبيق المبتدئين

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

5b27fc5b237e06b9.png

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

ff5b1a1c53231c54.png

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

927eb66bc909f36b.png

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

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

استيراد رمز الخادم المبدئي

ابدأ IntelliJ IDEA وافتح مشروع messaging/fcm-topics-codelab/starter/StockNewsServer.

يجب أن يظهر عرض المشروع في شريط التنقّل الأيمن على النحو التالي:

da20711f6527dff6.png

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

التعرّف على رمز بدء تشغيل الخادم

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

650fc733298588f8.png

  • أخيرًا، هناك فئتان، وهما:
    • ‫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-admin بتفويض طلبات إلى واجهات برمجة تطبيقات FCM.
    1. انتقِل إلى "وحدة تحكّم Firebase"، وانقر على رمز الترس بجانب نظرة عامة على المشروع في شريط التنقّل الأيمن، ثم اختَر إعدادات المشروع. 8c2108d4d7c915e9.png
    2. في صفحة الإعدادات، اختَر حسابات الخدمة وانقر على إنشاء حساب خدمة. 84b128cc5dac0a85.png
    3. انقر الآن على الزر إنشاء مفتاح خاص جديد وسيبدأ التنزيل التلقائي لملف المفتاح.
    4. أعِد تسمية ملف المفتاح إلى service-account.json وانسخه في المجلد messaging/fcm-topics-codelab/starter/StockNewsServer/src/main/resources.
    5. يحمّل كلّ من FcmSender.java وFcmSubscriptionManager.java الملف service-account.json من مسار الفئة باستخدام الرمز التالي. 8dffbee658e0bdd.png
  2. في هذه المرحلة، يكون رمز الخادم جاهزًا. نفِّذ "إنشاء" -> "إنشاء المشروع" من شريط القوائم في أعلى الصفحة.

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

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

52e4a3ec3f816473.png

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

d3540ec1089f97dd.png

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

31203deca59c03fe.png

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

6. تنفيذ ميزة الاشتراك في المواضيع أو إلغاء الاشتراك فيها

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

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

رمز المراجعة

  • انتقِل إلى الفئة SubscriptionAdapter.java في رمز تطبيق Android وابحث عن الفئة RecyclerViewViewHolder.

6c0614199e684f6.png

  • تُعدّ الدالة الإنشائية للفئة أداة معالجة لزر التبديل الخاص بالاشتراك باستخدام setOnCheckedChangeListener.
  • استنادًا إلى زر التبديل، يتم تنفيذ إجراءات الاشتراك وإلغاء الاشتراك من خلال استدعاء الطريقتَين subscribeToStockCategory وunsubscribeFromStockCategory على التوالي.
  • يتم استدعاء الطريقة setData من خلال onBindViewHolder في أداة RecyclerView Adapter لربط 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. وبالمثل، في شرط else، ستنفّذ طلب البيانات من واجهة برمجة التطبيقات 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. إرسال رسالة الموضوع الأولى

في هذه الخطوة، ستنفّذ رمزًا من جهة الخادم لإرسال رسالة موضوع FCM.

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

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

56381dd1b40cde9c.png

  1. في السطر الأول، أدخِل موضوع FCM الذي تريد إرسال الرسالة إليه.
    • وهي سلسلة بالتنسيق: /topics/<Topic Name>. على سبيل المثال، /topics/Technology.
  2. في الأسطر التالية، أنشئ كائن message جديدًا (مشابهًا للكائن المحدّد في الدالة sendMessageToFcmRegistrationToken).
    • بدلاً من ضبط الحقل Token للكائن message، عليك ضبط الحقل Topic.
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();
  1. الآن، أضِف طلبًا إلى مثيل FirebaseMessaging لإرسال الرسالة (مطابقًا لطلب الإرسال الذي تم إجراؤه في الدالة sendMessageToFcmRegistrationToken).
FirebaseMessaging.getInstance().send(message);
  1. أخيرًا، عدِّل الدالة main وفعِّل استدعاء الدالة sendMessageToFcmTopic فقط.

9a6aa08dd7c28898.png

إرسال رسالة والتحقّق من استلامها

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

8. إرسال رسالة شرط الموضوع الأولى

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

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

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

  • && : Logical 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.

3719a86c274522cf.png

  1. في السطر الأول، بالنسبة إلى المتغيّر topicCondition، أدخِل شرط الموضوع الذي تريد إرسال الرسالة إليه. يمكنك ضبطه على: 'Technology' in topics && 'Automotive' in topics.
  2. في الأسطر التالية، أنشئ عنصر message جديدًا (مشابهًا للعنصر المحدّد في الدالة sendMessageToFcmTopic).
    1. بدلاً من ضبط الحقل Topic للكائن، عليك ضبط الحقل Condition.
    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();
  1. الآن، أضِف طلبًا إلى مثيل FirebaseMessaging لإرسال الرسالة (مطابقًا لطلب الإرسال الذي تم إجراؤه في الدالة sendMessageToFcmTopic).
FirebaseMessaging.getInstance().send(message);
  1. أخيرًا، عدِّل الدالة main وفعِّل استدعاء الدالة sendMessageToFcmTopicCondition فقط.

db9588d40d2a0da6.png

إرسال الرسالة والتحقّق من استلامها

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

9. ملخّص

دعنا نلخّص سريعًا ما تعلّمته حتى الآن.

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

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

c0dc20655d392690.gif

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

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

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

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

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

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

5d5709e7b3cbcb04.png

  1. لنُنشئ اشتراكًا لمثيل التطبيق في موضوع "الطاقة". لإجراء ذلك، عليك أولاً تقديم بيانات للحقلَين التاليَين:
    1. ‫registrationTokens: قائمة سلاسل مفصولة بفواصل تمثّل رموز التسجيل في FCM التي تريد إنشاء اشتراكات في مواضيع لها.
    2. topicName: اسم الموضوع الخاص بموضوع "الطاقة"، أي /topics/Energy
  2. في الأسطر القليلة التالية، نفِّذ عملية الاتصال على النحو التالي:
TopicManagementResponse response = FirebaseMessaging.getInstance().subscribeToTopic(
        registrationTokens, topicName);
  1. يمكنك فحص TopicManagementResponse للاطّلاع على بعض الإحصاءات العامة للنتائج. مثل طباعة عدد الاشتراكات في المواضيع التي تم إنشاؤها بنجاح باستخدام getSuccessCount.
System.out.printf("Num tokens successfully subscribed %d", response.getSuccessCount());
  1. أخيرًا، في الدالة 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. مثيل التطبيق في المقدّمة
    40ab6cf71e0e4116.png
    1. مثيل التطبيق في الخلفية
    8fba81037198209e.png

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

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

8d9e8ea9d34016bd.png

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

11. تهانينا

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

947def3eb33b1e4a.gif

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

بعد إكمال هذا الدرس العملي، ننصحك بتجربة مواضيع لمنصات أخرى باستخدام الأدلة التالية:

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