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

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

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

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

قبل البدء

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

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

    • استهداف المستوى 19 من واجهة برمجة التطبيقات (KitKat) أو أعلى
    • تستخدِم الإصدار 4.4 من نظام التشغيل 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. لإتاحة القيم في ملف الإعداد 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. ننصح باستخدام بنود سياسة Android في Firebase للتحكّم في نُسَخ المكتبة.

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

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

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