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

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

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

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

قبل البدء

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

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

    • يستهدف المستوى 19 من واجهة برمجة التطبيقات (KitKat) أو مستوى أعلى
    • يستخدم الإصدار 4.4 من نظام التشغيل Android أو إصدارًا أحدث
    • تستخدم Jetpack (AndroidX)، الذي يتضمن استيفاء متطلبات الإصدار التالية:
      • الإصدار 7.3.0 من "com.android.tools.build:gradle" أو إصدار أحدث
      • 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 للحصول على ملف إعداد Firebase لنظام التشغيل Android.

    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.1" 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.1' 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" لنظام التشغيل Android. ننصحك باستخدام برنامج Firebase Android BoM للتحكّم في إصدارات المكتبة.

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

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.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")
}

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

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

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

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

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

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

عند بدء تشغيل التطبيق لأول مرة، تُنشئ حزمة تطوير البرامج (SDK) لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" رمزًا مميزًا للتسجيل لمثيل تطبيق العميل. إذا كنت تريد استهداف أجهزة فردية أو إنشاء مجموعات أجهزة، عليك الوصول إلى هذا الرمز المميّز من خلال توسيع 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. اختَر اختبار.

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

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

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

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

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

لا تقتصر على رسائل الإشعارات

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