تلقّي الرسائل باستخدام "المراسلة عبر السحابة الإلكترونية من Firebase"

يوضّح هذا الدليل كيفية إعداد Firebase Cloud Messaging في تطبيقات العميل على الأجهزة الجوّالة والويب حتى تتمكّن من تلقّي الرسائل بشكل موثوق.

لتلقّي الرسائل، استخدِم خدمة تتضمّن FirebaseMessagingService. يجب أن تتجاهل خدمتك عمليات الاسترجاع onMessageReceived وonDeletedMessages.

يتم توفير onMessageReceived لمعظم أنواع الرسائل، باستثناء ما يلي:

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

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

وباختصار:

لمزيد من المعلومات حول أنواع الرسائل، راجِع الإشعارات ورسائل البيانات.

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

إذا كنت تتوقّع أن يستغرق تطبيقك حوالي 10 ثوانٍ لمعالجة رسالة، عليك جدولة مهمة WorkManager أو اتّباع إرشادات WakeLock الواردة أدناه. في بعض الحالات، قد تكون الفترة الزمنية المتاحة لمعالجة الرسالة أقل من 10 ثوانٍ، وذلك حسب التأخيرات التي تحدث قبل طلب onMessageReceived، بما في ذلك تأخيرات نظام التشغيل أو وقت بدء تشغيل التطبيق أو حظر سلسلة التعليمات الرئيسية بسبب عمليات أخرى أو استغراق طلبات onMessageReceived السابقة وقتًا طويلاً. وبعد انتهاء صلاحية هذا الموقّت، قد يخضع تطبيقك لإيقاف العملية أو لقيود على التنفيذ في الخلفية. يُرجى العِلم أنّ حالات التأخير في عمليات الشبكة وبدء تشغيل التطبيق يمكن أن تكون كبيرة، لذا، عند الشك، خطِّط لتنفيذ معالجة الرسائل لفترة طويلة إذا كانت هناك أي تبعيات غير متزامنة، مثل متطلبات الوصول إلى الشبكة أو تحميل البيانات المكثّف.

تعديل ملف بيان التطبيق

لاستخدام FirebaseMessagingService، عليك إضافة ما يلي إلى بيان التطبيق:

<service
    android:name=".java.MyFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>
AndroidManifest.xml

يُنصح أيضًا بضبط القيم التلقائية لتخصيص مظهر الإشعارات. يمكنك تحديد رمز تلقائي مخصّص ولون تلقائي مخصّص يتم تطبيقهما عندما لا يتم ضبط القيم المكافئة في حمولة الإشعار.

أضِف الأسطر التالية داخل العلامة application لضبط الرمز التلقائي المخصّص واللون المخصّص:

<!-- Set custom default icon. This is used when no icon is set for incoming notification messages.
     See README(https://goo.gl/l4GJaQ) for more. -->
<meta-data
    android:name="com.google.firebase.messaging.default_notification_icon"
    android:resource="@drawable/ic_stat_ic_notification" />
<!-- Set color used with incoming notification messages. This is used when no color is set for the incoming
     notification message. See README(https://goo.gl/6BKBk7) for more. -->
<meta-data
    android:name="com.google.firebase.messaging.default_notification_color"
    android:resource="@color/colorAccent" />
AndroidManifest.xml

يعرض نظام التشغيل Android الرمز التلقائي المخصّص ويستخدمه في

• جميع رسائل الإشعارات المرسَلة من أداة إنشاء الإشعارات
• أي رسالة إشعار لا تحدّد الرمز بشكل صريح في حمولة الإشعار

إذا لم يتم ضبط أي رمز تلقائي مخصّص ولم يتم ضبط أي رمز في حمولة الإشعار، يعرض نظام التشغيل Android رمز التطبيق باللون الأبيض.

تجاهل onMessageReceived

من خلال إلغاء طريقة FirebaseMessagingService.onMessageReceived، يمكنك تنفيذ إجراءات استنادًا إلى عنصر RemoteMessage الذي تم تلقّيه والحصول على بيانات الرسالة:

override fun onMessageReceived(remoteMessage: RemoteMessage) {
    // TODO(developer): Handle FCM messages here.
    // Not getting messages here? See why this may be: https://goo.gl/39bRNJ
    Log.d(TAG, "From: ${remoteMessage.from}")

    // Check if message contains a data payload.
    if (remoteMessage.data.isNotEmpty()) {
        Log.d(TAG, "Message data payload: ${remoteMessage.data}")

        // Check if data needs to be processed by long running job
        if (needsToBeScheduled()) {
            // For long-running tasks (10 seconds or more) use WorkManager.
            scheduleJob()
        } else {
            // Handle message within 10 seconds
            handleNow()
        }
    }

    // Check if message contains a notification payload.
    remoteMessage.notification?.let {
        Log.d(TAG, "Message Notification Body: ${it.body}")
    }

    // Also if you intend on generating your own notifications as a result of a received FCM
    // message, here is where that should be initiated. See sendNotification method below.
}
MyFirebaseMessagingService.kt

@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
    // TODO(developer): Handle FCM messages here.
    // Not getting messages here? See why this may be: https://goo.gl/39bRNJ
    Log.d(TAG, "From: " + remoteMessage.getFrom());

    // Check if message contains a data payload.
    if (remoteMessage.getData().size() > 0) {
        Log.d(TAG, "Message data payload: " + remoteMessage.getData());

        if (/* Check if data needs to be processed by long running job */ true) {
            // For long-running tasks (10 seconds or more) use WorkManager.
            scheduleJob();
        } else {
            // Handle message within 10 seconds
            handleNow();
        }

    }

    // Check if message contains a notification payload.
    if (remoteMessage.getNotification() != null) {
        Log.d(TAG, "Message Notification Body: " + remoteMessage.getNotification().getBody());
    }

    // Also if you intend on generating your own notifications as a result of a received FCM
    // message, here is where that should be initiated. See sendNotification method below.
}
MyFirebaseMessagingService.java

إبقاء الجهاز مشغَّلاً أثناء معالجة رسائل FCM

إذا كان تطبيقك بحاجة إلى إبقاء الجهاز نشطًا أثناء معالجة رسالة من "المراسلة عبر السحابة الإلكترونية من Firebase"، يجب أن يحتفظ التطبيق بعملية WakeLock خلال هذه الفترة أو أن ينشئ مهمة WorkManager. تعمل WakeLocks بشكل جيد مع أنشطة المعالجة القصيرة التي قد تتجاوز onMessageReceived المهلات التلقائية. بالنسبة إلى مهام سير العمل الموسّعة، مثل إرسال عدة طلبات RPC متسلسلة إلى الخوادم، يكون استخدام مهمة WorkManager أكثر ملاءمة من استخدام WakeLock. في هذا القسم، نركّز على كيفية استخدام WakeLocks. يمنع WakeLock الجهاز من الانتقال إلى وضع السكون أثناء تشغيل تطبيقك، ما قد يؤدي إلى زيادة استهلاك البطارية، لذا يجب حجز استخدام WakeLocks للحالات التي يجب ألا يتم فيها إيقاف تطبيقك مؤقتًا أثناء معالجة الرسالة، مثل:

• إشعارات للمستخدم تكون حساسة للوقت
• التفاعلات مع شيء خارج الجهاز لا يجب أن يتم مقاطعتها (مثل عمليات نقل البيانات على الشبكة أو عمليات التواصل مع جهاز آخر، مثل ساعة مقترنة)

عليك أولاً التأكّد من أنّ تطبيقك يطلب إذن WakeLock (تتضمّن حزمة تطوير البرامج (SDK) لخدمة FCM هذا الإذن تلقائيًا، لذا لا يلزم عادةً إضافة أي شيء).

<uses-permission android:name="android.permission.WAKE_LOCK" />

بعد ذلك، سيحتاج تطبيقك إلى الحصول على WakeLock في بداية معاودة الاتصال FirebaseMessagingService.onMessageReceived() وإلغاء قفله في نهاية معاودة الاتصال.

FirebaseMessagingService المخصّص للتطبيق:

@Override
public void onMessageReceived(final RemoteMessage message) {
  // If this is a message that is time sensitive or shouldn't be interrupted
  WakeLock wakeLock = getSystemService(PowerManager.class).newWakeLock(PARTIAL_WAKE_LOCK, "myApp:messageReceived");
  try {
    wakeLock.acquire(TIMEOUT_MS);
    // handle message
    ...
  finally {
    wakeLock.release();
  }
}

تجاهل onDeletedMessages

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

التعامل مع رسائل الإشعارات في تطبيق يعمل في الخلفية

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

ويشمل ذلك الرسائل التي تحتوي على كل من الإشعار وحمولة البيانات (وجميع الرسائل المُرسَلة من وحدة تحكّم الإشعارات). في هذه الحالات، يتم تسليم الإشعار إلى علبة النظام في الجهاز، ويتم تسليم حمولة البيانات في الإضافات الخاصة بنية النشاط الخاص بمشغّل التطبيق.

للحصول على إحصاءات حول عملية تسليم الرسائل إلى تطبيقك، اطّلِع على FCM لوحة بيانات التقارير التي تسجّل عدد الرسائل المرسَلة والمفتوحة على أجهزة Apple وAndroid، بالإضافة إلى بيانات "مرات الظهور" (الإشعارات التي يراها المستخدمون) لتطبيقات Android.