تتطلب برامج FCM أجهزة تعمل بنظام Android 4.4 أو أعلى تشتمل أيضًا على تطبيق "متجر Google Play" مثبَّتًا عليه، أو محاكي يعمل بنظام التشغيل Android 4.4 مع واجهات Google APIs. يُرجى ملاحظة أنّه لا يقتصر نشر تطبيقات Android من خلال "متجر Google Play".
إعداد حزمة تطوير البرامج (SDK)
يتناول هذا القسم المهام التي قد تكون أكملتها إذا سبق لك تفعيلها. ميزات Firebase الأخرى لتطبيقك. أضِف Firebase إلى مشروع Android إذا لم يسبق لك إجراء ذلك.
تعديل بيان التطبيق
أضِف ما يلي إلى بيان التطبيق:
- خدمة تمتد إلى
FirebaseMessagingService. هذا الإجراء مطلوب إذا تريد التعامل مع أي رسائل بخلاف تلقي الإشعارات على التطبيقات في الخلفية. لتلقّي إشعارات في التطبيقات التي تعمل في المقدّمة، يجب تلقّي حمولة البيانات وإرسال الرسائل الأولية وما إلى ذلك، عليك توسيع نطاق خدمة ما.
<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" />
default_notification_channel_id على رقم تعريف عنصر قناة الإشعارات
كما هو موضح؛ ستستخدم خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"
عندما لا يتم تعيين إشعار بشكل صريح للرسائل الواردة
. لمزيد من المعلومات، يُرجى مراجعة
إدارة قنوات الإشعارات
<meta-data
android:name="com.google.firebase.messaging.default_notification_channel_id"
android:value="@string/default_notification_channel_id" />
طلب إذن إرسال الإشعارات في بيئة التشغيل على الإصدار 13 من نظام التشغيل Android أو الإصدارات الأحدث
يقدّم نظام Android 13 إذنًا جديدًا لوقت تشغيل لعرض الإشعارات. هذا النمط يؤثر في كل التطبيقات التي تعمل بنظام التشغيل Android 13 أو الإصدارات الأحدث والتي تستخدم خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" الإشعارات.
بشكل تلقائي، تتضمّن حزمة تطوير البرامج (SDK) لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" (الإصدار 23.0.6 أو إصدار أحدث) ما يلي:
POST_NOTIFICATIONS
المحدد في البيان.
مع ذلك، سيحتاج تطبيقك أيضًا إلى طلب إصدار بيئة التشغيل لهذا
إذن عن طريق الثابت، android.permission.POST_NOTIFICATIONS.
لن يُسمَح لتطبيقك بعرض الإشعارات حتى
منح المستخدم هذا الإذن.
لطلب إذن التشغيل الجديد:
Kotlin+KTX
// 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 من المستخدم.
أذونات إرسال الإشعارات للتطبيقات التي تستهدف الإصدار 12L من Android (المستوى 32 لواجهة برمجة التطبيقات) أو الإصدارات الأقدم
يطلب Android من المستخدِم الحصول على الإذن تلقائيًا في أول مرّة ينشئ قناة إشعارات، طالما أن التطبيق يعمل في المقدّمة. مع ذلك، هناك تنبيهات مهمة بشأن توقيت إنشاء القناة وطلبات الأذونات:
- إذا أنشأ تطبيقك قناة الإشعارات الأولى عند تشغيله في الخلفية (التي تفعلها حزمة تطوير البرامج (SDK) للمراسلة عبر السحابة الإلكترونية من Firebase عند تلقي "المراسلة عبر السحابة الإلكترونية من Firebase")، لن يسمح Android بإرسال الإشعار ولن يتم طلب إذن إرسال الإشعارات من المستخدم حتى في المرة القادمة التي يتم فيها فتح تطبيقك. يعني ذلك أنّه أيّ إشعارات تم استلامها سيتم فقدان الإذن قبل فتح التطبيق وقبول المستخدم للإذن.
- ننصحك بشدة بتحديث تطبيقك لاستهداف الإصدار 13 من نظام التشغيل Android أو الإصدارات الأحدث الاستفادة من واجهات برمجة التطبيقات للنظام الأساسي لطلب الإذن. إذا لم يكن الأمر كذلك على التطبيق، يجب إنشاء قنوات للإشعارات قبل إرسال أيّ إرسال إشعارات إلى التطبيق لتفعيل إذن إرسال الإشعارات والتأكد من عدم فقدان أي إشعارات. عرض أفضل الممارسات المتعلقة بأذونات إرسال الإشعارات لمزيد من المعلومات.
اختياري: إزالة إذن "POST_NOTIFICATIONS"
تتضمّن حزمة تطوير البرامج (SDK) لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" تلقائيًا إذن POST_NOTIFICATIONS.
إذا كان التطبيق لا يستخدم رسائل الإشعارات (سواء من خلال خدمة "المراسلة عبر السحابة الإلكترونية من Firebase")
الإشعارات من خلال حزمة تطوير برامج (SDK) أخرى أو نشرها تطبيقك مباشرةً)
كنت لا تريد أن يتضمّن تطبيقك الإذن، يمكنك إزالته باستخدام
عمليات دمج البيانات
محدّد الموقع remove يُرجى العِلم أنّ إزالة هذا الإذن تمنع العرض.
من كل الإشعارات، وليس فقط إشعارات "المراسلة عبر السحابة الإلكترونية من Firebase" إضافة ما يلي إلى
ملف البيان لتطبيقك:
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" tools:node="remove"/>
الوصول إلى الرمز المميّز لتسجيل الجهاز
عند بدء تشغيل التطبيق للمرة الأولى، تُنشئ حزمة تطوير البرامج (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)
}
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" ويُنصح بتنفيذ هذا الإجراء في
مكانين: في طريقة onCreate() للنشاط الرئيسي، وفي
طريقة onResume(). يضمن تسجيل الوصول في onCreate() أن التطبيق
ولا يمكن استخدامها بدون إجراء تحقق ناجح. يضمن تسجيل الوصول في onResume()
أنّه إذا عاد المستخدم إلى التطبيق قيد التشغيل من خلال وسائل أخرى، مثل
من خلال زر الرجوع، فستظل عملية التحقق تتم.
إذا لم يكن لدى الجهاز إصدار متوافق من خدمات Google Play، يمكن لتطبيقك الاتصال
GoogleApiAvailability.makeGooglePlayServicesAvailable()
للسماح للمستخدمين بتنزيل خدمات Google Play من "متجر Play".
منع الإعداد التلقائي
عند إنشاء رمز مميز للتسجيل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، يتم تحميل المكتبة
بيانات المعرف والتهيئة
Firebase. إذا كنت تفضّل منع الإنشاء التلقائي للرموز المميّزة، أوقِف جمع "إحصاءات Google"
الإعداد التلقائي للمراسلة عبر السحابة الإلكترونية من Firebase (يجب إيقاف كليهما) من خلال إضافة قيم البيانات الوصفية هذه إلى
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" />
لإعادة تفعيل التشغيل التلقائي لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، عليك إجراء مكالمة في بيئة التشغيل:
Kotlin+KTX
Firebase.messaging.isAutoInitEnabled = true
Java
FirebaseMessaging.getInstance().setAutoInitEnabled(true);
لإعادة تفعيل جمع البيانات في "إحصاءات Google"، اطلب
setAnalyticsCollectionEnabled()
للفئة FirebaseAnalytics. على سبيل المثال:
setAnalyticsCollectionEnabled(true);
وتظل هذه القيم سارية في جميع عمليات إعادة تشغيل التطبيق بعد ضبطها.
الخطوات التالية
يمكنك البدء بعد الانتهاء من إعداد تطبيق العميل. إرسال الرسائل المنتقلة بعد ذلك باستخدام منشئ الإشعارات هذه الوظيفة كما هو موضح في نموذج البدء السريع، التي يمكنك تنزيلها وتشغيلها ومراجعتها.
لإضافة سلوك آخر أكثر تقدّمًا إلى تطبيقك، عليك الإعلان عن فلتر أهداف وتنفيذ نشاط للرد على الرسائل الواردة الرسائل. للحصول على التفاصيل، راجِع أدلة إرسال الرسائل من خادم التطبيقات:
ملاحظات يجب أخذها في الاعتبار ذلك، للاستفادة من هذه الميزات، ستحتاج إلى تنفيذ الخادم وبروتوكولات الخادم (HTTP أو XMPP) أو بروتوكولات تنفيذ SDK للمشرف.