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

لبدء استخدام ميزة "المراسلة عبر السحابة الإلكترونية من 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 باستخدام حسابك الحساب.

إذا لم يكن لديك مشروع على Android وكنت تريد فقط تجربة Firebase يمكنك تنزيل أحد نماذج البدء السريع لدينا.

إنشاء مشروع على Firebase

يجب إنشاء منصّة Firebase لتتمكّن من إضافة منصة Firebase إلى تطبيقك على Android. مشروعك لربطه بتطبيق 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. config.

    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.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" لنظام التشغيل 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.1.2"))

    // 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) من 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.2")
}
    هل تبحث عن وحدة مكتبة خاصة بلغة Kotlin؟ ستبدأ بعد تشرين الأول (أكتوبر) 2023 (الإصدار 32.5.0 من Firebase BoM)، بإمكان مطوّري برامج 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 لبدء الإرسال إلى التطبيقات التي تعمل في المقدّمة.

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

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