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

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

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

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

قبل البدء

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

  • تأكد من أن مشروعك يلبي هذه المتطلبات (لاحظ أن بعض المنتجات قد يكون لها متطلبات أكثر صرامة):

    • استهداف المستوى 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 لنظام التشغيل Android (google-services.json) ثم أضِفه إلى تطبيقك:

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

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

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

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.6.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 لإدارة إصدارات المكتبة، ما يضمن توافق جميع الإصدارات. 

    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:24.1.0")
    implementation("com.google.firebase:firebase-analytics:22.1.2")
}
         هل تبحث عن وحدة مكتبة خاصة بلغة Kotlin؟ اعتبارًا من تشرين الأول (أكتوبر) 2023 (Firebase BoM 32.5.0)، يمكن لمطوّري Kotlin وJava الاعتماد على وحدة المكتبة الرئيسية (للاطّلاع على التفاصيل، راجِع الأسئلة الشائعة حول هذه المبادرة).

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

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

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

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

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

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

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

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

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

Kotlin+KTX

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+KTX

/**
 * 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. في الحقل المُسمَّى إضافة الرمز المميّز للتسجيل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، أدخِل الرمز المميّز للتسجيل الذي حصلت عليه في قسم سابق من هذا الدليل.

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

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

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

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

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

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

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

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