Topic Subscription در اعلان‌های پوش — چیست، چگونه کار می‌کند و تنظیم می‌شود

Topic Subscription در FCM چیست

Topic Subscription — مکانیزم ارسال گروهی اعلان‌های فشاری است که در آن دستگاه‌ها در کانال‌های نام‌گذاری شده (موضوعات) مشترک می‌شوند و پیام‌های ارسال شده به این کانال‌ها را دریافت می‌کنند. هر موضوع با یک نام رشته‌ای مشخص می‌شود، مثلاً news_sports یا weather_alerts.

اصل کار موضوعات

وقتی دستگاهی در یک موضوع مشترک می‌شود، FCM Registration Token آن را به لیست دریافت‌کنندگان آن موضوع اضافه می‌کند. هنگام ارسال پیام به یک موضوع، FCM به طور خودکار یک کپی به هر دستگاه مشترک تحویل می‌دهد. Firebase تعداد اشتراک‌های یک دستگاه را محدود نمی‌کند — برنامه می‌تواند کاربر را همزمان در ده‌ها موضوع مشترک کند.

موضوعات در مقابل ارسال فردی

مزیت اصلی موضوعات مقیاس‌پذیری است. برای ارسال اعلان به یک میلیون کاربر، یک درخواست HTTP به FCM با نام موضوع کافی است. در ارسال فردی به یک میلیون درخواست یا ارسال دسته‌ای حداکثر 500 توکن در هر بار نیاز بود. موضوعات همچنین منطق سمت سرور را ساده‌تر می‌کنند — نیازی به ذخیره لیست توکن‌ها برای هر دسته نیست.

نمونه‌های استفاده از موضوعات

Topic Subscription به طور گسترده در برنامه‌های خبری برای دسته‌بندی محتوا استفاده می‌شود — اشتراک در موضوعات "ورزش"، "سیاست"، "فناوری" امکان تحویل اعلان‌های مرتبط را فراهم می‌کند. در تجارت الکترونیک از موضوعات برای اعلان تخفیف‌ها در دسته‌های خاص محصولات استفاده می‌شود. در پیام‌رسان‌ها و شبکه‌های اجتماعی از موضوعات برای اعلان رویدادها در گروه‌ها استفاده می‌شود.

محدودیت‌های FCM

Firebase محدودیت‌هایی برای کار با موضوعات اعمال می‌کند. یک برنامه می‌تواند تا 2000 موضوع داشته باشد. هر دستگاه می‌تواند حداکثر در 2000 موضوع مشترک شود. تعداد اشتراک/لغو اشتراک نیز محدود است — حداکثر 3000 عملیات در دقیقه برای هر پروژه. تجاوز از محدودیت‌ها منجر به مسدودیت موقت می‌شود. برای پروژه‌هایی با تعداد موضوعات زیاد، توصیه می‌شود به جای موضوع از شرط (condition) استفاده کنید — FCM از عبارات منطقی برای هدف‌گیری پشتیبانی می‌کند.

اشتراک موضوع چگونه کار می‌کند

فرآیند Topic Subscription از سه مرحله تشکیل شده است: راه‌اندازی اشتراک در کلاینت، ثبت در زیرساخت 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 API REST برای مدیریت انبوه اشتراک‌ها فراهم می‌کند. متد /v1/projects/{project_id}/subscriptions امکان اشتراک تا 1000 دستگاه را در یک درخواست فراهم می‌کند. API از Registration Token دستگاه‌ها برای شناسایی استفاده می‌کند.

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)
    }
}

سناریوهای استفاده از مدیریت سمت سرور

مدیریت سمت سرور اشتراک‌ها در چندین سناریو استفاده می‌شود. هنگام ثبت‌نام کاربر، سرور به طور خودکار او را در موضوعات پایه مشترک می‌کند. هنگام تغییر تنظیمات در نسخه وب، سرور اشتراک‌ها را در دستگاه موبایل همگام‌سازی می‌کند. مدیران می‌توانند دستگاه‌های آزمایشی را برای اشکال‌زدایی در موضوعات داخلی مشترک کنند. برای عملیات انبوه، FCM متد Instance Group را فراهم می‌کند که امکان مدیریت اشتراک‌های گروهی از دستگاه‌ها را از طریق یک شناسه گروه فراهم می‌کند.

نظارت بر وضعیت اشتراک‌ها

Firebase API داخلی برای بررسی اشتراک‌های فعلی دستگاه فراهم نمی‌کند. به توسعه‌دهندگان توصیه می‌شود پایگاه داده اشتراک‌های خود را در سمت سرور نگهداری کنند. در هر راه‌اندازی برنامه، کلاینت اشتراک‌های خود را با ارسال لیست موضوعات فعال با سرور همگام‌سازی می‌کند. این امکان تشخیص عدم همگام‌سازی و بازیابی اشتراک‌ها در صورت نیاز را فراهم می‌کند. برای حسابرسی از لاگ‌های Firebase Cloud Functions استفاده کنید — هر عملیات subscribe/unsubscribe می‌تواند ثبت شود.