لبدء استخدام FCM ، قم ببناء أبسط حالة استخدام: إرسال رسالة إخطار اختبارية من مؤلف الإشعارات إلى جهاز تطوير عندما يكون التطبيق في الخلفية على الجهاز. تسرد هذه الصفحة جميع الخطوات لتحقيق ذلك ، من الإعداد إلى التحقق - قد تغطي الخطوات التي أكملتها بالفعل إذا قمت بإعداد تطبيق عميل Android لـ FCM.
قم بإعداد SDK
يغطي هذا القسم المهام التي ربما تكون قد أكملتها إذا كنت قد قمت بالفعل بتمكين ميزات Firebase الأخرى لتطبيقك.
قبل ان تبدأ
قم بتثبيت أو تحديث Android Studio إلى أحدث إصدار.
تأكد من أن مشروعك يلبي هذه المتطلبات:
- تستهدف مستوى API 19 (KitKat) أو أعلى
- يستخدم Android 4.4 أو أعلى
- يستخدم Jetpack (AndroidX) ، والذي يتضمن تلبية متطلبات الإصدار التالية:
-
com.android.tools.build:gradle
v3.2.1 أو أحدث -
compileSdkVersion
28 أو أحدث
-
قم بإعداد جهاز مادي أو استخدام محاكي لتشغيل تطبيقك.
لاحظ أن Firebase SDKs التي تعتمد على خدمات Google Play تتطلب تثبيت خدمات Google Play على الجهاز أو المحاكي.سجّل الدخول إلى Firebase باستخدام حساب Google الخاص بك.
إذا لم يكن لديك بالفعل مشروع Android وترغب فقط في تجربة أحد منتجات Firebase ، فيمكنك تنزيل إحدى عينات البدء السريع الخاصة بنا.
أنشئ مشروع Firebase
قبل أن تتمكن من إضافة Firebase إلى تطبيق Android ، تحتاج إلى إنشاء مشروع Firebase للاتصال بتطبيق Android. تفضل بزيارة فهم مشاريع Firebase لمعرفة المزيد حول مشاريع Firebase.
سجّل تطبيقك في Firebase
لاستخدام Firebase في تطبيق Android ، يلزمك تسجيل تطبيقك في مشروع Firebase. غالبًا ما يسمى تسجيل تطبيقك "إضافة" تطبيقك إلى مشروعك.
انتقل إلى وحدة تحكم Firebase .
في وسط صفحة نظرة عامة على المشروع ، انقر فوق رمز Android (
) أو إضافة تطبيق لبدء سير عمل الإعداد.أدخل اسم حزمة تطبيقك في حقل اسم حزمة Android .
يعرّف اسم الحزمة بشكل فريد تطبيقك على الجهاز وفي متجر Google Play.
غالبًا ما يشار إلى اسم الحزمة باسم معرف التطبيق .
ابحث عن اسم حزمة التطبيق الخاص بك في ملف Gradle (على مستوى التطبيق) للوحدة النمطية ، وعادةً ما يكون
app/build.gradle
(مثال على اسم الحزمة:com.yourcompany.yourproject
).اعلم أن قيمة اسم الحزمة حساسة لحالة الأحرف ، ولا يمكن تغييرها لتطبيق Firebase Android هذا بعد تسجيله في مشروع Firebase.
(اختياري) أدخل معلومات التطبيق الأخرى: لقب التطبيق وشهادة توقيع تصحيح الأخطاء SHA-1 .
لقب التطبيق : معرّف داخلي ملائم يكون مرئيًا لك فقط في وحدة تحكم Firebase
شهادة توقيع تصحيح الأخطاء SHA-1: مطلوب تجزئة SHA-1 بواسطة مصادقة Firebase (عند استخدام تسجيل الدخول إلى Google أو تسجيل الدخول برقم الهاتف ) و Firebase Dynamic Links .
انقر فوق تسجيل التطبيق .
أضف ملف تهيئة Firebase
قم بتنزيل ملف تهيئة Firebase Android (
) ثم أضفه إلى تطبيقك:google-services.json انقر فوق تنزيل google-services.json للحصول على ملف تهيئة Firebase Android.
انقل ملف التكوين الخاص بك إلى دليل جذر الوحدة النمطية (مستوى التطبيق) لتطبيقك.
يحتوي ملف تهيئة Firebase على معرّفات فريدة ولكنها غير سرية لمشروعك. لمعرفة المزيد حول ملف التكوين هذا ، تفضل بزيارة فهم مشاريع Firebase .
يمكنك تنزيل ملف تهيئة Firebase مرة أخرى في أي وقت.
تأكد من عدم إلحاق اسم ملف التكوين بأحرف إضافية ، مثل
(2)
.
لجعل القيم الموجودة في ملف التكوين
الخاص بك قابلة للوصول إلى Firebase SDKs ، فأنت بحاجة إلى المكون الإضافي لخدمات Google Gradle (google-services.json google-services
).في ملف Gradle على مستوى الجذر (على مستوى المشروع) (
<project>/build.gradle.kts
أو<project>/build.gradle
) ، أضف المكوِّن الإضافي لخدمات Google كعنصر تابع:Kotlin
plugins { id("com.android.application") version "7.2.0" apply false // ... // Add the dependency for the Google services Gradle plugin id("com.google.gms.google-services") version "4.3.15" apply false }
Groovy
plugins { id 'com.android.application' version '7.2.0' apply false // ... // Add the dependency for the Google services Gradle plugin id 'com.google.gms.google-services' version '4.3.15' apply false }
في ملف 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 إلى تطبيقك
في ملف Gradle (على مستوى التطبيق) الوحدة النمطية الخاصة بك (عادةً
<project>/<app-module>/build.gradle.kts
أو<project>/<app-module>/build.gradle
) ، أضف تبعية Firebase Cloud مكتبة المراسلة Android. نوصي باستخدام Firebase Android BoM للتحكم في إصدارات المكتبة.للحصول على تجربة مثالية مع Firebase Cloud Messaging ، نوصي بتمكين Google Analytics في مشروع Firebase وإضافة Firebase SDK لـ Google Analytics إلى تطبيقك.
Kotlin+KTX
dependencies { // Import the BoM for the Firebase platform implementation(platform("com.google.firebase:firebase-bom:32.3.1")) // 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-ktx") implementation("com.google.firebase:firebase-analytics-ktx") }
باستخدام 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-ktx:23.2.1") implementation("com.google.firebase:firebase-analytics-ktx:21.3.0") }
Java
dependencies { // Import the BoM for the Firebase platform implementation(platform("com.google.firebase:firebase-bom:32.3.1")) // 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.2.1") implementation("com.google.firebase:firebase-analytics:21.3.0") }
قم بمزامنة مشروع Android الخاص بك مع ملفات Gradle.
إن إنشاءات Gradle التي تستخدم المكون الإضافي Android Gradle (AGP) v4.2 أو إصدار سابق تحتاج إلى تمكين دعم Java 8. بخلاف ذلك ، تتعرض مشاريع Android هذه لإخفاق في الإنشاء عند إضافة Firebase SDK.
لإصلاح فشل هذا الإصدار ، يمكنك اتباع أحد الخيارين التاليين:
- أضف خيارات
compileOptions
المدرجة من رسالة الخطأ إلى ملفbuild.gradle.kts
على مستوى التطبيق أو ملفbuild.gradle
. - قم بزيادة
minSdk
لمشروع Android الخاص بك إلى 26 أو أعلى.
تعرف على المزيد حول فشل هذا الإصدار في هذه الأسئلة الشائعة .
- أضف خيارات
الوصول إلى رمز التسجيل
لإرسال رسالة إلى جهاز معين ، تحتاج إلى معرفة رمز تسجيل هذا الجهاز. نظرًا لأنك ستحتاج إلى إدخال الرمز المميز في حقل في وحدة التحكم في الإشعارات لإكمال هذا البرنامج التعليمي ، تأكد من نسخ الرمز المميز أو تخزينه بشكل آمن بعد استرداده.
عند بدء التشغيل الأولي لتطبيقك ، تنشئ 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) }
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); }
بعد حصولك على الرمز المميز ، يمكنك إرساله إلى خادم التطبيق وتخزينه باستخدام طريقتك المفضلة.
إرسال رسالة إخطار اختبار
قم بتثبيت التطبيق وتشغيله على الجهاز المستهدف. على أجهزة Apple ، ستحتاج إلى قبول طلب الإذن لتلقي الإشعارات عن بُعد.
تأكد من أن التطبيق في الخلفية على الجهاز.
في وحدة تحكم Firebase ، افتح صفحة المراسلة .
إذا كانت هذه هي رسالتك الأولى ، فحدد إنشاء حملتك الأولى .
- حدد رسائل إعلام Firebase وحدد إنشاء .
بخلاف ذلك ، في علامة التبويب "الحملات" ، حدد "حملة جديدة " ثم "التنبيهات" .
أدخل نص الرسالة. جميع الحقول الأخرى اختيارية.
حدد إرسال رسالة اختبار من الجزء الأيمن.
في الحقل المسمى إضافة رمز تسجيل FCM ، أدخل رمز التسجيل الذي حصلت عليه في قسم سابق من هذا الدليل.
حدد اختبار .
بعد تحديد اختبار ، يجب أن يتلقى جهاز العميل المستهدف (مع التطبيق في الخلفية) الإشعار.
للحصول على نظرة ثاقبة حول تسليم الرسائل إلى تطبيقك ، راجع لوحة تحكم تقارير FCM ، التي تسجل عدد الرسائل المرسلة والمفتوحة على أجهزة Apple و Android ، إلى جانب بيانات "مرات الظهور" (الإشعارات التي يراها المستخدمون) لتطبيقات Android.
الخطوات التالية
إرسال رسائل إلى التطبيقات المقدمة
بمجرد إرسال رسائل الإشعارات بنجاح أثناء وجود التطبيق في الخلفية ، راجع تلقي الرسائل في تطبيق Android لبدء الإرسال إلى التطبيقات المتقدمة.
تجاوز رسائل الإشعارات
لتجاوز رسائل الإشعارات وإضافة سلوك آخر أكثر تقدمًا إلى تطبيقك ، راجع: