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

للبدء باستخدام 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.

  1. في وحدة تحكّم Firebase، انقر على إضافة مشروع.

    • لإضافة موارد Firebase إلى مشروع Google Cloud حالي، أدخِل اسم المشروع أو اختَره من القائمة المنسدلة.

    • لإنشاء مشروع جديد، أدخِل اسم المشروع المطلوب. يمكنك أيضًا اختياريًا تعديل رقم تعريف المشروع المعروض أسفل اسم المشروع.

  2. راجِع بنود Firebase واقبلها في حال طُلب منك ذلك.

  3. انقر على متابعة.

  4. (اختياري) يمكنك إعداد Google Analytics لمشروعك، ما يتيح لك الحصول على تجربة مثالية باستخدام أيّ من منتجات Firebase التالية:

    اختَر إما حساب Google Analytics حاليًا أو أنشئ حسابًا جديدًا.

    إذا أنشأت حسابًا جديدًا، اختَر Analytics الموقع الجغرافي لإعداد التقارير، ثم وافِق على إعدادات مشاركة البيانات وبنود Google Analytics لمشروعك.

  5. انقر على إنشاء مشروع (أو إضافة Firebase، إذا كنت تستخدم مشروعًا حاليًا على Google Cloud).

توفّر Firebase الموارد تلقائيًا لمشروعك على Firebase. عند اكتمال العملية، سيتم نقلك إلى صفحة النظرة العامة لمشروع Firebase في وحدة تحكّم Firebase.

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

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

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

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

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

    • يحدِّد اسم الحزمة تطبيقك بشكلٍ فريد على الجهاز وفي "متجر Google Play".

    • يُشار إلى اسم الحزمة غالبًا باسم رقم تعريف التطبيق.

    • ابحث عن اسم حزمة تطبيقك في ملف Gradle للوحدة (على مستوى التطبيق)، وهو عادةً app/build.gradle (مثال على اسم الحزمة: com.yourcompany.yourproject).

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

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

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

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

  1. نزِّل ملف إعدادات Firebase لنظام التشغيل Android (google-services.json) ثم أضِفه إلى تطبيقك:

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

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

    • يحتوي ملف إعدادات Firebase على معرّفات فريدة، ولكنها غير سرية لمشروعك. لمعرفة المزيد من المعلومات عن ملف الإعدادات هذا، يُرجى الانتقال إلى مقالة فهم مشاريع Firebase.

    • يمكنك تنزيل ملف إعداد Firebase مجددًا في أي وقت.

    • تأكَّد من عدم إلحاق اسم ملف الإعدادات بأحرف إضافية، مثل (2).

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

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

      KotlinGroovy
      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
      }
      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:

      KotlinGroovy
      plugins {
        id("com.android.application")
      
        // Add the Google services Gradle plugin
        id("com.google.gms.google-services")
        // ...
      }
      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.9.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 في سطر التبعية الخاص به.

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

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

    يجب تفعيل استخدام Java 8 في عمليات إنشاء Gradle التي تستخدم الإصدار 4.2 من المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP) أو الإصدارات الأقدم. بخلاف ذلك، ستتعذّر عملية إنشاء مشاريع Android هذه عند إضافة حزمة تطوير برامج Firebase.

    لحلّ مشكلة تعذُّر إنشاء التطبيق، يمكنك اتّباع أحد الخيارَين التاليَين:

    • أضِف compileOptions المدرَج في رسالة الخطأ إلى ملفbuild.gradle.kts أو build.gradle على مستوى التطبيق.
    • عليك زيادة minSdk لمشروع Android إلى 26 أو إصدار أحدث.

    يمكنك الاطّلاع على مزيد من المعلومات حول تعذُّر إنشاء الحزمة في هذه الأسئلة الشائعة.

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

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

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

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

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

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

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

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

KotlinJava
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()
})
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 عند إنشاء رمز مميّز جديد.

KotlinJava
/**
 * 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)
}
/**
 * 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);
}

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

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

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

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

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

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

    1. اختَر رسائل إشعارات Firebase ثمّ إنشاء.
  5. بخلاف ذلك، في علامة التبويب الحملات، اختَر حملة جديدة ثم الإشعارات.

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

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

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

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

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

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

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

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

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

الاستفادة من ميزات إضافية في الإشعارات

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