Advanced Android in Kotlin 01.2: Android Firebase Cloud Messaging

هذا الدرس العملي حول الترميز هو جزء من دورة "تطبيقات متقدّمة متوافقة مع نظام Android باستخدام لغة Kotlin". ستستفيد إلى أقصى حدّ من هذه الدورة التدريبية إذا تابعت دروس الترميز بالتسلسل، ولكن هذا ليس إلزاميًا. يمكنك الاطّلاع على جميع دورات الترميز في الدورة التدريبية على الصفحة المقصودة لدورات الترميز في "تطبيقات متقدمة متوافقة مع نظام Android باستخدام لغة Kotlin".

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

تتضمّن هذه السلسلة من الجلسات العملية ما يلي:

• 1.1 استخدام إشعارات Android
• ‫1.2 خدمة المراسلة عبر السحابة الإلكترونية من Firebase على Android

مقدمة

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

ما هو الإشعار الفوري؟

الإشعارات الفورية هي إشعارات "يرسلها" الخادم إلى الأجهزة الجوّالة. ويمكن إرسالها إلى جهاز بغض النظر عمّا إذا كان تطبيقك قيد التشغيل أم لا.

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

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

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

ما هي خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"؟

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

يمكنك أيضًا استخدام "الرسائل عبر السحابة الإلكترونية من Firebase" لنقل البيانات من تطبيق الخلفية أو من مشروع Firebase إلى المستخدمين.

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية استخدام خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" لإرسال إشعارات فورية لتطبيق Android، بالإضافة إلى إرسال البيانات.

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

ما يجب معرفته

يجب أن تكون على دراية بما يلي:

• كيفية إنشاء تطبيقات Android باستخدام لغة Kotlin على وجه الخصوص، يمكنك استخدام حزمة تطوير البرامج (SDK) لنظام التشغيل Android.
• كيفية تصميم تطبيقك باستخدام مكوّنات البنية وربط البيانات
• فهم أساسي لمستقبِلات البث
• فهم أساسي لفئة AlarmManager
• كيفية إنشاء الإشعارات وإرسالها باستخدام NotificationManager

أهداف الدورة التعليمية

• كيفية إرسال رسائل إلى المستخدم من خلال خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"
• كيفية إرسال البيانات من الخلفية إلى تطبيقك باستخدام رسائل البيانات، وهي جزء من خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"

الإجراءات التي ستنفذّها

• أضِف إشعارات فورية إلى التطبيق الأوّلي.
• التعامل مع "المراسلة عبر السحابة الإلكترونية من Firebase" أثناء تشغيل تطبيقك
• نقل البيانات باستخدام "المراسلة عبر السحابة الإلكترونية من Firebase"

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

للحصول على التطبيق النموذجي، يمكنك اتّباع أحد الإجراءَين التاليَين:

استنسِخ المستودع من GitHub وانتقِل إلى فرع starter:

$  git clone https://github.com/googlecodelabs/android-kotlin-notifications-fcm

بدلاً من ذلك، يمكنك تنزيل المستودع كملف Zip وفك ضغطه وفتحه في Android Studio.

تنزيل ملف Zip

الخطوة 1: إنشاء مشروع Firebase

قبل أن تتمكّن من إضافة Firebase إلى تطبيق Android، عليك إنشاء مشروع على Firebase للربط بتطبيق Android.

1. سجِّل الدخول إلى وحدة تحكُّم Firebase.
2. انقر على إضافة مشروع، ثم اختَر اسم مشروع أو أدخِله. أدخِل اسمًا لمشروعك fcm-codelab.
3. انقر على متابعة.
4. يمكنك تخطّي إعداد "إحصاءات Google" من خلال إيقاف الزر تفعيل "إحصاءات Google" لهذا المشروع .
5. انقر على إنشاء مشروع لإنهاء إعداد مشروع Firebase.

الخطوة 2: تسجيل تطبيقك في Firebase

بعد إنشاء مشروع على Firebase، يمكنك إضافة تطبيق Android إليه.

1. في وسط صفحة النظرة العامة على المشروع في "وحدة تحكّم Firebase"، انقر على رمز Android لبدء خطوات الإعداد.

2. في حقل اسم حزمة Android، أدخِل com.example.android.eggtimernotifications.
3. انقر على تسجيل التطبيق.

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

الخطوة 3: إضافة ملف إعداد Firebase إلى مشروعك

أضِف ملف إعداد Firebase Android إلى تطبيقك.

1. انقر على تنزيل ملف google-services.json للحصول على ملف إعداد Firebase Android (google-services.json). تأكَّد من عدم إضافة أحرف إضافية إلى ملف الإعداد وأنّ اسمه هو google-services.json بالضبط.
2. انقل ملف الإعداد إلى دليل الوحدة (على مستوى التطبيق) في تطبيقك.

ملاحظة: يمكنك تنزيل ملف إعداد Android في Firebase مرة أخرى في أي وقت.

الخطوة 4: ضبط مشروع Android لتفعيل منتجات Firebase

لتفعيل منتجات Firebase في تطبيقك، يجب إضافة المكوّن الإضافي لخدمات Google إلى ملفات Gradle.

1. في ملف Gradle على مستوى الجذر (على مستوى المشروع) (build.gradle)، تأكَّد من توفُّر مستودع Maven من Google.
2. بعد ذلك، أضِف قواعد لتضمين المكوّن الإضافي "خدمات Google".

build.gradle

buildscript {

  repositories {
    // Check that you have the following line (if not, add it):
    google()  // Google's Maven repository
  }

  dependencies {
    // ...

    // Add the following line:
    classpath 'com.google.gms:google-services:4.3.2'  // Google Services plugin
  }
}

allprojects {
  // ...

  repositories {
    // Check that you have the following line (if not, add it):
    google()  // Google's Maven repository
    // ...
  }
}

3. في ملف Gradle الخاص بالوحدة (على مستوى التطبيق) (عادةً app/build.gradle)، أضِف سطرًا لتطبيق المكوّن الإضافي في أسفل الملف.

app/build.gradle

apply plugin: 'com.android.application'

android {
  // ...
}

// Add the following line to the bottom of the file:
apply plugin: 'com.google.gms.google-services'  // Google Play services Gradle plugin

في هذه المهمة، ستضيف خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" ‏ (FCM) إلى مشروعك للاستفادة من الإشعارات الفورية.

يتم تقديم رمز خدمة Android الخاص بخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" في هذا الدرس التطبيقي حول الترميز في MyFirebaseMessagingService.kt. في الخطوات التالية، ستضيف رمزًا إلى تطبيق Android.

ستستخدم أداة إنشاء الإشعارات لاختبار عملية التنفيذ. منشئ الإشعارات هو أداة تساعدك في إنشاء الرسائل وإرسالها من الموقع الإلكتروني لوحدة تحكّم Firebase.

1. فتح "MyFirebaseMessagingService.kt"
2. افحص الملف، وخاصةً الدوال التالية:

• onNewToken()—يتم استدعاؤها تلقائيًا إذا كانت خدمتك مسجّلة في ملف البيان Android. يتم استدعاء هذه الدالة عند تشغيل تطبيقك لأول مرة وفي كل مرة تصدر فيها Firebase رمزًا مميزًا جديدًا لتطبيقك، والرمز المميز هو مفتاح وصول إلى مشروع الخلفية في Firebase. ويتم إنشاؤه لجهاز العميل المحدّد. باستخدام هذا الرمز المميز، تعرف Firebase العميل الذي يجب أن يرسل إليه الخلفية الرسائل. يتعرّف Firebase أيضًا على ما إذا كان هذا العميل صالحًا ويمكنه الوصول إلى مشروع Firebase هذا.
• ‫onMessageReceived: يتم استدعاؤها عندما يكون تطبيقك قيد التشغيل وترسل Firebase رسالة إلى تطبيقك. تتلقّى هذه الدالة عنصر RemoteMessage يمكنه نقل حمولة إشعار أو رسالة بيانات. ستتعرّف على المزيد من المعلومات عن الاختلافات بين الإشعارات وحِزم بيانات الرسائل لاحقًا في هذا الدرس العملي.

الخطوة 1: إرسال إشعارات FCM إلى جهاز واحد

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

عندما ينشئ الخلفية في Firebase رمزًا مميّزًا جديدًا أو يتم تجديده، سيتم استدعاء الدالة onNewToken() مع تمرير الرمز المميّز الجديد كوسيطة. إذا أردت استهداف جهاز واحد أو إنشاء مجموعة من الأجهزة التي تريد إرسال رسالة بث إليها، عليك الوصول إلى هذا الرمز المميّز من خلال توسيع FirebaseMessagingService وتجاوز onNewToken().

1. افتح AndroidManifest.xml وأزِل التعليق من الرمز التالي لتفعيل MyFirebaseMessagingService لتطبيق مؤقت البيض. تسجّل بيانات الخدمة الوصفية في ملف البيان Android MyFirebaseMessagingService كخدمة وتضيف فلتر أهداف حتى تتلقّى هذه الخدمة الرسائل المُرسَلة من FCM. يحدّد الجزء الأخير من بيانات التعريف breakfast_notification_channel_id على أنّه default_notification_channel_id في Firebase. ستستخدم رقم التعريف هذا في الخطوة التالية.

<!-- AndroidManifest.xml -->
<!-- TODO: Step 3.0 uncomment to start the service  -->

        <service
                android:name=".MyFirebaseMessagingService"
                android:exported="false">
            <intent-filter>
                <action android:name="com.google.firebase.MESSAGING_EVENT"/>
            </intent-filter>
        </service>
        <!-- [START fcm_default_icon] -->
        <!--
 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/common_google_signin_btn_icon_dark"/>
        <!--
 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"/> <!-- [END fcm_default_icon] -->
        <!-- [START fcm_default_channel] -->
        <meta-data
            android:name="com.google.firebase.messaging.default_notification_channel_id"
            android:value="@string/breakfast_notification_channel_id" />
        <!-- [END fcm_default_channel] -->

من المستحسن إنشاء قناة إشعارات جديدة لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، لأنّ المستخدمين قد يريدون تفعيل/إيقاف الإشعارات الفورية من "مؤقت البيض" أو "المراسلة عبر السحابة الإلكترونية من Firebase" بشكل منفصل.

2. افتح ui/EggTimerFragment.kt . في onCreateView()، أضِف رمز إنشاء القناة التالي.

// EggTimerFragment.kt

   // TODO: Step 3.1 create a new channel for FCM
    createChannel(
        getString(R.string.breakfast_notification_channel_id),
        getString(R.string.breakfast_notification_channel_name)
    )

3. افتح MyFirebaseMessagingService.kt وأزِل التعليق من الدالة onNewToken(). سيتم استدعاء هذه الدالة عند إنشاء رمز مميّز جديد.

// MyFirebaseMessagingService.kt

   // TODO: Step 3.2 log registration token
    // [START on_new_token]
    /**
     * Called if InstanceID token is updated. This may occur if the security of
     * the previous token had been compromised. Note that this is called when the     
     * InstanceID 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
        // Instance ID token to your app server.
        sendRegistrationToServer(token)
    }
    // [END on_new_token]

4. شغِّل تطبيق مؤقت البيض.
5. مراقبة Logcat (عرض > نوافذ الأدوات > Logcat) من المفترض أن يظهر سطر سجلّ يعرض الرمز المميّز الخاص بك على النحو التالي. هذا هو الرمز المميّز الذي تحتاجه لإرسال رسالة إلى هذا الجهاز. لا يتم استدعاء هذه الدالة إلا عند إنشاء رمز مميّز جديد.

2019-07-23 13:09:15.243 2312-2459/com.example.android.eggtimernotifications D/MyFirebaseMsgService: Refreshed token: f2esflBoQbI:APA91bFMzNNFaIskjr6KIV4zKjnPA4hxekmrtbrtba2aDbh593WQnm11ed54Mv6MZ9Yeerver7pzgwfKx7R9BHFffLBItLEgPvrtF0TtX9ToCrXZ5y7Hd-m

ملاحظة: إذا لم يظهر الرمز المميّز في رسائل logcat، من المحتمل أنّ تطبيقك قد تلقّى الرمز المميّز من قبل. في هذه الحالة، سيساعدك إلغاء تثبيت التطبيق في تلقّي رمز مميّز جديد.

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

يمكنك الآن إجراء الاختبار من خلال إرسال إشعار. لإرسال إشعار، عليك استخدام أداة إنشاء الإشعارات.

4. افتح وحدة تحكُّم Firebase واختَر مشروعك.
5. بعد ذلك، اختَر المراسلة عبر السحابة الإلكترونية من قائمة التنقّل على يمين الشاشة.
6. انقر على إرسال رسالتك الأولى.

5. أدخِل Time for Breakfast! كعنوان الإشعار وDon't forget to eat eggs! كنص الإشعار، ثم انقر على إرسال رسالة اختبار. يظهر مربّع الحوار المنبثق الاختبار على الجهاز، ويطلب منك تقديم رمز تسجيل FCM.

6. انسخ الرمز المميز لتطبيقك من logcat.

7. الصِق الرمز المميّز في الحقل إضافة رمز مميّز للتسجيل في FCM ضمن النافذة المنبثقة، ثم انقر على الزر إضافة بجانب الرمز المميّز.
8. في قائمة مربّعات الاختيار التي تظهر، اختَر الرمز المميّز. من المفترض أن يتم تفعيل الزر اختبار.

9. على جهازك، شغِّل تطبيق "مؤقت البيض" في الخلفية.
10. في النافذة المنبثقة، انقر على اختبار.

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

المهمة: إرسال إشعارات FCM إلى موضوع

تستند المراسلة حسب الموضوع في "المراسلة عبر السحابة الإلكترونية من Firebase" إلى نموذج النشر/الاشتراك.

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

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

للاشتراك في موضوع، يستدعي تطبيق العميل الدالة subscribeToTopic() في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" مع اسم الموضوع breakfast. يمكن أن يكون لهذه المكالمة نتيجتان. في حال نجاح المتصل، سيتم استدعاء دالة رد الاتصال OnCompleteListener مع الرسالة التي تم الاشتراك فيها. إذا تعذّر على العميل الاشتراك، ستتلقّى الدالة رد الاتصال رسالة خطأ بدلاً من ذلك.

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

1. افتح EggTimerFragment.kt وابحث عن الدالة الفارغة subscribeTopic().
2. احصل على مثيل FirebaseMessaging واستدعِ الدالة subscibeToTopic() مع اسم الموضوع.
3. أضِف addOnCompleteListener لتلقّي إشعار من FCM بشأن نجاح اشتراكك أو تعذّره.

// EggTimerFragment.kt

   // TODO: Step 3.3 subscribe to breakfast topic
    private fun subscribeTopic() {
        // [START subscribe_topics]
        FirebaseMessaging.getInstance().subscribeToTopic(TOPIC)
            .addOnCompleteListener { task ->
                var msg = getString(R.string.message_subscribed)
                if (!task.isSuccessful) {
                    msg = getString(R.string.message_subscribe_failed)
                }
                Toast.makeText(context, msg, Toast.LENGTH_SHORT).show()
            }
        // [END subscribe_topics]
    }

2. استدعِ الدالة subscribeTopic() للاشتراك في موضوع عند بدء تشغيل التطبيق. انتقِل للأعلى إلى onCreateView() وأضِف مكالمة إلى subscribeTopic().

// EggTimerFragment.kt

   // TODO: Step 3.4 call subscribe topics on start
    subscribeTopic()

    return binding.root

3. للاشتراك في موضوع وجبة الإفطار، شغِّل التطبيق مرة أخرى. من المفترض أن تظهر رسالة منبثقة نصها "تم الاشتراك في الموضوع".

يمكنك الآن اختبار إرسال الرسائل إلى موضوع:

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

4. انقر على الآن لتحديد موعد.

5. تأكَّد من تشغيل تطبيقك في الخلفية على جهاز الاختبار.

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

يتضمّن التطبيق الآن قنوات الإشعارات التالية: البيض ووجبة الإفطار. على جهاز العميل، انقر مع الاستمرار على رمز التطبيق، ثم اختَر معلومات وانقر على الإشعارات. من المفترض أن تظهر لك قنوات الإشعارات Egg وBreakfast، كما هو موضّح في لقطة الشاشة التالية. إذا ألغيت اختيار القناة Breakfast، لن يتلقّى تطبيقك أي إشعارات يتم إرسالها عبر هذه القناة.

عند استخدام الإشعارات، ضَع في اعتبارك دائمًا أنّه يمكن للمستخدمين إيقاف أي قناة إشعارات في أي وقت.

الخطوة 1: رسائل البيانات

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

للتعامل مع رسائل البيانات، عليك التعامل مع حمولة البيانات في الدالة onMessageReceived() من MyFirebaseMessagingService. يتم تخزين الحمولة في السمة data للعنصر remoteMessage. يمكن أن يكون كل من العنصر remoteMessage والسمة data null.

1. فتح "MyFirebaseMessagingService."
2. تحقَّق ممّا إذا كانت السمة data الخاصة بالكائن remoteMessage تتضمّن بعض القيم واطبع البيانات في السجلّ.

// MyFirebaseMessagingService.kt

    // [START receive_message]
    override fun onMessageReceived(remoteMessage: RemoteMessage?) {
        // Not getting messages here? See why this may be: https://goo.gl/39bRNJ
        Log.d(TAG, "From: ${remoteMessage?.from}")
        
       // TODO: Step 3.5 check messages for data
        // Check if the message contains a data payload.
        remoteMessage?.data?.let {
            Log.d(TAG, "Message data payload: " + remoteMessage.data)
        }

    }
    // [END receive_message]

لاختبار الرمز، يمكنك استخدام أداة إنشاء الإشعارات مرة أخرى.

1. افتح "أداة إنشاء الإشعارات"، وأنشئ رسالة جديدة، واضبط الهدف على الموضوع "وجبة الإفطار".
2. في هذه المرة، عند الوصول إلى الخطوة 4، خيارات إضافية، اضبط خصائص المفتاح والقيمة للبيانات المخصّصة على النحو التالي:

1. المفتاح: eggs
2. القيمة: 3

3. تأكَّد من أنّ تطبيقك يعمل في المقدّمة. إذا كان تطبيقك يعمل في الخلفية، ستؤدي رسالة FCM إلى تشغيل إشعار تلقائي، ولن تتلقّى الدالة onMessageReceived() سوى العنصر remoteMessage عندما ينقر المستخدم على الإشعار.
4. أرسِل الرسالة من أداة إنشاء الإشعارات، وراقِب سجلّ رسائل البيانات الذي يظهر في logcat.

ملاحظة: الحدّ الأقصى لحجم الحمولة لكلا نوعَي الرسائل هو 4 كيلوبايت (باستثناء إرسال الرسائل من وحدة تحكّم Firebase، التي تفرض حدًا يبلغ 1024 حرفًا).

الخطوة 2: معالجة الرسائل في المقدّمة والخلفية

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

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

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

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

بالنسبة إلى تطبيقك، عليك التأكّد من أنّ المستخدم يتلقّى التذكير عندما يكون التطبيق في المقدّمة، لذا لننفّذ بعض الرموز البرمجية لتفعيل إشعار:

1. افتح وظيفة onMessageReceived() في MyFirebaseMessagingService مرة أخرى.
2. بعد الرمز الذي أضفته مؤخرًا للتحقّق من رسالة البيانات مباشرةً، أضِف الرمز التالي الذي يرسل إشعارًا باستخدام إطار عمل الإشعارات.

// MyFirebaseMessagingService.kt

    // TODO: Step 3.6 check messages for notification and call sendNotification
    // Check if the message contains a notification payload.
    remoteMessage.notification?.let {
        Log.d(TAG, "Message Notification Body: ${it.body}")
        sendNotification(it.body as String)
    }

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

يتوفّر رمز الحل في الفرع الرئيسي للرمز الذي تم تنزيله.

• نفِّذ BroadcastReceiver في "المراسلة عبر السحابة الإلكترونية من Firebase" من خلال توسيع FirebaseMessagingService.
• إعداد مشروع المراسلة عبر السحابة الإلكترونية من Firebase (FCM) وإضافة FCM إلى تطبيق Android
• اختبِر تطبيقك عن طريق إرسال إشعارات فورية من "أداة إنشاء الإشعارات".
• يمكنك الاشتراك في مواضيع FCM من خلال استدعاء الدالة subscribeToTopic() للفئة FirebaseMessaging.
• أرسِل حمولة بيانات باستخدام عنصر RemoteMessage.
• التعامل مع البيانات في الدالة onMessageReceived()
• أضِف منطقًا للتعامل مع "المراسلة عبر السحابة الإلكترونية من Firebase" عندما يكون التطبيق في المقدّمة وعندما يكون في الخلفية.

دورة Udacity التدريبية:

• تطوير تطبيقات Android باستخدام لغة Kotlin

مستندات Firebase:

• المراسلة عبر السحابة الإلكترونية من Firebase
• وحدة تحكّم Firebase
• تنزيل ملف إعداد Android في Firebase
• FirebaseMessagingService
• RemoteMessage
• إرسال الرسائل باستخدام "وحدة تحكّم Firebase"
• الاشتراك في موضوع من خلال تطبيق العميل

للحصول على روابط تؤدي إلى نماذج أخرى من دروس البرمجة في هذه الدورة التدريبية، يمكنك الاطّلاع على صفحة الوصول إلى نماذج دروس البرمجة في "تطبيقات متقدّمة متوافقة مع نظام Android باستخدام لغة Kotlin".