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

1. مقدمة

الأهداف

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

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

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

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

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

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

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

ما ستتعلمه

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

ما ستنشئه

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

المتطلبات

  • متصفّح من اختيارك، مثل 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، واستورِد messaging/fcm-topics-codelab/starter/StockNewsApp من دليل الرمز الأوّلي.

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

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

b574ea0089ee87c6.png

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

4bc64eb3b99eb0ae.png

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

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

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

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

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

f04ff8f48d186dff.png

  • في AndroidManifest.xml، تمت إضافة معالج ردّ الاتصال MESSAGING_EVENT.
    • يوسّع معالج الأحداث هذا، StockNewsMessagingService.java، الفئة FirebaseMessagingService التي توفّر وظائف متنوّعة ذات صلة بخدمة "مراسلة Firebase السحابية". لمزيد من المعلومات، يمكنك الاطّلاع على مستندات FirebaseMessagingService. b843c4d33ee53166.png
    88fad1960f4a6ff5.png * يتم استدعاء الدالة `onNewToken` عند إنشاء رمز التسجيل في FCM أو إعادة تحميله. لمزيد من المعلومات، يُرجى الاطّلاع على [مراقبة إنشاء الرموز المميزة](https://firebase.google.com/docs/cloud-messaging/android/client#monitor-token-generation). * يتم استدعاء الدالة `onMessageReceived` عند تلقّي رسالة ويكون التطبيق في المقدّمة. في الوقت الحالي، يتم تسجيل الرسالة المستلَمة فقط. * اطّلِع على [تلقّي الرسائل في تطبيق Android](https://firebase.google.com/docs/cloud-messaging/android/receive) لمعرفة المزيد عن الاختلافات بين تسليم الرسائل ومعالجتها في الخلفية وفي المقدّمة.
  • بالإضافة إلى ذلك، في AndroidManifest.xml، يتم توفير فئة Application في Android باسم StockNewsApplication. a4982a8731492dfc.png ccde692f7f68dc5a.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. في هذه المرحلة، يكون رمز الخادم جاهزًا. نفِّذ الأمر Build -> Build Project من شريط القوائم في أعلى الصفحة.

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

  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 - يستهدف فقط مثيلات التطبيق التي تم الاشتراك فيها في كل من "مواضيع التكنولوجيا" و"مواضيع السيارات".
  • || : تعني "أو" المنطقية. على سبيل المثال، '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: قائمة سلاسل مفصولة بفواصل تمثّل رموز التسجيل في "مراسلة Firebase السحابية" التي تريد إنشاء اشتراكات في مواضيع لها.
    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. تهانينا

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

947def3eb33b1e4a.gif

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

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

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