Registration Token در اعلان‌های push: چیست، روش‌های دریافت و به‌روزرسانی

Registration Token چیست

Registration Token — یک رشته منحصربه‌فرد به طول تا 4096 کاراکتر است که Firebase Cloud Messaging به هر نسخه برنامه تعیین می‌کند. توکن بر اساس شناسه برنامه، دستگاه و حساب Google روی دستگاه شکل می‌گیرد.

ساختار و منصور توکن

Registration Token از یک تسلسل تصادفی کاراکترهای کدگذاری شده در فرمت Base64 تشکیل شده است. FCM از این توکن به عنوان آدرس تحویل استفاده می‌کند — بخش سرور اعلانی را به توکن ارسال می‌کند و FCM آن را به دستگاه مورد نظر هدایت می‌کند. بدون توکن نمی‌توان اعلان push را به کاربر خاصی نسبت داد.

تفاوت با سایر شناسه‌گرها

Registration Token را نباید با Device ID (IMEI) یا Advertising ID اشتباه گرفت. Device ID یک شناسه‌گر سخت‌افزاری دستگاه است و Advertising ID برای تبلیغات هدفمند استفاده می‌شود. Registration Token به ترکیب برنامه و دستگاه وابسته است، به طوری که یک دستگاه می‌تواند برای برنامه‌های مختلف چندین توکن داشته باشد.

وقتی توکن نامعتبر دانسته می‌شود

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

FCM چگونه Registration Token را تعیین می‌کند

Firebase Cloud Messaging Registration Token را در نخستین بار اجرای برنامه، هنگامی که روش getToken() فراخوانی می‌شود، تولید می‌کند. فرآیند شامل بررسی اعتبارنامه‌های Google Play Services و ثبت برنامه در زیرساخت Firebase است.

فرآیند ثبت دستگاه

وقتی دستگاه برای نخستین بار برنامه را با FCM SDK اجرا می‌کند، مورد زیر اتفاق می‌افتد. Firebase SDK وجود Google Play Services را روی دستگاه بررسی می‌کند. سپس SDK با ارسال شناسه برنامه و اطلاعات دستگاه به سرورهای Firebase درخواست می‌فرستد. سرور Firebase یک توکن جدید ایجاد کرده و آن را به برنامه برمی‌گرداند.

مکانیک داخلی FCM

FCM از معماری مبتنی بر اتصالات طولانی استفاده می‌کند. پس از دریافت Registration Token، دستگاه از طریق پروتکل STOMP در Android یا کانال APNs در iOS اتصال دائمی با سرورهای Firebase برقرار می‌کند. وقتی بخش سرور اعلانی را به توکن ارسال می‌کند، FCM دستگاه را توسط توکن پیدا کرده و بار را انتقال می‌دهد.

شرایط بازتولید توکن

Registration Token می‌تواند توسط FCM در موارد زیر بازتولید شود. هنگام بازیابی برنامه از پشتیبان گیری روی دستگاه جدید. هنگام حذف و نصب مجدد برنامه. هنگام پاک کردن داده‌های برنامه از طریق تنظیمات سیستم. هنگام ورود به حساب Google دیگر روی دستگاه. Firebase توصیه می‌کند همیشه برای رصد تغییرات، callback onNewToken را مدیریت کنید.

دریافت Registration Token در Android

در Android Registration Token از طریق Firebase Messaging SDK دریافت می‌شود. فرآیند برای نسخه‌های مختلف SDK متفاوت است — در نسخه‌های جدید به جای FirebaseInstanceId منسوخ، از FirebaseInstallations API استفاده می‌شود.

روش نوین از طریق FirebaseInstallations

از Firebase SDK نسخه 21.0.0 به بعد، روش getToken() از طریق FirebaseMessaging فراخوانی می‌شود. این رویکرد چرخه عمر توکن را به‌طور خودکار مدیریت کرده و در به‌روزرسانی‌های آن مشترک می‌شود.

class MyFirebaseMessagingService : FirebaseMessagingService() {

    override fun onNewToken(token: String) {
        sendRegistrationToServer(token)
    }

    private fun sendRegistrationToServer(token: String) {
        // ارسال توکن به بخش سرور
        Log.d("FCM", "New token: $token")
    }

    init {
        FirebaseMessaging.getInstance()
            .getToken()
            .addOnCompleteListener { task ->
                if (!task.isSuccessful) {
                    Log.w("FCM", "دریافت توکن FCM ناموفق بود")
                    return@addOnCompleteListener
                }
                val token = task.result
                sendRegistrationToServer(token)
            }
    }
}

پردازش توکن در Activity یا ViewModel

در بعضی سناریوها، توکن در خدمت مورد نیاز نیست، بلکه مستقیماً در Activity یا ViewModel مورد نیاز است. برای این منظور می‌توان getToken() را در مکان مناسبی از چرخه عمر برنامه فراخوانی کرد. مهم است که این روش را بدون مدیریت ناهمگامی از رشته اصلی فراخوانی نکنید.

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        getFCMToken()
    }

    private fun getFCMToken() {
        FirebaseMessaging.getInstance().getToken()
            .addOnCompleteListener { task ->
                if (task.isSuccessful) {
                    val token = task.result
                    Log.d("FCM", "Token: $token")
                }
            }
    }
}

روش منسوخ FirebaseInstanceId

در نسخه‌های قدیمی Firebase SDK (قبل از نسخه 20.x) توکن از طریق FirebaseInstanceId.getInstance().getToken() دریافت می‌شد. این روش به عنوان deprecated علامت‌گذاری شده است و در پروژه‌های جدید توصیه نمی‌شود. توسعه‌دهندگانی که کد لگاسی را حفظ می‌کنند باید به FirebaseInstallations API مهاجرت کنند.

دریافت Registration Token در iOS

در iOS فرآیند دریافت Registration Token از نظر معماری متفاوت است — FCM از طریق Apple Push Notification service (APNs) کار می‌کند. Firebase SDK از APNs یک device token منحصربه‌فرد دریافت کرده، آن را به فرمت FCM تبدیل کرده و به برنامه ارسال می‌کند.

تنظیم APNs و دریافت توکن

برای عملکرد FCM در iOS، باید گواهینامه APNs یا کلید را در کنسول Firebase تنظیم کنید. برنامه باید از طریق UNUserNotificationCenter اجازه اعلان را درخواست کند. پس از دریافت توکن APNs، Firebase SDK به‌طور خودکار Registration Token را تولید می‌کند.

import FirebaseMessaging
import UserNotifications

class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(
        application: UIApplication,
        didFinishLaunchingWithOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        FirebaseApp.configure()
        Messaging.messaging().delegate = self
        requestNotificationAuthorization()
        return true
    }

    private func requestNotificationAuthorization() {
        let center = UNUserNotificationCenter.current()
        center.requestAuthorization(options: [.alert, .sound, .badge])
    }
}

extension AppDelegate: MessagingDelegate {
    func messaging(
        messaging: Messaging,
        didReceiveRegistrationToken fcmToken: String?
    ) {
        Log.d("FCM", "Token: \(fcmToken ?? "")")
        sendTokenToServer(token: fcmToken)
    }
}

تفاوت‌های توکن iOS و Android

Registration Token در iOS در مقایسه با توکن Android اندازه کوچک‌تری دارد، زیرا بر اساس APNs device token است. Firebase SDK به‌طور خودکار توکن FCM را هنگام تغییر توکن APNs به‌روز می‌کند، که این امر هنگام بازیابی دستگاه از پشتیبان گیری یا نصب مجدد برنامه اتفاق می‌افتد.

به‌روزرسانی و مدیریت Registration Token

مدیریت چرخه عمر Registration Token یک وظیفه حیاتی برای تحویل پایدار اعلان‌های push است. اگر بخش سرور توکن قدیمی را ذخیره کند، اعلان‌ها تحویل نخواهند شد و Firebase خطای UNREGISTERED را برمی‌گرداند.

نظارت بر تغییرات توکن

Firebase SDK دو مکانیزم برای رصد تغییرات توکن ارائه می‌دهد. در Android از callback onNewToken در FirebaseMessagingService استفاده می‌شود. در iOS — دلگات messaging:didReceiveRegistrationToken. هر دو در هر به‌روزرسانی توکن فراخوانی می‌شوند.

// ذخیره توکن در SharedPreferences و ارسال به سرور
class TokenManager(private val context: Context) {

    companion object {
        private const val PREFS_TOKEN_KEY = "fcm_registration_token"
    }

    fun saveToken(token: String) {
        val prefs = PreferenceManager
            .getDefaultSharedPreferences(context)
        prefs.edit().putString(PREFS_TOKEN_KEY, token).apply()
    }

    fun getSavedToken(): String? {
        val prefs = PreferenceManager
            .getDefaultSharedPreferences(context)
        return prefs.getString(PREFS_TOKEN_KEY, null)
    }
}

راهبرد ذخیره توکن‌ها در سرور

بخش سرور باید Registration Token را همراه با شناسه کاربر ذخیره کند. هنگام به‌روزرسانی توکن، مشترک توکن جدید را به سرور ارسال می‌کند و سرور توکن قدیمی را جایگزین می‌کند. توصیه می‌شود تاریخچه توکن‌ها را نگه داشته باشید: اگر اعلانی به توکن جدید تحویل نشد، می‌توان از توکن قدیمی استفاده کرد.

مدیریت خطاها هنگام کار با توکن

Firebase می‌تواند در چند مورد خطای دریافت توکن را برگرداند. عدم وجود Google Play Services روی دستگاه — توکن دریافت نخواهد شد. تجاوز محدودیت درخواست‌های FCM — باید در تلاش‌های مجدد از تأخیر نمایی استفاده کرد. منقضی شدن مدت اعتبار توکن — SDK به‌طور خودکار توکن جدیدی درخواست می‌کند.