Google is committed to advancing racial equity for Black communities. See how.
ترجمت واجهة Cloud Translation API‏ هذه الصفحة.
Switch to English

قم بإعداد تطبيق Firebase Cloud Messaging على Android

لكتابة تطبيق عميل Firebase Cloud Messaging Android ، استخدم FirebaseMessaging API و Android Studio 1.4 أو أعلى مع Gradle. تفترض الإرشادات الواردة في هذه الصفحة أنك قد أكملت خطوات إضافة Firebase إلى مشروع Android الخاص بك .

تتطلب عملاء FCM أجهزة تعمل بنظام Android 4.1 أو إصدار أحدث مثبت عليها أيضًا تطبيق متجر Google Play ، أو محاكي يعمل بنظام Android 4.1 مع Google APIs. لاحظ أنك لست مقيدًا بنشر تطبيقات Android من خلال متجر Google Play.

قم بإعداد SDK

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

قبل ان تبدأ

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

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

    • تستهدف مستوى API 16 (Jelly Bean) أو ما بعده
    • يستخدم Gradle 4.1 أو أحدث
    • يستخدم Jetpack (AndroidX) ، والذي يتضمن تلبية متطلبات الإصدار التالية:
      • com.android.tools.build:gradle v3.2.1 أو أحدث
      • compileSdkVersion 28 أو أحدث
  • قم بإعداد جهاز مادي أو استخدم محاكي لتشغيل تطبيقك.
    محاكاة يجب استخدام صورة المحاكي مع جوجل اللعب.

  • سجّل الدخول إلى Firebase باستخدام حساب Google الخاص بك.

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

أنشئ مشروع Firebase

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

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

بعد أن يكون لديك مشروع Firebase ، يمكنك إضافة تطبيق Android إليه.

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

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

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

    إذا كنت قد أضفت بالفعل تطبيقًا إلى مشروع Firebase الخاص بك ، فانقر فوق إضافة تطبيق لعرض خيارات النظام الأساسي.

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

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

  5. انقر فوق تسجيل التطبيق .

أضف ملف تهيئة Firebase

  1. أضف ملف تهيئة Firebase Android إلى تطبيقك:

    1. انقر فوق تنزيل google-services.json للحصول على ملف تهيئة Firebase Android ( google-services.json ).

    2. انقل ملف التكوين الخاص بك إلى دليل الوحدة النمطية (مستوى التطبيق) لتطبيقك.

  2. لتمكين منتجات Firebase في تطبيقك ، أضف المكوِّن الإضافي لخدمات google إلى ملفات Gradle.

    1. في ملف Gradle على مستوى الجذر (على مستوى المشروع) ( build.gradle ) ، أضف قواعد لتضمين المكوّن الإضافي Google Services Gradle. تحقق من أن لديك مستودع Google Maven أيضًا.

      buildscript {
      
        repositories {
          // Check that you have the following line (if not, add it):
          google()  // Google's Maven repository
        }
      
        dependencies {
          // ...
      
          // Add the following line:
          classpath 'com.google.gms:google-services:4.3.3'  // Google Services plugin
        }
      }
      
      allprojects {
        // ...
      
        repositories {
          // Check that you have the following line (if not, add it):
          google()  // Google's Maven repository
          // ...
        }
      }
      
    2. في ملف Gradle (على مستوى التطبيق) الوحدة النمطية الخاصة بك (عادةً app/build.gradle ) ، قم بتطبيق مكون Google Services Gradle الإضافي:

      apply plugin: 'com.android.application'
      // Add the following line:
      apply plugin: 'com.google.gms.google-services'  // Google Services plugin
      
      android {
        // ...
      }
      

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

  1. إلى ملف Gradle للوحدة (على مستوى التطبيق) (عادةً app/build.gradle ) ، أضف التبعيات لمنتجات Firebase التي تريد استخدامها في تطبيقك.

    يمكنك إضافة أي من منتجات Firebase المدعومة إلى تطبيق Android الخاص بك.

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

    تم تمكين التحليلات

    dependencies {
      // ...
    // Add the Firebase SDK for Google Analytics implementation 'com.google.firebase:firebase-analytics:17.4.4'
    // Add the SDK for Firebase Cloud Messaging implementation 'com.google.firebase:firebase-messaging:20.2.4'
    // Getting a "Could not find" error? Make sure that you've added // Google's Maven repository to your root-level build.gradle file }

    لم يتم تمكين التحليلات

    dependencies {
      // ...
    // Add the SDK for Firebase Cloud Messaging implementation 'com.google.firebase:firebase-messaging:20.2.4'
    // Getting a "Could not find" error? Make sure that you've added // Google's Maven repository to your root-level build.gradle file }
  2. قم بمزامنة تطبيقك للتأكد من أن جميع التبعيات لها الإصدارات الضرورية.

  3. إذا أضفت Analytics ، فقم بتشغيل تطبيقك لإرسال إثبات إلى Firebase بأنك نجحت في دمج Firebase. خلاف ذلك ، يمكنك تخطي خطوة التحقق.

    ستعرض سجلات جهازك تحقق Firebase من اكتمال التهيئة. إذا قمت بتشغيل تطبيقك على محاكي لديه وصول إلى الشبكة ، فإن وحدة تحكم Firebase تُعلمك أن اتصال التطبيق قد اكتمل.

تحرير بيان التطبيق الخاص بك

أضف ما يلي إلى بيان تطبيقك:

  • خدمة توسع خدمة FirebaseMessagingService . هذا مطلوب إذا كنت تريد التعامل مع أي رسالة بخلاف تلقي الإشعارات على التطبيقات في الخلفية. لتلقي الإخطارات في التطبيقات المقدمة ، لتلقي حمولة البيانات ، لإرسال الرسائل الأولية ، وما إلى ذلك ، يجب عليك تمديد هذه الخدمة.
  • <service
        android:name=".java.MyFirebaseMessagingService"
        android:exported="false">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
    </service>
  • (اختياري) ضمن مكون التطبيق ، عناصر البيانات الأولية لتعيين رمز ولون إعلام افتراضي. يستخدم Android هذه القيم عندما لا تحدد الرسائل الواردة رمزًا أو لونًا بشكل صريح.
  • <!-- Set custom default icon. This is used when no icon is set for incoming notification messages.
         See README(https://goo.gl/l4GJaQ) for more. -->
    <meta-data
        android:name="com.google.firebase.messaging.default_notification_icon"
        android:resource="@drawable/ic_stat_ic_notification" />
    <!-- Set color used with incoming notification messages. This is used when no color is set for the incoming
         notification message. See README(https://goo.gl/6BKBk7) for more. -->
    <meta-data
        android:name="com.google.firebase.messaging.default_notification_color"
        android:resource="@color/colorAccent" />
  • (اختياري) من Android 8.0 (مستوى API 26) والإصدارات الأحدث ، يتم دعم قنوات الإعلام ويوصى بها. يوفر FCM قناة إعلام افتراضية مع الإعدادات الأساسية. إذا كنت تفضل إنشاء قناتك الافتراضية واستخدامها ، default_notification_channel_id بتعيين default_notification_channel_id على معرف كائن قناة الإعلام كما هو موضح ؛ سيستخدم FCM هذه القيمة عندما لا تحدد الرسائل الواردة بشكل صريح قناة إعلام. لمعرفة المزيد ، راجع إدارة قنوات الإعلام .
  • <meta-data
        android:name="com.google.firebase.messaging.default_notification_channel_id"
        android:value="@string/default_notification_channel_id" />

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

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

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

قد يتغير رمز التسجيل عندما:

  • يحذف التطبيق معرف المثيل
  • تمت استعادة التطبيق على جهاز جديد
  • يقوم المستخدم بإلغاء تثبيت / إعادة تثبيت التطبيق
  • يمسح المستخدم بيانات التطبيق.

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

عندما تحتاج إلى استرداد الرمز المميز الحالي ، اتصل بـ FirebaseInstanceId.getInstance().getInstanceId() :

جافا

FirebaseInstanceId.getInstance().getInstanceId()
        .addOnCompleteListener(new OnCompleteListener<InstanceIdResult>() {
            @Override
            public void onComplete(@NonNull Task<InstanceIdResult> task) {
                if (!task.isSuccessful()) {
                    Log.w(TAG, "getInstanceId failed", task.getException());
                    return;
                }

                // Get new Instance ID token
                String token = task.getResult().getToken();

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

Kotlin + KTX

FirebaseInstanceId.getInstance().instanceId
        .addOnCompleteListener(OnCompleteListener { task ->
            if (!task.isSuccessful) {
                Log.w(TAG, "getInstanceId failed", task.exception)
                return@OnCompleteListener
            }

            // Get new Instance ID token
            val token = task.result?.token

            // Log and toast
            val msg = getString(R.string.msg_token_fmt, token)
            Log.d(TAG, msg)
            Toast.makeText(baseContext, msg, Toast.LENGTH_SHORT).show()
        })

مراقبة توليد الرمز المميز

يتم onNewToken رد الاتصال onNewToken كلما تم إنشاء رمز جديد.

جافا

/**
 * Called if InstanceID token is updated. This may occur if the security of
 * the previous token had been compromised. Note that this is called when the InstanceID token
 * is initially generated so this is where you would retrieve the token.
 */
@Override
public void onNewToken(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
    // Instance ID token to your app server.
    sendRegistrationToServer(token);
}

Kotlin + KTX

/**
 * Called if InstanceID token is updated. This may occur if the security of
 * the previous token had been compromised. Note that this is called when the InstanceID 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
    // Instance ID token to your app server.
    sendRegistrationToServer(token)
}

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

تحقق من خدمات Google Play

يجب أن تتحقق التطبيقات التي تعتمد على Play Services SDK دائمًا من الجهاز بحثًا عن APK متوافق لخدمات Google Play قبل الوصول إلى ميزات خدمات Google Play. من المستحسن القيام بذلك في مكانين: في طريقة onCreate() للنشاط الرئيسي ، وفي طريقة onResume() . يضمن تسجيل الوصول onCreate() عدم إمكانية استخدام التطبيق دون إجراء فحص ناجح. يضمن تسجيل الوصول onResume() أنه إذا عاد المستخدم إلى التطبيق قيد التشغيل من خلال بعض الوسائل الأخرى ، مثل زر الرجوع ، فسيظل الفحص جارياً.

إذا لم يكن الجهاز يحتوي على إصدار متوافق من خدمات Google Play ، فيمكن لتطبيقك الاتصال بـ GoogleApiAvailability.makeGooglePlayServicesAvailable() للسماح للمستخدمين بتنزيل خدمات Google Play من متجر Play.

منع التهيئة التلقائية

يُنشئ Firebase معرف المثيل ، والذي تستخدمه FCM لإنشاء رمز مميز للتسجيل ويستخدم Analytics لجمع البيانات. عندما يتم إنشاء معرف المثيل ، ستقوم المكتبة بتحميل المعرف وبيانات التكوين إلى Firebase. إذا كنت تفضل منع الإنشاء التلقائي لمعرف المثيل ، فقم بتعطيل التهيئة التلقائية لـ FCM و Analytics (يجب عليك تعطيل كليهما) عن طريق إضافة قيم البيانات الوصفية هذه إلى AndroidManifest.xml :

<meta-data
    android:name="firebase_messaging_auto_init_enabled"
    android:value="false" />
<meta-data
    android:name="firebase_analytics_collection_enabled"
    android:value="false" />

لإعادة تمكين FCM ، قم بإجراء مكالمة وقت التشغيل:

جافا

FirebaseMessaging.getInstance().setAutoInitEnabled(true);

Kotlin + KTX

FirebaseMessaging.getInstance().isAutoInitEnabled = true

تستمر هذه القيمة عبر إعادة تشغيل التطبيق بمجرد تعيينها.

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

بعد إعداد تطبيق العميل ، ستكون جاهزًا لبدء إرسال الرسائل النهائية باستخدام مؤلف الإشعارات . تم توضيح هذه الوظيفة في نموذج التشغيل السريع ، والذي يمكنك تنزيله وتشغيله ومراجعته.

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

ضع في اعتبارك أنه للاستفادة من هذه الميزات ، ستحتاج إلى تنفيذ خادم و procotols الخادم (HTTP أو XMPP) ، أو تنفيذ Admin SDK .