الاشتراك في المواضيع في الإشعارات الفورية — ما هو، كيف يعمل وكيف يتم إعداده

ما هو الاشتراك في المواضيع في FCM

الاشتراك في المواضيع هو آلية توصيل جماعي للإشعارات الفورية حيث تشترك الأجهزة في قنوات مسماة (مواضيع) وتتلقى الرسائل المرسلة إلى تلك القنوات. يتم تعريف كل موضوع باسم نصي، مثل news_sports أو weather_alerts.

مبدأ عمل المواضيع

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

المواضيع مقابل الإرسال الفردي

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

حالات استخدام المواضيع

يستخدم الاشتراك في المواضيع على نطاق واسع في تطبيقات الأخبار لتصنيف المحتوى — الاشتراك في مواضيع «الرياضة» و«السياسة» و«التكنولوجيا» يتيح توصيل الإشعارات ذات الصلة. في التجارة الإلكترونية، تُستخدم المواضيع للإشعارات حول الخصومات في فئات محددة من المنتجات. في تطبيقات المراسلة والشبكات الاجتماعية، تُستخدم المواضيع للإشعارات حول الأحداث في المجموعات.

قيود FCM وحدوده

يفرض Firebase قيودًا على العمل مع المواضيع. يمكن أن يحتوي التطبيق الواحد على ما يصل إلى 2000 موضوع. يمكن لكل جهاز الاشتراك في ما لا يزيد عن 2000 موضوع. كما أن تكرار عمليات الاشتراك/إلغاء الاشتراك محدود — لا يزيد عن 3000 عملية في الدقيقة لكل مشروع. يؤدي تجاوز هذه الحدود إلى حظر مؤقت. للمشاريع التي تحتوي على عدد كبير من المواضيع، يوصى باستخدام الشروط بدلاً من المواضيع — يدعم FCM التعبيرات المنطقية للاستهداف.

كيف يعمل الاشتراك في المواضيع

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

دورة حياة الاشتراك

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

إنشاء الموضوع تلقائيًا

ليس من الضروري إنشاء الموضوع مسبقًا في وحدة تحكم Firebase. عند اشتراك أول جهاز في موضوع باسم news_promo، يقوم FCM بإنشائه تلقائيًا. إذا ألغى آخر جهاز اشتراكه، يبقى الموضوع في النظام ولكن غير نشط، ويستأنف العمل عند حدوث اشتراك جديد.

الاشتراك في المواضيع على Android

على Android، يتم الاشتراك وإلغاء الاشتراك في المواضيع عبر FirebaseMessaging SDK. تقبل طريقتا subscribeToTopic() و unsubscribeFromTopic() اسم الموضوع كمعامل. العمليات غير متزامنة وتتطلب معالجة النتيجة.

الاشتراك الأساسي في موضوع

للاشتراك، يكفي استدعاء subscribeToTopic() مع اسم الموضوع المستهدف. يقوم Firebase SDK بإدارة طلبات الشبكة وإعادة المحاولة تلقائيًا عند الفشل. يوصى بالاشتراك في المواضيع بعد الحصول بنجاح على Registration Token.

class TopicSubscriber(private val context: Context) {

    fun subscribeToNewsTopic() {
        FirebaseMessaging.getInstance()
            .subscribeToTopic("news_latest")
            .addOnCompleteListener { task ->
                val msg = if (task.isSuccessful) {
                    "Subscribed to news topic"
                } else {
                    "Subscription failed"
                }
                Log.d("FCM", msg)
            }
    }

    fun unsubscribeFromNewsTopic() {
        FirebaseMessaging.getInstance()
            .unsubscribeFromTopic("news_latest")
            .addOnCompleteListener { task ->
                Log.d("FCM", "غير مشترك: ${task.isSuccessful}")
            }
    }
}

إدارة الاشتراكات المتعددة

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

class SubscriptionManager(private val context: Context) {

    private val fcm = FirebaseMessaging.getInstance()

    suspend fun syncSubscriptions(topics: List<String>) {
        topics.forEach { topic ->
            fcm.subscribeToTopic(topic).await()
        }
    }

    suspend fun removeAllSubscriptions() {
        val savedTopics = getSavedTopics()
        savedTopics.forEach { topic ->
            fcm.unsubscribeFromTopic(topic).await()
        }
    }

    private fun getSavedTopics(): List<String> {
        return listOf("news_latest", "promotions", "updates")
    }
}

الاشتراك في المواضيع على iOS

على iOS، عملية الاشتراك في المواضيع مماثلة لـ Android من حيث المنطق ولكنها تستخدم Swift API لـ Firebase Messaging. يتم استدعاء طريقتي subscribe و unsubscribe على مثيل Messaging وهي أيضًا غير متزامنة.

تنفيذ الاشتراك على iOS

للاشتراك في موضوع في تطبيق iOS، استخدم طريقة Messaging.subscribe(). من المهم استدعاء الاشتراك بعد تهيئة Firebase والحصول على Registration Token. توصي Apple بطلب إذن الإشعارات قبل الاشتراك في المواضيع.

import FirebaseMessaging

class PushTopicManager {

    func subscribeToTopic(topic: String) {
        Messaging.messaging().subscribe(toTopic: topic) { error in
            if let error = error {
                Log.e("FCM", "خطأ في الاشتراك: \(error)")
            } else {
                Log.d("FCM", "تم الاشتراك في \(topic)")
            }
        }
    }

    func unsubscribeFromTopic(topic: String) {
        Messaging.messaging().unsubscribe(fromTopic: topic) { error in
            if let error = error {
                Log.e("FCM", "خطأ في إلغاء الاشتراك: \(error)")
            }
        }
    }
}

خصائص الاشتراكات على iOS

على iOS، يرتبط الاشتراك في الموضوع أيضًا بـ Registration Token الذي يستقبله Firebase من APNs. إذا تغير رمز APNs (على سبيل المثال، بعد استعادة الجهاز)، يقوم Firebase تلقائيًا بنقل الاشتراكات إلى الرمز الجديد. ومع ذلك، في حالات نادرة، قد تكون إعادة الاشتراك مطلوبة بعد تحديث Registration Token.

إدارة الاشتراكات من الخادم

تتيح الإدارة من الخادم للاشتراكات إمكانية اشتراك الأجهزة وإلغاء اشتراكها دون إشراك تطبيق العميل. هذا مفيد للإدارة واختبار A/B وإدارة الاشتراكات من جانب backend.

FCM HTTP API لإدارة الاشتراكات

يوفر Firebase REST API للإدارة الجماعية للاشتراكات. يسمح نقطة النهاية /v1/projects/{project_id}/subscriptions باشتراك ما يصل إلى 1000 جهاز في طلب واحد. يستخدم API Registration Tokens للأجهزة للتحديد.

const admin = require("firebase-admin")

async function subscribeUsersToTopic(tokens, topic) {
    try {
        const response = await admin
            .messaging()
            .subscribeToTopic(tokens, topic)
        Log.info(`Success: ${response.successCount}`)
        Log.info(`Failures: ${response.failureCount}`)
    } catch (error) {
        Log.error("خطأ في الاشتراك", error)
    }
}

حالات استخدام الإدارة من الخادم

تُستخدم إدارة الاشتراكات من الخادم في عدة سيناريوهات. عند تسجيل المستخدم، يقوم الخادم تلقائيًا باشتراكه في المواضيع الأساسية. عندما تتغير التفضيلات في الإصدار web، يقوم الخادم بمزامنة الاشتراكات على الجهاز المحمول. يمكن للمسؤولين اشتراك أجهزة الاختبار في المواضيع الداخلية لتصحيح الأخطاء. للعمليات الجماعية، يوفر FCM طريقة Instance Group، التي تتيح إدارة اشتراكات مجموعة من الأجهزة من خلال معرف مجموعة واحد.

مراقبة حالة الاشتراكات

لا يوفر Firebase API مدمج للتحقق من الاشتراكات الحالية للجهاز. يُنصح المطورون بالاحتفاظ بقاعدة بيانات الاشتراكات الخاصة بهم على جانب الخادم. عند كل بدء تشغيل للتطبيق، يقوم العميل بمزامنة اشتراكاته مع الخادم عن طريق إرسال قائمة المواضيع النشطة. يساعد هذا في تحديد عدم التزامن واستعادة الاشتراكات إذا لزم الأمر. لمراجعة التدقيق، استخدم سجلات Firebase Cloud Functions — يمكن تسجيل كل عملية اشتراك/إلغاء اشتراك.