| اختيار المنصة: | iOS+ Android الويب Flutter Unity C++ |
يوضّح هذا الدليل كيفية بدء استخدام Firebase Cloud Messaging في تطبيقات Android للعملاء لكي تتمكّن من إرسال الرسائل بشكل موثوق.
يتطلب عملاء FCM أجهزة تعمل بنظام التشغيل Android 7.0 أو الإصدارات الأحدث التي تم تثبيت تطبيق "متجر Google Play" عليها أيضًا، أو محاكي يعمل بنظام التشغيل Android 7.0 مع Google APIs. يُرجى العِلم أنّك لست مقيّدًا بنشر تطبيقات Android من خلال "متجر Google Play" فقط.
إعداد حزمة تطوير البرامج (SDK)
أضِف Firebase إلى مشروع Android الخاص بك، في حال لم يسبق لك إجراء ذلك.
للحصول على تجربة مثالية مع "FCM"، ننصحك بشدة بتفعيل Google Analytics في مشروعك. يجب تفعيل Google Analytics لإعداد تقارير تسليم الرسائل في FCM.
تعديل ملف بيان التطبيق
أضِف ما يلي إلى ملف بيان تطبيقك:
- خدمة تتيح استخدام
FirebaseMessagingServiceهذا الإجراء مطلوب إذا أردت معالجة أي رسائل بخلاف تلقّي الإشعارات على التطبيقات في الخلفية. لتلقّي الإشعارات في التطبيقات التي تعمل في المقدّمة، وتلقّي حمولة البيانات، والمزيد، عليك توسيع نطاق هذه الخدمة. - (اختياري) ضمن مكوّن التطبيق، عناصر البيانات الوصفية لضبط رمز الإشعار التلقائي ولونه يستخدم Android هذه القيم عندما لا تحدّد الرسائل الواردة الرمز أو اللون بشكل صريح.
- (اختياري) بدءًا من الإصدار Android 8.0 (مستوى واجهة برمجة التطبيقات 26) والإصدارات الأحدث،
تتوفّر قنوات الإشعارات ويُنصح باستخدامها. FCM يوفّر قناة إشعارات تلقائية
مع إعدادات أساسية. إذا كنت تفضّل
إنشاء واستخدام قناتك التلقائية،
اضبط
default_notification_channel_idعلى رقم تعريف عنصر قناة الإشعارات كما هو موضّح، وستستخدم FCM هذه القيمة عندما لا تضبط الرسائل الواردة قناة إشعارات بشكل صريح. لمزيد من المعلومات، يُرجى الاطّلاع على إدارة قنوات الإشعارات.
<service android:name=".java.MyFirebaseMessagingService" android:exported="false"> <intent-filter> <action android:name="com.google.firebase.MESSAGING_EVENT" /> </intent-filter> </service>
<!-- 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" />
<meta-data android:name="com.google.firebase.messaging.default_notification_channel_id" android:value="@string/default_notification_channel_id" />
طلب إذن إرسال الإشعارات أثناء التشغيل على Android 13 والإصدارات الأحدث
يقدّم Android 13 إذن تشغيل جديدًا لعرض الإشعارات. يؤثر هذا التغيير في جميع التطبيقات التي تعمل بنظام التشغيل Android 13 أو الإصدارات الأحدث والتي تستخدم إشعارات FCM.
بشكل تلقائي، تتضمّن حزمة تطوير البرامج (SDK) لـ FCM (الإصدار 23.0.6 أو إصدار أحدث) الإذن
POST_NOTIFICATIONS
المحدّد في ملف البيان. ومع ذلك، سيحتاج تطبيقك أيضًا إلى طلب
إصدار وقت التشغيل لهذا الإذن باستخدام الثابت
android.permission.POST_NOTIFICATIONS. لن يُسمح لتطبيقك بعرض الإشعارات إلى أن يمنح المستخدم هذا الإذن.
لطلب إذن التشغيل الجديد:
Kotlin
// Declare the launcher at the top of your Activity/Fragment: private val requestPermissionLauncher = registerForActivityResult( ActivityResultContracts.RequestPermission(), ) { isGranted: Boolean -> if (isGranted) { // FCM SDK (and your app) can post notifications. } else { // TODO: Inform user that that your app will not show notifications. } } private fun askNotificationPermission() { // This is only necessary for API level >= 33 (TIRAMISU) if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) { if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) == PackageManager.PERMISSION_GRANTED ) { // FCM SDK (and your app) can post notifications. } else if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) { // TODO: display an educational UI explaining to the user the features that will be enabled // by them granting the POST_NOTIFICATION permission. This UI should provide the user // "OK" and "No thanks" buttons. If the user selects "OK," directly request the permission. // If the user selects "No thanks," allow the user to continue without notifications. } else { // Directly ask for the permission requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS) } } }
Java
// Declare the launcher at the top of your Activity/Fragment: private final ActivityResultLauncher<String> requestPermissionLauncher = registerForActivityResult(new ActivityResultContracts.RequestPermission(), isGranted -> { if (isGranted) { // FCM SDK (and your app) can post notifications. } else { // TODO: Inform user that that your app will not show notifications. } }); private void askNotificationPermission() { // This is only necessary for API level >= 33 (TIRAMISU) if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) { if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) == PackageManager.PERMISSION_GRANTED) { // FCM SDK (and your app) can post notifications. } else if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) { // TODO: display an educational UI explaining to the user the features that will be enabled // by them granting the POST_NOTIFICATION permission. This UI should provide the user // "OK" and "No thanks" buttons. If the user selects "OK," directly request the permission. // If the user selects "No thanks," allow the user to continue without notifications. } else { // Directly ask for the permission requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS); } } }
بشكل عام، يجب عرض واجهة مستخدم توضّح للمستخدم الميزات التي سيتم تفعيلها إذا منح التطبيق أذونات لنشر الإشعارات. يجب أن توفّر واجهة المستخدم هذه خيارات للمستخدم للموافقة أو الرفض، مثل زرَّي حسنًا ولا شكرًا. إذا اختار المستخدم حسنًا، اطلب الإذن مباشرةً. إذا اختار المستخدم لا، شكرًا، اسمح له بالمتابعة بدون إشعارات.
يمكنك الاطّلاع على إذن التشغيل الخاص بالإشعارات
لمعرفة المزيد من أفضل الممارسات حول الحالات التي يجب أن يطلب فيها تطبيقك إذن POST_NOTIFICATIONS
من المستخدم.
أذونات إرسال الإشعارات للتطبيقات التي تستهدف الإصدار Android 12L (مستوى واجهة برمجة التطبيقات 32) أو الإصدارات الأقدم
يطلب Android تلقائيًا من المستخدم الحصول على الإذن في المرة الأولى التي ينشئ فيها تطبيقك قناة إشعارات، طالما أنّ التطبيق في المقدّمة. ومع ذلك، هناك تحذيرات مهمة بشأن توقيت إنشاء القناة وطلبات الحصول على الإذن:
- إذا أنشأ تطبيقك أول قناة إشعارات له أثناء تشغيله في الخلفية، وهو ما تفعله حزمة تطوير البرامج (SDK) لخدمة FCM عند تلقّي إشعار من FCM، لن يسمح Android بعرض الإشعار ولن يطلب من المستخدم منح إذن إرسال الإشعارات إلا في المرة التالية التي يتم فيها فتح تطبيقك. وهذا يعني أنّ أي إشعارات يتم تلقّيها قبل فتح تطبيقك وقبول المستخدم للإذن ستُفقد.
- ننصحك بشدة بتحديث تطبيقك لاستهداف الإصدار 13 من نظام التشغيل Android أو الإصدارات الأحدث للاستفادة من واجهات برمجة التطبيقات الخاصة بالنظام الأساسي لطلب الإذن. وإذا لم يكن ذلك ممكنًا، يجب أن ينشئ تطبيقك قنوات إشعارات قبل إرسال أي إشعارات إلى التطبيق لتفعيل مربّع حوار إذن إرسال الإشعارات والتأكّد من عدم فقدان أي إشعارات. يمكنك الاطّلاع على أفضل الممارسات المتعلّقة بإذن إرسال الإشعارات لمزيد من المعلومات.
اختياري: إزالة إذن "POST_NOTIFICATIONS"
تتضمّن حزمة تطوير البرامج (SDK) لـ "FCM" تلقائيًا الإذن "POST_NOTIFICATIONS".
إذا كان تطبيقك لا يستخدم رسائل الإشعارات (سواء من خلال إشعارات FCM أو من خلال حزمة تطوير برامج أخرى أو من خلال نشرها مباشرةً من تطبيقك) ولا تريد أن يتضمّن تطبيقك الإذن، يمكنك إزالته باستخدام علامة remove دمج ملفات البيان. يُرجى العِلم أنّ إزالة هذا الإذن تمنع عرض جميع الإشعارات، وليس فقط إشعارات "FCM". أضِف ما يلي إلى
ملف بيان تطبيقك:
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" tools:node="remove"/>
الوصول إلى معرّف Firebase Installation ID
عند بدء تشغيل تطبيقك لأول مرة، تسجِّل حزمة تطوير البرامج (SDK) لخدمة FCM مثيل التطبيق في
FCM وتعرض معرّفًا لمثيل التطبيق. إذا أردت استهداف نُسخ فردية من التطبيق، عليك الوصول إلى هذا المعرّف من خلال توسيع
FirebaseMessagingService وتجاوز
onRegistered().
كأفضل ممارسة، يمكنك استرداد أحدث معرّف تم تعديله لأنّه يمكن تدوير المعرّف بعد بدء التشغيل الأوّلي.
تفعيل التسجيل من خلال معرّف تثبيت Firebase
لتفعيل تسجيل مثيل تطبيقك في "FCM" باستخدام رقم تعريف تثبيت Firebase (FID)، أضِف علامة البيانات الوصفية التالية إلى ملفAndroidManifest.xml:
<meta-data android:name="firebase_messaging_installation_id_enabled" android:value="true" />
تنفيذ دالة الاستدعاء onRegistered()
يتم استهداف مثيلات التطبيق باستخدام معرّف تثبيت Firebase (FID) بعد تسجيلها
في FCM. لاسترداد معرّف FID عند التسجيل، نفِّذ دالة الاستدعاء
onRegistered().
بعد تسجيل مثيل تطبيق، تراقب حزمة تطوير البرامج (SDK) لخدمة FCM
تغييرات معرّف مثيل Firebase تلقائيًا وتستدعي دالة الاستدعاء عند رصد تغيير.
عند تفعيل الإعداد التلقائي، تتم مزامنة حزمة تطوير البرامج (SDK) لخدمة "FCM"
تلقائيًا مع الخلفية في "FCM" لإبقاء التسجيل محدَّثًا واستدعاء دالة الاستدعاء
لضمان حصول خادم التطبيق على المعرّف الحالي. للحماية من فقدان معرّف مثيل Firebase أو
معرّفات مثيل Firebase القديمة، عليك إرسال معرّف مثيل Firebase إلى خادم تطبيقك كلما تم تشغيل رد الاتصال هذا.
Kotlin
/** * There are three scenarios when `onRegistered` is called: * 1) Every time a manual `register()` call finishes successfully * 2) Whenever the FID is changed and the app is re-registered with FCM via the new FID. * 3) Automatically on app startup or routine sync when auto-initialization is enabled. * Under #2, there are three scenarios when the existing FID is changed: * A) App is restored to a new device * B) User uninstalls/reinstalls the app * C) User clears app data */ override fun onRegistered(installationId: String) { Log.d(TAG, "Registered installation ID: $installationId") // Send the Firebase Installation ID to your app server. sendRegistrationToServer(installationId) }
Java
/** * There are three scenarios when `onRegistered` is called: * 1) Every time a manual `register()` call finishes successfully * 2) Whenever the FID is changed and the app is re-registered with FCM via the new FID * 3) Automatically on app startup or routine sync when auto-initialization is enabled. * Under #2, there are three scenarios when the existing FID is changed: * A) App is restored to a new device * B) User uninstalls/reinstalls the app * C) User clears app data */ @Override public void onRegistered(@NonNull String installationId) { Log.d(TAG, "Registered installation ID: " + installationId); // Send the Firebase Installation ID to your app server. sendRegistrationToServer(installationId); }
التسجيل يدويًا عند إيقاف الإعداد التلقائي
إذا كان عليك إيقاف الإعداد التلقائي، لن تتم مزامنة حزمة تطوير البرامج (SDK) لخدمة "FCM" تلقائيًا أو لن يتم تفعيل دالة الاستدعاء
onRegistered()
عند بدء التشغيل. ننصح بشدة بإعادة تفعيل الإعداد التلقائي بعد
منح إذن إرسال الإشعارات. لمزيد من المعلومات، يُرجى الاطّلاع على
إعادة تفعيل الإعداد التلقائي.
إذا كان يجب أن تظل ميزة الإعداد التلقائي غير مفعَّلة، يمكنك استدعاء
FirebaseMessaging.getInstance().register() عند بدء تشغيل التطبيق لتفعيل
التسجيل وتسليم معرّف مثيل Firebase من خلال
دالة الاستدعاء
onRegistered(). يمكنك
تنفيذ هذا الطلب ضمن إجراء
onCreate() في
Activity الرئيسي.
Kotlin
// Trigger manual registration if auto-initialization is turned off. // Consider calling this every time the app starts to guarantee sync status. FirebaseMessaging.getInstance().register() .addOnCompleteListener(this) { task -> if (!task.isSuccessful()) { // Registration failed. Consider retrying the registration with exponential backoff. Log.w(TAG, "Failed to register with Firebase Cloud Messaging", task.exception) } // Success! The Firebase Installation ID can be used to target messages to this app // instance and will be delivered asynchronously to your `onRegistered()` callback. }
Java
// Trigger manual registration if auto-initialization is turned off. // Consider calling this every time the app starts to guarantee sync status. FirebaseMessaging.getInstance().register() .addOnCompleteListener(task -> { if (!task.isSuccessful()) { // Registration failed. Consider retrying the registration with exponential backoff. Log.w(TAG, "Failed to register with Firebase Cloud Messaging", task.exception) } // Success! The Firebase Installation ID can be used to target messages to this app // instance and will be delivered asynchronously to your `onRegistered()` callback. });
الوصول إلى رمز التسجيل المميّز في "FCM" (متوقّف نهائيًا)
عند بدء تشغيل تطبيقك لأول مرة، تنشئ حزمة تطوير البرامج (SDK) لخدمة FCM رمزًا مميزًا للتسجيل لنسخة تطبيق العميل. إذا أردت استهداف نُسخ تطبيق واحدة أو إنشاء مجموعات أجهزة، عليك الوصول إلى هذا الرمز المميّز من خلال تمديد
FirebaseMessagingService وتجاوز onNewToken. بما أنّه يمكن تبديل الرمز المميّز بعد بدء التشغيل الأولي، ننصحك بشدة باسترداد آخر رمز مميّز للتسجيل تم تعديله.
قد يتغيّر رمز التسجيل المميّز في الحالات التالية:
- تمت استعادة التطبيق على جهاز جديد
- يلغي المستخدم تثبيت التطبيق أو يعيد تثبيته
- محو بيانات التطبيق من قِبل المستخدم
استرداد الرمز المميّز الحالي للتسجيل
عندما تحتاج إلى استرداد الرمز المميّز الحالي، يمكنك استدعاء
FirebaseMessaging.getInstance().getToken():
Kotlin
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
/** * 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); }
بعد الحصول على الرمز المميّز، يمكنك إرساله إلى خادم تطبيقك وتخزينه باستخدام الطريقة المفضّلة لديك.
التحقّق من توفّر "خدمات Google Play"
يجب أن تتحقّق التطبيقات التي تعتمد على حزمة تطوير البرامج (SDK) لخدمات Play دائمًا من توفّر حزمة APK متوافقة لخدمات Google Play على الجهاز قبل الوصول إلى ميزات خدمات Google Play. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إعداد "خدمات Google Play". ننصحك بإجراء ذلك في مكانَين: في إجراء onCreate() الخاص بالنشاط الرئيسي وفي إجراء onResume() الخاص به. يضمن التحقّق في "onCreate()" عدم إمكانية استخدام التطبيق بدون إجراء عملية تحقّق ناجحة. يضمن التحقّق في onResume() أنّه إذا عاد المستخدم إلى التطبيق قيد التشغيل من خلال وسيلة أخرى، مثل زر الرجوع، سيستمر إجراء التحقّق.
إذا لم يكن الجهاز يحتوي على إصدار متوافق من "خدمات Google Play"، يمكن لتطبيقك استدعاء GoogleApiAvailability.makeGooglePlayServicesAvailable() للسماح للمستخدمين بتنزيل "خدمات Google Play" من "متجر Play".
منع الإعداد التلقائي
عند إنشاء تسجيل FCM، تحمّل المكتبة المعرّف وبيانات الإعداد إلى Firebase. إذا كنت تفضّل منع التسجيل التلقائي، يمكنك إيقاف جمع بيانات "إحصاءات Google" وبدء FCM تلقائيًا (يجب إيقاف كليهما) من خلال إضافة قيم البيانات الوصفية هذه إلى 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، يمكنك إجراء طلب في وقت التشغيل:
Kotlin
Firebase.messaging.isAutoInitEnabled = true
Java
FirebaseMessaging.getInstance().setAutoInitEnabled(true);
لإعادة تفعيل جمع البيانات في "إحصاءات Google"، استخدِم طريقة
setAnalyticsCollectionEnabled()
من فئة FirebaseAnalytics. على سبيل المثال:
setAnalyticsCollectionEnabled(true);
وتظل هذه القيم محفوظة عند إعادة تشغيل التطبيق بعد ضبطها.
إرسال رسالة إشعار
للتأكّد من إعداد برنامج Android بشكل صحيح، يمكنك إرسال رسالة إشعار تجريبية باتّباع التعليمات التالية:
ثبِّت التطبيق وشغِّله على جهاز الاختبار.
تأكَّد من أنّ التطبيق يعمل في الخلفية على الجهاز.
في وحدة تحكّم Firebase، انتقِل إلى DevOps والتفاعل > المراسلة
أنشئ حملة.
إذا كانت هذه رسالتك الأولى:
انقر على إنشاء حملتك الأولى.
اختَر رسائل إشعارات Firebase، ثمّ انقر على إنشاء.
إذا سبق لك إنشاء حملات:
في علامة التبويب الحملات، انقر على حملة جديدة.
انقر على الإشعارات.
أدخِل نص الرسالة. وجميع الحقول الأخرى اختيارية.
انقر على إرسال رسالة اختبار من اللوحة اليسرى.
في الحقل الذي يحمل التصنيف إضافة رمز تسجيل في خدمة "مراسلة Firebase السحابية"، أدخِل رمز التسجيل الذي حصلت عليه في قسم سابق من هذا الدليل.
اختَر اختبار.
يجب أن يتلقّى جهاز العميل المستهدَف الإشعار، مع تشغيل التطبيق في الخلفية.
للحصول على إحصاءات حول تسليم الرسائل إلى تطبيقك، انتقِل إلى لوحة بيانات DevOps & Engagement > Messaging > Reports في وحدة تحكّم Firebase. تسجّل لوحة البيانات هذه عدد الرسائل المُرسَلة والمفتوحة على أجهزة Apple وAndroid، بالإضافة إلى بيانات "مرّات الظهور" (الإشعارات التي يراها المستخدمون) لتطبيقات Android.
الخطوات التالية
بعد إكمال خطوات الإعداد، إليك بعض الخيارات للمضي قدمًا في استخدام "FCM" على أجهزة Android: