Save the date - Google I/O returns May 18-20. Register to get the most out of the digital experience: Build your schedule, reserve space, participate in Q&As, earn Google Developer profile badges, and more. Register now
ترجمت واجهة Cloud Translation API‏ هذه الصفحة.
Switch to English

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

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

التعامل مع الرسائل

لتلقي الرسائل ، استخدم خدمة توسع FirebaseMessagingService . يجب أن تتجاوز onMessageReceived onDeletedMessages رد onDeletedMessages و onDeletedMessages . يجب أن يتعامل مع أي رسالة خلال 20 ثانية من استلامها (10 ثوانٍ على Android Marshmallow). قد تكون النافذة الزمنية أقصر بناءً على تأخيرات نظام التشغيل المتكبدة قبل استدعاء onMessageReceived . بعد ذلك الوقت ، قد تتداخل سلوكيات نظام التشغيل المختلفة مثل حدود تنفيذ خلفية 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>

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

أضف هذه الخطوط داخل علامة 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" />

يعرض Android الرمز الافتراضي المخصص لـ

  • جميع رسائل الإشعارات المرسلة من مؤلف الإخطارات .
  • أي رسالة إعلام لا تحدد بشكل صريح الرمز في حمولة الإعلام.

يستخدم Android اللون الافتراضي المخصص لـ

  • جميع رسائل الإشعارات المرسلة من مؤلف الإخطارات .
  • أي رسالة إعلام لا تحدد اللون بشكل صريح في حمولة الإشعارات.

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

تجاوز onMessageReceived

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

جافا

01 fefeaa20

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}")

        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.
    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.
}

تجاوز onDeletedMessages

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

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

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

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

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

التطبيقات المقيدة في الخلفية (Android P أو الأحدث)

قد لا ترسل FCM رسائل إلى التطبيقات التي تم تقييدها في الخلفية من قبل المستخدم (مثل عبر: الإعداد -> التطبيقات والإشعارات -> [اسم التطبيق] -> البطارية). بمجرد إزالة تطبيقك من قيود الخلفية ، سيتم تسليم الرسائل الجديدة إلى التطبيق كما كان من قبل. من أجل منع الرسائل المفقودة والتأثيرات الأخرى لتقييد الخلفية ، تأكد من تجنب السلوكيات السيئة المدرجة في جهود مؤشرات Android الحيوية . قد تؤدي هذه السلوكيات إلى أن يوصي جهاز Android المستخدم بتقييد تطبيقك في الخلفية. يمكن لتطبيقك التحقق مما إذا كان مقيّدًا في الخلفية باستخدام: isBackgroundRestricted () .

تلقي رسائل FCM في وضع التمهيد المباشر

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

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

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

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

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

  1. في ملف Gradle على مستوى التطبيق ، أضف تبعية إلى مكتبة دعم التمهيد المباشر 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 الأخرى التي لم يتم وضع علامة عليها كتمهيد مباشر على علم أثناء التشغيل في وضع التمهيد المباشر.
  • يجب أيضًا ألا تصل أي مكتبات تستخدمها الخدمة إلى وحدة تخزين بيانات الاعتماد المحمية ولا تستدعي مكونات غير DirectBootAware أثناء التشغيل في وضع التمهيد المباشر. هذا يعني أن أي مكتبات يستخدمها التطبيق والتي يتم استدعاؤها من الخدمة إما أن تكون على دراية بالتمهيد المباشر ، أو سيحتاج التطبيق إلى التحقق مما إذا كان يعمل في وضع التمهيد المباشر وعدم الاتصال بها في هذا الوضع. على سبيل المثال ، تعمل حزم Firebase SDK مع التمهيد المباشر (يمكن تضمينها في أحد التطبيقات دون تعطله في وضع التمهيد المباشر) ، ولكن العديد من واجهات برمجة تطبيقات Firebase لا تدعم الاستدعاء في وضع التمهيد المباشر.
  • إذا كان التطبيق يستخدم عادة Application ، و Application سوف تحتاج أيضا إلى أن يكون التمهيد المباشر علم (أي الوصول إلى التخزين المحمي الاعتماد في وضع التشغيل المباشر).

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