تلقّي الرسائل في تطبيقات Android

اختيار المنصة:

iOS+ Android الويب Flutter Unity C++‎

ملاحظة: يُرجى نقل طلباتك من جهة خادم Android إلى AndroidConfigV2 لتسليم الإشعارات التي تظهر للمستخدمين في الوقت المناسب. للحصول على إرشادات، يُرجى الاطّلاع على مقالة نقل البيانات من AndroidConfig إلى AndroidConfigV2.

لتلقّي الرسائل، يمكنك استخدام خدمة تتيح استخدام FirebaseMessagingService. إذا كنت تنقل البيانات إلى AndroidConfigV2، عليك تنفيذ عمليات الاستدعاء المتخصصة onNotificationReceived وonBackgroundSyncReceived كما هو موضّح في تعديل عمليات استدعاء عميل Android. بالنسبة إلى رسائل AndroidConfig (الإصدار 1) القديمة، يجب أن تلغي خدمتك عمليات معاودة الاتصال onMessageReceived وonDeletedMessages. للاطّلاع على مثال كامل، يُرجى مراجعة نموذج البدء السريع لخدمة "مراسلة Firebase السحابية".

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

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

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

وباختصار:

حالة التطبيق	إشعار	البيانات	كلاهما
لون الواجهة	onMessageReceived	onMessageReceived	onMessageReceived
الخلفية	علبة النظام	onMessageReceived	الإشعار: علبة النظام البيانات: في الإضافات الخاصة بالintent.

ملاحظة: ينطبق تقسيم التوجيه في المقدّمة مقابل الخلفية في الجدول السابق على رسائل AndroidConfig (الإصدار 1) القديمة فقط. في AndroidConfigV2، يجب أن تستخدم التطبيقات RemoteNotification لجميع الرسائل التي تعرض إشعارًا مرئيًا للمستخدم ليتم تسليمها بدون تأخير مقصود، ويتم عرض الإشعارات تلقائيًا في كل من حالتي المقدّمة والخلفية ما لم يتم كتم صوتها صراحةً في onNotificationReceived.

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

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

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

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

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

لاستخدام 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 الرمز التلقائي المخصّص ويستخدمه

• جميع رسائل الإشعارات المُرسَلة من منشئ الإشعارات في وحدة تحكّم Firebase

• أي رسالة إشعار لا تضبط الرمز بشكل صريح في حمولة الإشعار.

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

تجاوز onMessageReceived

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

Kotlin

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

Java

@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

تجاوز onDeletedMessages

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

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

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

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

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