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

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

قم بإعداد SDK

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

قبل ان تبدأ

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

  • تأكد من أن مشروعك يلبي هذه المتطلبات:

    • يستهدف مستوى API 19 (KitKat) أو أعلى
    • يستخدم أندرويد 4.4 أو أعلى
    • يستخدم Jetpack (AndroidX) ، والذي يتضمن تلبية متطلبات الإصدار التالية:
      • com.android.tools.build:gradle v7.3.0 أو الأحدث
      • compileSdkVersion 28 أو الأحدث

  • قم بإعداد جهاز فعلي أو استخدم محاكيًا لتشغيل تطبيقك.
    لاحظ أن حزم Firebase SDK التي تعتمد على خدمات 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 الخاص بك قابلة للوصول إلى Firebase SDK، تحتاج إلى المكون الإضافي 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.0" 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.0' 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'
  // ...
}

أضف حزم Firebase SDK إلى تطبيقك

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

    للحصول على تجربة مثالية مع Firebase Cloud Messaging، نوصي بتمكين Google Analytics في مشروع Firebase الخاص بك وإضافة Firebase SDK لـ Google Analytics إلى تطبيقك.

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:32.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:23.3.1")
    implementation("com.google.firebase:firebase-analytics:21.5.0")
}
    هل تبحث عن وحدة مكتبة خاصة بـ Kotlin؟ بدءًا من أكتوبر 2023 (Firebase BoM 32.5.0) ، يمكن لمطوري Kotlin وJava الاعتماد على وحدة المكتبة الرئيسية (لمزيد من التفاصيل، راجع الأسئلة الشائعة حول هذه المبادرة ).

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

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

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

عند بدء التشغيل الأولي لتطبيقك، تقوم FCM SDK بإنشاء رمز تسجيل مميز لمثيل تطبيق العميل. إذا كنت تريد استهداف أجهزة فردية أو إنشاء مجموعات أجهزة، فستحتاج إلى الوصول إلى هذا الرمز المميز عن طريق توسيع 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. في الحقل المسمى إضافة رمز تسجيل FCM ، أدخل رمز التسجيل الذي حصلت عليه في القسم السابق من هذا الدليل.

  9. حدد اختبار .

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

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

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

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

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

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

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