إرسال رسالة اختبار إلى تطبيق في الخلفية

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

إعداد حزمة تطوير البرامج (SDK)

يتناول هذا القسم المهام التي ربما تكون قد أكملتها إذا سبق لك تفعيل ميزات أخرى من Firebase لتطبيقك.

قبل البدء

  • ثبِّت Android Studio أو حدِّثه إلى أحدث إصدار.

  • يجب التأكّد من أنّ مشروعك يستوفي هذه المتطلبات (يُرجى العِلم أنّ بعض المنتجات قد تتضمّن متطلبات أكثر صرامة):

    • يستهدف المستوى 21 من واجهة برمجة التطبيقات (Lollipop) أو الإصدارات الأحدث
    • يستخدم الإصدار 5.0 من نظام التشغيل Android أو إصدارًا أحدث
    • يستخدم Jetpack (AndroidX)، الذي يتضمّن استيفاء متطلبات الإصدار التالية:
      • ‫com.android.tools.build:gradle الإصدار 7.3.0 أو إصدار أحدث
      • ‫compileSdkVersion 28 أو إصدار أحدث

  • يمكنك إعداد جهاز فعلي أو استخدام محاكي لتشغيل تطبيقك.
    يُرجى العِلم أنّ حِزم تطوير البرامج (SDK) من Firebase التي تعتمد على خدمات Google Play تتطلّب تثبيت خدمات Google Play على الجهاز أو المحاكي.

  • سجِّل الدخول إلى Firebase باستخدام حسابك على Google.

إذا لم يكن لديك مشروع Android وتريد فقط تجربة أحد منتجات Firebase، يمكنك تنزيل أحد نماذج التشغيل السريع.

إنشاء مشروع Firebase

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

تسجيل تطبيقك في Firebase

لاستخدام Firebase في تطبيق Android، عليك تسجيل تطبيقك في مشروعك على Firebase. يُطلق على تسجيل تطبيقك غالبًا اسم "إضافة" تطبيقك إلى مشروعك.

  1. انتقِل إلى Firebase وحدة التحكّم.

  2. في وسط صفحة "نظرة عامة على المشروع"، انقر على رمز Android () أو إضافة تطبيق لبدء سير عمل الإعداد.

  3. أدخِل اسم حزمة تطبيقك في حقل اسم حزمة Android.

  4. (اختياري) أدخِل معلومات التطبيق الأخرى: الاسم المختصر للتطبيق وشهادة توقيع تصحيح الأخطاء SHA-1.

  5. انقر على تسجيل التطبيق.

إضافة ملف إعدادات Firebase

  1. نزِّل ملف إعداد Firebase الخاص بتطبيقك (google-services.json) ثم أضِفه إلى قاعدة الرموز البرمجية:

    1. انقر على تنزيل ملف google-services.json للحصول على ملف إعدادات Firebase لتطبيقك.

    2. انقِل ملف الإعداد إلى الدليل الجذري للوحدة (على مستوى التطبيق) في تطبيقك.

  2. لإتاحة الوصول إلى القيم في ملف الإعداد google-services.json لحِزم تطوير البرامج (SDK) في Firebase، يجب استخدام مكوّن Gradle الإضافي لخدمات Google (google-services).

    1. في ملف Gradle على مستوى الجذر (على مستوى المشروع) (<project>/build.gradle.kts أو <project>/build.gradle)، أضِف المكوّن الإضافي لخدمات Google كعنصر تابع:

      Kotlin 

      plugins {
  id("com.android.application") version "7.3.0" apply false
  // ...

  // Add the dependency for the Google services Gradle plugin
  id("com.google.gms.google-services") version "4.4.3" apply false
}

      Groovy 

      plugins {
  id 'com.android.application' version '7.3.0' apply false
  // ...

  // Add the dependency for the Google services Gradle plugin
  id 'com.google.gms.google-services' version '4.4.3' apply false
}

    2. في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، أضِف المكوّن الإضافي لخدمات Google:

      Kotlin 

      plugins {
  id("com.android.application")

  // Add the Google services Gradle plugin
  id("com.google.gms.google-services")
  // ...
}

      Groovy 

      plugins {
  id 'com.android.application'

  // Add the Google services Gradle plugin
  id 'com.google.gms.google-services'
  // ...
}

إضافة حِزم تطوير البرامج (SDK) من Firebase إلى تطبيقك

  1. في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، أضِف الاعتمادية لمكتبة Firebase Cloud Messaging لنظام التشغيل Android. ننصحك باستخدام Firebase Android BoM للتحكّم في إصدارات المكتبة.

    للحصول على أفضل تجربة مع Firebase Cloud Messaging، ننصحك بتفعيل Google Analytics في مشروعك على Firebase وإضافة حزمة تطوير البرامج (SDK) الخاصة بخدمة "إحصاءات Google" لبرنامج Firebase إلى تطبيقك. 

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:34.0.0"))

    // Add the dependencies for the Firebase Cloud Messaging and Analytics libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-messaging")
    implementation("com.google.firebase:firebase-analytics")
}

    باستخدام Firebase Android BoM، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات Firebase Android.

    (بديل)  أضِف تبعيات مكتبة Firebase بدون استخدام BoM

    إذا اخترت عدم استخدام Firebase BoM، عليك تحديد إصدار كل مكتبة من مكتبات Firebase في سطر التبعية الخاص بها.

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

    dependencies {
    // Add the dependencies for the Firebase Cloud Messaging and Analytics libraries
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-messaging:25.0.0")
    implementation("com.google.firebase:firebase-analytics:23.0.0")
}

  2. مزامنة مشروع Android مع ملفات Gradle

الوصول إلى رمز التسجيل

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

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

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

قد يتغيّر رمز التسجيل في الحالات التالية:

  • تمت استعادة التطبيق على جهاز جديد
  • يلغي المستخدم تثبيت التطبيق أو يعيد تثبيته
  • يمحو المستخدم بيانات التطبيق.

استرداد رمز التسجيل الحالي

عند الحاجة إلى استرداد الرمز المميّز الحالي، اتّصِل بالدالة FirebaseMessaging.getInstance().getToken():

Kotlin

FirebaseMessaging.getInstance().token.addOnCompleteListener(OnCompleteListener { task ->
    if (!task.isSuccessful) {
        Log.w(TAG, "Fetching FCM registration token failed", task.exception)
        return@OnCompleteListener
    }

    // Get new FCM registration token
    val token = task.result

    // Log and toast
    val msg = getString(R.string.msg_token_fmt, token)
    Log.d(TAG, msg)
    Toast.makeText(baseContext, msg, Toast.LENGTH_SHORT).show()
})

Java

FirebaseMessaging.getInstance().getToken()
    .addOnCompleteListener(new OnCompleteListener<String>() {
        @Override
        public void onComplete(@NonNull Task<String> task) {
          if (!task.isSuccessful()) {
            Log.w(TAG, "Fetching FCM registration token failed", task.getException());
            return;
          }

          // Get new FCM registration token
          String token = task.getResult();

          // Log and toast
          String msg = getString(R.string.msg_token_fmt, token);
          Log.d(TAG, msg);
          Toast.makeText(MainActivity.this, msg, Toast.LENGTH_SHORT).show();
        }
    });

مراقبة إنشاء الرموز المميزة

يتم تشغيل الدالة onNewToken عند إنشاء رمز مميز جديد.

Kotlin

/**
 * Called if the FCM registration token is updated. This may occur if the security of
 * the previous token had been compromised. Note that this is called when the
 * FCM registration 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
    // FCM registration token to your app server.
    sendRegistrationToServer(token)
}
MyFirebaseMessagingService.kt

Java

/**
 * There are two scenarios when onNewToken is called:
 * 1) When a new token is generated on initial app startup
 * 2) Whenever an existing token is changed
 * Under #2, there are three scenarios when the existing token is changed:
 * A) App is restored to a new device
 * B) User uninstalls/reinstalls the app
 * C) User clears app data
 */
@Override
public void onNewToken(@NonNull String token) {
    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
    // FCM registration token to your app server.
    sendRegistrationToServer(token);
}
MyFirebaseMessagingService.java

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

إرسال رسالة إشعار اختبار

  1. ثبِّت التطبيق وشغِّله على الجهاز المستهدف. على أجهزة Apple، عليك قبول طلب الحصول على إذن بتلقّي إشعارات عن بُعد.

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

  3. في وحدة تحكّم Firebase، افتح صفحة "المراسلة".

  4. إذا كانت هذه هي رسالتك الأولى، اختَر إنشاء حملتك الأولى.

    1. اختَر رسائل إشعارات Firebase، ثمّ انقر على إنشاء.

  5. بخلاف ذلك، في علامة التبويب الحملات، انقر على حملة جديدة، ثمّ على الإشعارات.

  6. أدخِل نص الرسالة. جميع الحقول الأخرى اختيارية.

  7. اختَر إرسال رسالة اختبار من اللوحة اليمنى.

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

  9. انقر على اختبار.

بعد النقر على اختبار، من المفترض أن يتلقّى جهاز العميل المستهدَف (مع تشغيل التطبيق في الخلفية) الإشعار.

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

الخطوات التالية

إرسال رسائل إلى التطبيقات التي تعمل في المقدّمة

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

تجاوز رسائل الإشعارات

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