أفضل الممارسات لإدارة الرمز المميز لتسجيل FCM

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

رموز التسجيل القديمة والمنتهية الصلاحية

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

هناك عدة أسباب تجعل الرمز المميز قديمًا. على سبيل المثال، قد يتم فقدان الجهاز المرتبط بالرمز المميز أو تدميره أو تخزينه ونسيانه.

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

أفضل الممارسات الأساسية

هناك بعض الممارسات الأساسية التي يجب عليك اتباعها في أي تطبيق يستخدم واجهات برمجة التطبيقات FCM لإنشاء طلبات الإرسال برمجيًا. أفضل الممارسات الرئيسية هي:

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

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

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

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

ومن المهم أيضًا حفظ الرمز المميز على الخادم وتحديث الطابع الزمني كلما تغير، مثل عندما:

  • تتم استعادة التطبيق على جهاز جديد
  • يقوم المستخدم بإلغاء تثبيت التطبيق أو إعادة تثبيته
  • يقوم المستخدم بمسح بيانات التطبيق
  • يصبح التطبيق نشطًا مرة أخرى بعد انتهاء صلاحية FCM لرمزه المميز الحالي

مثال: تخزين الرموز والطوابع الزمنية في Cloud Firestore

على سبيل المثال، يمكنك استخدام Cloud Firestore لتخزين الرموز المميزة في مجموعة تسمى fcmTokens . يتوافق كل معرف مستند في المجموعة مع معرف المستخدم، ويقوم المستند بتخزين رمز التسجيل الحالي والطابع الزمني الأخير الذي تم تحديثه. استخدم الدالة set كما هو موضح في مثال Kotlin هذا:

    /**
     * Persist token to third-party servers.
     *
     * Modify this method to associate the user's FCM registration token with any server-side account
     * maintained by your application.
     *
     * @param token The new token.
     */
    private fun sendTokenToServer(token: String?) {
        // If you're running your own server, call API to send token and today's date for the user

        // Example shown below with Firestore
        // Add token and timestamp to Firestore for this user
        val deviceToken = hashMapOf(
            "token" to token,
            "timestamp" to FieldValue.serverTimestamp(),
        )
        // Get user ID from Firebase Auth or your own server
        Firebase.firestore.collection("fcmTokens").document("myuserid")
            .set(deviceToken)
    }

كلما تم استرداد رمز مميز، يتم تخزينه في Cloud Firestore عن طريق استدعاء sendTokenToServer :

    /**
     * Called if the FCM registration token is updated. This may occur if the security of
     * the previous token had been compromised. Note that this is called when the
     * FCM registration token is initially generated so this is where you would retrieve the token.
     */
    override fun onNewToken(token: String) {
        Log.d(TAG, "Refreshed token: $token")

        // If you want to send messages to this application instance or
        // manage this apps subscriptions on the server side, send the
        // FCM registration token to your app server.
        sendTokenToServer(token)
    }
        var token = Firebase.messaging.token.await()

        // Check whether the retrieved token matches the one on your server for this user's device
        val preferences = this.getPreferences(Context.MODE_PRIVATE)
        val tokenStored = preferences.getString("deviceToken", "")
        lifecycleScope.launch {
            if (tokenStored == "" || tokenStored != token)
            {
                // If you have your own server, call API to send the above token and Date() for this user's device

                // Example shown below with Firestore
                // Add token and timestamp to Firestore for this user
                val deviceToken = hashMapOf(
                    "token" to token,
                    "timestamp" to FieldValue.serverTimestamp(),
                )

                // Get user ID from Firebase Auth or your own server
                Firebase.firestore.collection("fcmTokens").document("myuserid")
                    .set(deviceToken).await()
            }
        }

الحفاظ على نضارة الرمز المميز وإزالة الرموز القديمة

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

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

اكتشف استجابات الرمز المميز غير الصالحة من الواجهة الخلفية لـ FCM

تأكد من اكتشاف استجابات الرموز المميزة غير الصالحة من FCM والرد عن طريق حذف أي رموز تسجيل مميزة من نظامك معروفة بأنها غير صالحة أو منتهية الصلاحية. باستخدام HTTP v1 API، قد تشير رسائل الخطأ هذه إلى أن طلب الإرسال الخاص بك يستهدف رموزًا مميزة غير صالحة أو منتهية الصلاحية:

  • UNREGISTERED (HTTP 404)
  • INVALID_ARGUMENT (HTTP 400)

إذا كنت متأكدًا من أن حمولة الرسالة صالحة وتلقيت أيًا من هذه الاستجابات لرمز مميز مستهدف، فمن الآمن حذف السجل الخاص بك لهذا الرمز المميز، لأنه لن يكون صالحًا مرة أخرى أبدًا. على سبيل المثال، لحذف الرموز المميزة غير الصالحة من Cloud Firestore، يمكنك نشر وتشغيل وظيفة مثل ما يلي:

    // Registration token comes from the client FCM SDKs
    const registrationToken = 'YOUR_REGISTRATION_TOKEN';

    const message = {
    data: {
        // Information you want to send inside of notification
    },
    token: registrationToken
    };

    // Send message to device with provided registration token
    getMessaging().send(message)
    .then((response) => {
        // Response is a message ID string.
    })
    .catch((error) => {
        // Delete token for user if error code is UNREGISTERED or INVALID_ARGUMENT.
        if (errorCode == "messaging/registration-token-not-registered") {
            // If you're running your own server, call API to delete the
            token for the user

            // Example shown below with Firestore
            // Get user ID from Firebase Auth or your own server
            Firebase.firestore.collection("fcmTokens").document(user.uid).delete()
        }
    });

لن تقوم FCM بإرجاع استجابة رمزية غير صالحة إلا إذا انتهت صلاحية الرمز المميز بعد 270 يومًا أو إذا كان العميل غير مسجل بشكل صريح. إذا كنت بحاجة إلى تتبع حالة عدم الصلاحية بشكل أكثر دقة وفقًا لتعريفاتك الخاصة، فيمكنك إزالة الرموز المميزة للتسجيل التي لا معنى لها بشكل استباقي.

تحديث الرموز على أساس منتظم

نوصي باسترداد وتحديث جميع رموز التسجيل المميزة على الخادم الخاص بك بشكل دوري. وهذا يتطلب منك:

  • أضف منطق التطبيق في تطبيق العميل الخاص بك لاسترداد الرمز المميز الحالي باستخدام استدعاء API المناسب (مثل token(completion): لمنصات Apple أو getToken() لنظام Android) ثم أرسل الرمز المميز الحالي إلى خادم التطبيق الخاص بك للتخزين (مع الطابع الزمني). يمكن أن تكون هذه مهمة شهرية تم تكوينها لتغطية جميع العملاء أو الرموز المميزة.
  • أضف منطق الخادم لتحديث الطابع الزمني للرمز المميز على فترات زمنية منتظمة، بغض النظر عما إذا كان الرمز المميز قد تغير أم لا.

للحصول على مثال لمنطق Android لتحديث الرموز المميزة باستخدام WorkManager ، راجع إدارة رموز المراسلة السحابية على مدونة Firebase.

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

إزالة الرموز المميزة للتسجيل التي لا معنى لها

قبل إرسال الرسائل إلى أحد الأجهزة، تأكد من أن الطابع الزمني لرمز تسجيل الجهاز يقع ضمن فترة صلاحية الجهاز. على سبيل المثال، يمكنك تنفيذ Cloud Functions for Firebase لإجراء فحص يومي للتأكد من أن الطابع الزمني يقع ضمن فترة زمنية محددة مثل const EXPIRATION_TIME = 1000 * 60 * 60 * 24 * 30; ثم قم بإزالة الرموز القديمة:

exports.pruneTokens = functions.pubsub.schedule('every 24 hours').onRun(async (context) => {
  // Get all documents where the timestamp exceeds is not within the past month
  const staleTokensResult = await admin.firestore().collection('fcmTokens')
      .where("timestamp", "<", Date.now() - EXPIRATION_TIME)
      .get();
  // Delete devices with stale tokens
  staleTokensResult.forEach(function(doc) { doc.ref.delete(); });
});

إلغاء الاشتراك في الرموز القديمة من المواضيع

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

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

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

قياس نجاح التسليم

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

قبل توجيه الرسائل إلى رمز مميز، ضع في اعتبارك ما يلي:

  • هل يشير Google Analytics أو البيانات التي تم التقاطها في BigQuery أو إشارات التتبع الأخرى إلى أن الرمز المميز نشط؟
  • هل فشلت محاولات التسليم السابقة باستمرار على مدى فترة من الزمن؟
  • هل تم تحديث رمز التسجيل على خوادمك في الشهر الماضي؟
  • بالنسبة لأجهزة Android، هل تبلغ FCM Data API عن نسبة عالية من حالات فشل تسليم الرسائل بسبب droppedDeviceInactive ؟

لمزيد من المعلومات حول التسليم، راجع فهم تسليم الرسائل .