کلاینتهای FCM به دستگاههایی با Android نسخه ۴.۴ یا بالاتر نیاز دارند که برنامه فروشگاه Google Play را نیز نصب کرده باشند، یا شبیهسازی دارای Android نسخه ۴.۴ با Google API. توجه داشته باشید که شما محدود به استقرار برنامه های اندروید خود از طریق فروشگاه Google Play نیستید.
SDK را تنظیم کنید
اگر قبلاً سایر ویژگیهای Firebase را برای برنامه خود فعال کرده باشید، این بخش وظایفی را پوشش میدهد که ممکن است انجام داده باشید. اگر قبلاً این کار را نکرده اید، Firebase را به پروژه اندروید خود اضافه کنید
مانیفست برنامه خود را ویرایش کنید
موارد زیر را به مانیفست برنامه خود اضافه کنید:
- سرویسی که
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
را مطابق شکل روی شناسه شی کانال اطلاعرسانی خود تنظیم کنید. هر زمان که پیامهای دریافتی کانال اعلان تنظیم نکرده باشند، FCM از این مقدار استفاده میکند. برای کسب اطلاعات بیشتر، به مدیریت کانالهای اعلان مراجعه کنید.<meta-data android:name="com.google.firebase.messaging.default_notification_channel_id" android:value="@string/default_notification_channel_id" />
درخواست مجوز اعلان زمان اجرا در Android 13+
اندروید 13 مجوز زمان اجرا جدیدی را برای نمایش اعلان ها معرفی می کند. این روی همه برنامههایی که روی Android نسخه 13 یا بالاتر اجرا میشوند و از اعلانهای FCM استفاده میکنند، تأثیر میگذارد.
به طور پیش فرض، FCM SDK (نسخه 23.0.6 یا بالاتر) شامل مجوز POST_NOTIFICATIONS
تعریف شده در مانیفست است. با این حال، برنامه شما همچنین باید نسخه زمان اجرا این مجوز را از طریق ثابت، android.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() { 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); } }
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() { 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) } }
به طور کلی، شما باید یک رابط کاربری نمایش دهید که ویژگی هایی را به کاربر توضیح دهد که در صورت اعطای مجوز به برنامه برای ارسال اعلان ها فعال می شوند. این رابط کاربری باید گزینههای موافقت یا رد کردن را در اختیار کاربر قرار دهد، مانند دکمههای OK و No تشکر . اگر کاربر OK را انتخاب کرد، مستقیماً مجوز را درخواست کنید. اگر کاربر خیر، تشکر را انتخاب کرد، به کاربر اجازه دهید بدون اعلان ادامه دهد.
برای بهترین روشهای بیشتر درباره زمانی که برنامه شما باید مجوز POST_NOTIFICATIONS
را از کاربر درخواست کند، مجوز زمان اجرا اعلان را ببینید.
مجوزهای اعلان برای برنامههایی که Android 12L (سطح API 32) یا پایینتر را هدف قرار میدهند
تا زمانی که برنامه در پیش زمینه باشد، اندروید به طور خودکار از کاربر اجازه می خواهد اولین باری که برنامه شما یک کانال اعلان ایجاد می کند. با این حال، هشدارهای مهمی در مورد زمان ایجاد کانال و درخواست مجوز وجود دارد:
- اگر برنامه شما اولین کانال اعلان خود را هنگامی که در پسزمینه اجرا میشود ایجاد کند (که FCM SDK هنگام دریافت اعلان FCM انجام میدهد)، Android اجازه نمایش اعلان را نمیدهد و تا زمان بعدی از کاربر اجازه اعلان را نمیخواهد. زمانی که برنامه شما باز می شود این بدان معناست که هرگونه اعلانهایی که قبل از باز شدن برنامه شما و پذیرش مجوز توسط کاربر دریافت میشود، از بین میرود .
- ما قویاً توصیه میکنیم که برنامه خود را بهمنظور هدف قرار دادن Android 13+ بهروزرسانی کنید تا از APIهای پلتفرم برای درخواست مجوز استفاده کنید. اگر این امکان وجود ندارد، برنامه شما باید قبل از ارسال اعلان به برنامه، کانال های اعلان ایجاد کند تا گفتگوی مجوز اعلان را فعال کند و مطمئن شود هیچ اعلانی از بین نمی رود. برای اطلاعات بیشتر به بهترین شیوه های مجوز اعلان مراجعه کنید.
اختیاری: حذف مجوز POST_NOTIFICATIONS
به طور پیشفرض، FCM SDK شامل مجوز POST_NOTIFICATIONS
است. اگر برنامه شما از پیامهای اعلان استفاده نمیکند (خواه از طریق اعلانهای FCM، از طریق SDK دیگر، یا مستقیماً توسط برنامه شما پست شده است) و نمیخواهید برنامه شما مجوز را داشته باشد، میتوانید آن را با استفاده از نشانگر remove
ادغام مانیفست حذف کنید. به خاطر داشته باشید که حذف این مجوز از نمایش همه اعلانها و نه فقط اعلانهای FCM جلوگیری میکند. موارد زیر را به فایل مانیفست برنامه خود اضافه کنید:
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" tools:node="remove"/>
به رمز ثبت دستگاه دسترسی پیدا کنید
در راه اندازی اولیه برنامه شما، FCM SDK یک نشانه ثبت نام برای نمونه برنامه مشتری ایجاد می کند. اگر میخواهید دستگاههای منفرد را هدف قرار دهید یا گروههای دستگاه ایجاد کنید، باید با گسترش FirebaseMessagingService
و لغو onNewToken
به این نشانه دسترسی داشته باشید.
این بخش نحوه بازیابی توکن و نحوه نظارت بر تغییرات توکن را توضیح می دهد. از آنجایی که رمز می تواند پس از راه اندازی اولیه چرخانده شود، اکیداً به شما توصیه می شود که آخرین توکن ثبت نام به روز شده را بازیابی کنید.
رمز ثبت نام ممکن است زمانی تغییر کند که:
- برنامه در یک دستگاه جدید بازیابی می شود
- کاربر برنامه را حذف/نصب مجدد می کند
- کاربر داده های برنامه را پاک می کند.
رمز ثبت نام فعلی را بازیابی کنید
هنگامی که نیاز به بازیابی رمز فعلی دارید، FirebaseMessaging.getInstance().getToken()
:
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(); } });
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() })
نظارت بر تولید توکن
پاسخ به تماس onNewToken
هر زمان که یک توکن جدید تولید شود فعال می شود.
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); }
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) }
پس از دریافت رمز، می توانید آن را به سرور برنامه خود ارسال کرده و با استفاده از روش دلخواه خود آن را ذخیره کنید.
خدمات Google Play را بررسی کنید
برنامههایی که به Play Services SDK متکی هستند، همیشه باید قبل از دسترسی به ویژگیهای سرویسهای Google Play، دستگاه را برای یک APK سازگار با خدمات Google Play بررسی کنند. توصیه می شود این کار را در دو مکان انجام دهید: در onCreate()
اکتیویتی اصلی و در متد () onResume()
آن. بررسی onCreate()
تضمین میکند که برنامه بدون بررسی موفقیتآمیز قابل استفاده نیست. بررسی onResume()
تضمین میکند که اگر کاربر از طریق روشهای دیگری مانند دکمه برگشت به برنامه در حال اجرا برگردد، بررسی همچنان انجام میشود.
اگر دستگاه نسخه سازگار خدمات Google Play را ندارد، برنامه شما میتواند با GoogleApiAvailability.makeGooglePlayServicesAvailable()
تماس بگیرد تا به کاربران اجازه دهد خدمات Google Play را از فروشگاه Play دانلود کنند.
جلوگیری از مقداردهی اولیه خودکار
هنگامی که یک نشانه ثبت FCM تولید می شود، کتابخانه شناسه و داده های پیکربندی را در Firebase آپلود می کند. اگر ترجیح میدهید از تولید خودکار نشانهها جلوگیری کنید، مجموعه Analytics و مقداردهی اولیه خودکار 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، یک تماس در زمان اجرا برقرار کنید:
Java
FirebaseMessaging.getInstance().setAutoInitEnabled(true);
Kotlin+KTX
Firebase.messaging.isAutoInitEnabled = true
برای فعال کردن مجدد مجموعه Analytics، setAnalyticsCollectionEnabled()
از کلاس FirebaseAnalytics
را فراخوانی کنید. مثلا:
setAnalyticsCollectionEnabled(true);
این مقادیر پس از تنظیم در سراسر راه اندازی مجدد برنامه باقی می مانند.
مراحل بعدی
پس از راهاندازی برنامه مشتری، آماده ارسال پیامهای پاییندستی با سازنده Notifications هستید. این قابلیت در نمونه راه اندازی سریع نشان داده شده است که می توانید آن را دانلود، اجرا و مرور کنید.
برای افزودن سایر رفتارهای پیشرفته تر به برنامه خود، می توانید یک فیلتر قصد اعلام کنید و یک فعالیت برای پاسخ به پیام های دریافتی اجرا کنید. برای جزئیات، به راهنمای ارسال پیام از سرور برنامه مراجعه کنید:
به خاطر داشته باشید که برای استفاده از این ویژگیها، به اجرای سرور و پروتکلهای سرور (HTTP یا XMPP) یا پیادهسازی Admin SDK نیاز دارید.