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

1. مقدمة

الأهداف

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

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

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

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

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

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

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

ما ستتعلمه

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

ما ستنشئه

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

المتطلبات

• متصفّح من اختيارك، مثل Chrome
• IntelliJ IDEA هي بيئة تطوير متكاملة (IDE) لتطوير تطبيقات 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.

ضبط Android

1. في وحدة تحكّم 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، واستورِد 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. سيتم إنشاء رمز تسجيل صالح في خدمة FCM وتسجيله.
• يضيف MainActivity.java RecyclerView الذي يعرض خيارات "فئة السلع".
• تنفِّذ SubscriptionAdapter.java الفئة RecyclerView.Adapter التي تعرض شاشة اختيار فئة المستودع.
  • تحتوي كل فئة من فئات الأسهم على اسم ومفتاح تبديل اشتراك بجانبها.
  • يجب أن يؤدي تغيير زر التبديل إلى إجراء طلب اشتراك / إلغاء اشتراك في موضوع FCM.
  • ستنفّذ هذه الاستدعاءات في الأقسام القادمة.
• يحتوي الصف model/StockCategories.java على قائمة بجميع فئات الأسهم وأسماء المواضيع المرتبطة بها.

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

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

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

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

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

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

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

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

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

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

التعرّف على الرمز الأوّلي للخادم

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

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

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

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

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

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

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

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

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

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

رمز المراجعة

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

• تُعدّ الدالة الإنشائية للفئة أداة معالجة لزر التبديل بين الاشتراك وعدم الاشتراك باستخدام 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.

2. في السطر الأول، أدخِل موضوع "مراسلة Firebase السحابية" الذي تريد إرسال الرسالة إليه.
   • وهي سلسلة بالتنسيق: /topics/<Topic Name>. على سبيل المثال، /topics/Technology.
3. في الأسطر التالية، أنشئ عنصر 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();

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

FirebaseMessaging.getInstance().send(message);

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

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

1. قبل إرسال رسالة الموضوع، تأكَّد أولاً من أنّ مثيل تطبيقك مشترك في الموضوع الذي تريد الإرسال إليه.
   1. ويمكن إجراء ذلك من خلال النقر على زر التبديل المقابل. على سبيل المثال:
   
2. يمكنك الآن إرسال رسالة الموضوع من خلال تنفيذ الدالة main الخاصة بـ FcmSender.java.
3. كما كان من قبل، يجب أن تتمكّن من ملاحظة استلام الرسالة على مثيل التطبيق.
   1. مثيل التطبيق في المقدّمة
   
   2. مثيل التطبيق في الخلفية
   
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.

2. في السطر الأول، بالنسبة إلى المتغيّر topicCondition، أدخِل شرط الموضوع الذي تريد إرسال الرسالة إليه. يمكنك ضبطها على: 'Technology' in topics && 'Automotive' in topics.
3. في الأسطر التالية، أنشئ عنصر 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();

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

FirebaseMessaging.getInstance().send(message);

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

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

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

9. ملخّص

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

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

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

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

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

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

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

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

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

2. لنُسجّل مثيل التطبيق في موضوع "الطاقة". لإجراء ذلك، عليك أولاً تقديم بيانات للحقلَين التاليَين:
   1. ‫registrationTokens: قائمة سلاسل مفصولة بفواصل تمثّل رموز التسجيل في FCM التي تريد إنشاء اشتراكات في المواضيع لها.
   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 السحابية لإرسال رسائل البث المتعدّد الوجهات إلى مجموعات فرعية من مثيلات تطبيقك. سيساعدك ذلك في تبسيط قدرتك على الوصول إلى المستخدمين في الوقت المناسب من خلال المحتوى ذي الصلة.

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

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

• مواضيع FCM على أجهزة iOS
• مواضيع FCM للويب

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

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