لبدء استخدام FCM، أنشئ أبسط حالة استخدام وهي: إرسال رسالة إشعار تجريبية من مؤلف الإشعارات إلى جهاز التطوير عندما يعمل التطبيق في الخلفية على الجهاز تعرض هذه الصفحة كل الخطوات اللازمة لتنفيذ ذلك، بدءًا من عملية الإعداد إلى إثبات ملكية الحساب. — قد يغطي الخطوات التي أكملتها بالفعل إذا إعداد تطبيق عميل على Android مقابل FCM.
إعداد حزمة تطوير البرامج (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 إلى تطبيقك على Android، عليك إنشاء Firebase. توصيله بتطبيق Android. زيارة الموقع يمكنك فهم مشاريع Firebase للحصول على مزيد من المعلومات حول. مشاريع Firebase:
تسجيل تطبيقك في Firebase
لاستخدام Firebase في تطبيق Android، يجب تسجيل تطبيقك في مشروع على Firebase. وعادةً ما يُطلق على تسجيل تطبيقك اسم "الإضافة". تطبيقك إلى مشروعك.
انتقِل إلى وحدة تحكُّم Firebase.
في منتصف صفحة النظرة العامة على المشروع، انقر على رمز Android. (
) أو إضافة تطبيق لبدء عملية الإعدادأدخل اسم حزمة التطبيق في حقل اسم حزمة Android.
(اختياري) أدخِل معلومات أخرى عن التطبيق: اسم التطبيق وشهادة توقيع تصحيح الأخطاء SHA-1
انقر على تسجيل التطبيق.
إضافة ملف إعداد Firebase
تنزيل ملف إعداد Firebase لنظام التشغيل Android ثم إضافته (
) إلى تطبيقك:google-services.json انقر على تنزيل google-services.json للحصول على نظام التشغيل Firebase Android. config.
انقِل ملف الإعداد إلى الدليل الجذري للوحدة (على مستوى التطبيق) تطبيقك.
لإتاحة الوصول إلى القيم في ملف إعداد
بحزم تطوير البرامج (SDK) لمنصّة Firebase، ستحتاج إلى مكوّن Gradle لخدمات Google (google-services.json google-services
).في ملف 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 }
في ملف 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 إلى تطبيقك
في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً
<project>/<app-module>/build.gradle.kts
أو<project>/<app-module>/build.gradle
)، أضف التبعية لمكتبة Firebase Cloud Messaging لنظام التشغيل Android. ننصح باستخدام Firebase Android BoM للتحكم في إصدارات المكتبة.للحصول على تجربة مثالية مع Firebase Cloud Messaging، ننصح تفعيل Google Analytics في مشروعك على Firebase وإضافة حزمة تطوير البرامج (SDK) لمنصّة Firebase الخاصة بخدمة "إحصاءات Google" إلى تطبيقك.
dependencies { // Import the BoM for the Firebase platform implementation(platform("com.google.firebase:firebase-bom:33.2.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، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات Android في Firebase.
(بديل) إضافة اعتماديات مكتبة 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:24.0.1") implementation("com.google.firebase:firebase-analytics:22.1.0") }
مزامنة مشروع Android مع ملفات Gradle
الوصول إلى الرمز المميّز للتسجيل
لإرسال رسالة إلى جهاز محدد، يجب معرفة الرمز المميز للتسجيل. ولأنّك ستحتاج إلى إدخال الرمز المميّز في حقل في وحدة التحكّم في الإشعارات لإكمال هذا الدليل التعليمي، يجب نسخ الرمز المميّز أو تخزينها بشكل آمن بعد استرجاعها.
عند بدء تشغيل تطبيقك للمرة الأولى، تُنشئ حزمة تطوير البرامج (SDK) "FCM" تسجيلاً.
لمثيل تطبيق العميل. وإذا كنت ترغب في استهداف أجهزة أو
لإنشاء مجموعات أجهزة، فستحتاج إلى الوصول إلى هذا الرمز من خلال تمديد
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 ثم اختَر إنشاء.
إذا لم يكن الأمر كذلك، اختَر حملة جديدة من علامة التبويب الحملات. ثم الإشعارات.
أدخِل نص الرسالة. وجميع الحقول الأخرى اختيارية.
اختَر إرسال رسالة اختبار من اللوحة على يسار الصفحة.
في الحقل الذي يحمل عبارة إضافة الرمز المميّز للتسجيل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، أدخِل معلومات التسجيل الذي حصلت عليه في قسم سابق من هذا الدليل.
اختَر اختبار.
بعد اختيار اختبار، جهاز العميل المستهدف (الذي يتضمن التطبيق في الخلفية) الإشعار.
للحصول على إحصاءات بشأن تسليم الرسائل إلى تطبيقك، راجِع FCM لوحة بيانات إعداد التقارير، التي تسجّل عدد الرسائل المرسَلة وفتحها على أجهزة Apple وAndroid، إلى جانب بيانات "مرات الظهور" (الإشعارات التي اطّلع عليها المستخدمون) لتطبيقات Android.
الخطوات التالية
إرسال رسائل إلى التطبيقات التي تعمل في المقدّمة
بعد إرسال رسائل إشعارات بنجاح أثناء تشغيل التطبيق الخلفية، انظر تلقّي "الرسائل" في تطبيق Android لبدء الإرسال إلى التطبيقات التي تعمل في المقدّمة.
تجاوز رسائل الإشعارات
لتجاوز رسائل الإشعارات وإضافة سلوكيات أخرى أكثر تقدمًا إلى يمكنك الاطّلاع على: