Registration Token في إشعارات الدفع: ما هو، طرق الحصول عليه وتحديثه

ما هو Registration Token

Registration Token هو سلسلة فريدة يصل طولها إلى 4096 حرفًا يعيّنها Firebase Cloud Messaging لكل مثيل تطبيق. يتم تشكيل الرمز بناءً على معرف التطبيق ومعرف الجهاز وحساب Google على الجهاز.

هيكل الرمز والغرض منه

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

الاختلافات عن المعرفات الأخرى

لا ينبغي الخلط بين 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، ينشئ الجهاز اتصالاً مستمراً بخوادم Firebase عبر بروتوكول STOMP على أندرويد أو قناة APNs على iOS. عندما يرسل الخادم إشعارًا إلى الرمز، يجد FCM الجهاز بواسطة الرمز ويوصل الحمولة.

ظروف إعادة إنشاء الرمز

قد يتم إعادة إنشاء Registration Token بواسطة FCM في الحالات التالية. عند استعادة تطبيق من نسخة احتياطية على جهاز جديد. عند حذف التطبيق وإعادة تثبيته. عند مسح بيانات التطبيق عبر إعدادات النظام. عند تسجيل الدخول إلى حساب Google مختلف على الجهاز. توصي Firebase دائمًا بمعالجة رد الاتصال onNewToken لتتبع التغييرات.

الحصول على Registration Token في أندرويد

على أندرويد، يتم الحصول على Registration Token من خلال Firebase Messaging SDK. تختلف العملية حسب إصدار SDK — الإصدارات الأحدث تستخدم FirebaseInstallations API بدلاً من FirebaseInstanceId القديم.

الطريقة الحديثة عبر 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(). هذه الطريقة مُوسومة بأنها مهملة ولا يُنصح باستخدامها في المشاريع الجديدة. يجب على المطورين الذين يحافظون على كود قديم الترحيل إلى FirebaseInstallations API.

الحصول على Registration Token في iOS

على iOS، تختلف عملية الحصول على Registration Token من الناحية المعمارية — يعمل FCM من خلال Apple Push Notification service (APNs). يتلقى Firebase SDK رمز جهاز فريدًا من APNs، ويحوله إلى تنسيق 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 وأندرويد

حجم Registration Token على iOS أصغر مقارنة برمز أندرويد، لأنه يعتمد على رمز جهاز APNs. يقوم Firebase SDK بتحديث رمز FCM تلقائيًا عند تغيير رمز APNs، وهو ما يحدث عند استعادة جهاز من نسخة احتياطية أو إعادة تثبيت التطبيق.

تحديث وإدارة Registration Token

إدارة دورة حياة Registration Token هي مهمة بالغة الأهمية لتوصيل إشعارات الدفع بشكل موثوق. إذا كان الخادم يخزن رمزًا قديمًا، فلن يتم تسليم الإشعارات، وسيعيد Firebase خطأ UNREGISTERED.

مراقبة تغييرات الرمز

يوفر Firebase SDK آليتين لتتبع تغييرات الرمز. على أندرويد، يتم استخدام رد الاتصال 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)
    }
}

استراتيجية تخزين الرموز على الخادم

يجب على الخادم تخزين RegistrationToken مرتبطًا بـ معرف المستخدم. عند تحديث الرمز، يرسل العميل الرمز الجديد إلى الخادم، ويستبدل الخادم القديم. يُوصى بالاحتفاظ بسجل للرموز: إذا لم يتم تسليم إشعار إلى الرمز الجديد، يمكن تجربة القديم.

معالجة الأخطاء عند العمل مع الرمز

قد يعيد Firebase خطأ في الحصول على الرمز في عدة حالات. عدم وجود Google Play Services على الجهاز — لن يتم الحصول على الرمز. تجاوز حصة طلبات FCM — من الضروري تنفيذ تأخير أسي عند إعادة المحاولة. انتهاء صلاحية الرمز — يطلب SDK تلقائيًا رمزًا جديدًا.