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

تختلف طريقة عمل إشعارات Firebase حسب حالة التطبيق المستلِم في المقدّمة/الخلفية. إذا كنت تريد أن تتلقّى التطبيقات التي تعمل في المقدّمة رسائل إشعارات أو رسائل بيانات، عليك كتابة رمز لمعالجة مكالمة onMessageReceived. للحصول على تفسير للفرق بين إشعارات البيانات والرسائل، يُرجى الاطّلاع على أنواع الرسائل.

معالجة الرسائل

لتلقّي الرسائل، استخدِم خدمة توفّر FirebaseMessagingService. يجب أن تلغي خدمتك onMessageReceived وonDeletedMessages طلبات إعادة الاتصال.

يجب أن تعالج خدمتك أي رسالة في غضون 20 ثانية من استلامها.

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

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

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

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

وباختصار:

حالة التطبيق	إشعار	البيانات	كلاهما
لون الواجهة	onMessageReceived	onMessageReceived	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 اللون التلقائي المخصّص في ما يلي:

• جميع رسائل الإشعارات المُرسَلة من أداة إنشاء الإشعارات
• أي رسالة إشعار لا تضبط اللون صراحةً في الحمولة الإشعار

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

إلغاء onMessageReceived

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

Kotlin+KTX

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 رسائل الإشعارات إلى لوحة النظام. يؤدي نقر المستخدم على الإشعار إلى فتح مشغّل التطبيقات تلقائيًا.

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

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

تلقّي رسائل "المراسلة عبر السحابة الإلكترونية من Firebase" في وضع التشغيل المباشر

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

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

المتطلبات الأساسية

• يجب إعداد الجهاز للتشغيل المباشر.
• يجب تثبيت أحدث إصدار من "خدمات Google Play" على الجهاز (19.0.54 أو إصدار أحدث).
• يجب أن يستخدم التطبيق حزمة تطوير البرامج (SDK) لنظام المراسلة عبر السحابة الإلكترونية من Firebase (com.google.firebase:firebase-messaging) لتلقّي رسائل هذا النظام.

تفعيل معالجة الرسائل في وضع التشغيل المباشر في تطبيقك

1. في ملف Gradle على مستوى التطبيق، أضِف تبعية على مكتبة دعم التشغيل المباشر من خدمة "إشعارات من Google‏ (FCM)":

   implementation 'com.google.firebase:firebase-messaging-directboot:20.2.0'
   

2. يمكنك إعلام FirebaseMessagingService بالتشغيل المباشر للتطبيق من خلال إضافة سمة android:directBootAware="true" في بيان التطبيق:

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

من المهم التأكّد من أنّه يمكن تشغيل هذا FirebaseMessagingService في وضع التشغيل المباشر. يُرجى التحقّق مما يلي:

• يجب ألا تصل الخدمة إلى مساحة التخزين المحمية ببيانات الاعتماد أثناء تشغيلها في وضع التشغيل المباشر.
• يجب ألا تحاول الخدمة استخدام مكوّنات، مثل Activities أو BroadcastReceivers أو أو Services أخرى غير مصنّفة على أنّها متوافق مع ميزة "التشغيل المباشر" أثناء التشغيل في وضع "التشغيل المباشر".
• يجب أيضًا ألا تصل أي مكتبات تستخدمها الخدمة إلى مساحة التخزين المحمية ببيانات الاعتماد، ولا تستدعي المكوّنات غير المتوافقة مع وضع التشغيل المباشر أثناء التشغيل في وضع التشغيل المباشر. وهذا يعني أنّ أي مكتبات يستخدمها التطبيق ويتم استدعاؤها من الخدمة يجب أن تكون على دراية بالتشغيل المباشر، أو يجب أن يتحقّق التطبيق ممّا إذا كان يعمل في وضع التشغيل المباشر وألا يستدعيها في هذا الوضع. على سبيل المثال، تعمل حِزم تطوير البرامج (SDK) لمنصّة Firebase مع وضع التشغيل المباشر (يمكن تضمينها في تطبيق بدون تعطُّله في وضع التشغيل المباشر)، ولكن لا تتيح العديد من واجهات برمجة التطبيقات في Firebase إمكانية الاتصال بها في وضع التشغيل المباشر.
• إذا كان التطبيق يستخدم Application مخصّصًا، يجب أن يكون Application على دراية بالتشغيل المباشر (لا يمكن الوصول إلى مساحة التخزين المحمية ببيانات الاعتماد في وضع التشغيل المباشر).

للحصول على إرشادات حول إرسال الرسائل إلى الأجهزة في وضع التشغيل المباشر، اطّلِع على مقالة إرسال الرسائل المفعَّلة لميزة "التشغيل المباشر".