| انتخاب پلاتفرم: | iOS+ Android Web Flutter Unity C++ |
این راهنما نحوه شروع به کار با Firebase Cloud Messaging در برنامههای کارخواه Android را توضیح میدهد تا بتوانید پیامها را بهطور مطمئن ارسال کنید.
مشتریان FCM به دستگاههایی نیاز دارند که Android 6.0 یا بالاتر داشته باشند و برنامه «فروشگاه Google Play» نیز در آنها نصب شده باشد، یا به شبیهسازی نیاز دارند که Android 6.0 با «میاناهای برنامهسازی کاربردی Google» داشته باشد. توجه داشته باشید که محدود به استقرار برنامههای Android ازطریق «فروشگاه Google Play» نیستید.
راهاندازی کیت توسعه نرمافزار
اگر قبلاً این کار را نکردهاید، Firebase را به پروژه Android خود اضافه کنید.
برای داشتن تجربهای بهینه با FCM، اکیداً توصیه میکنیم فعال کردن Google Analytics را در پروژهتان فعال کنید. Google Analytics برای گزارش ارسال پیام برای FCM الزامی است.
ویرایش مانیفست برنامه
مورد زیر را به مانیفست برنامهتان اضافه کنید:
- سرویسی که
FirebaseMessagingServiceرا گسترش میدهد. اگر میخواهید هرگونه مدیریت پیام فراتر از دریافت اعلان در برنامههای پسزمینه انجام دهید، این مورد الزامی است. برای دریافت اعلان در برنامههای پیشزمینهای، برای دریافت دادهبار، و غیره، باید این سرویس را گسترش دهید. - (اختیاری) در عنصر برنامه، عناصر فراداده برای تنظیم نماد و رنگ اعلان پیشفرض. Android هرگاه پیامهای ورودی بهطور صریح نماد یا رنگ را تنظیم نکنند از این مقادیر استفاده میکند.
- (اختیاری) از Android 8.0 (سطح میانای برنامهسازی کاربردی ۲۶) و بالاتر،
کانالهای اعلان پشتیبانی میشود و توصیه میشود. 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 استفاده میکنند تأثیر میگذارد.
بهطور پیشفرض، کیت توسعه نرمافزار FCM (نسخه ۲۳.۰.۶ یا بالاتر) شامل
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 (سطح میانای برنامهسازی کاربردی ۳۲) یا پایینتر را هدفیابی میکنند
وقتی برنامه شما برای اولینبار کانال اعلانی ایجاد میکند، Android بهطور خودکار از کاربر اجازه میخواهد، بهشرطی که برنامه در پیشزمینه باشد. بااینحال، نکتههای مهمی درباره زمان ایجاد کانال و درخواستهای اجازه وجود دارد:
- اگر برنامه شما اولین کانال اعلان خود را زمانی ایجاد کند که در پسزمینه درحال اجرا است، که کیت توسعه نرمافزار FCM هنگام دریافت اعلان FCM این کار را انجام میدهد، Android اجازه نمیدهد اعلان نمایش داده شود و تا دفعه بعدی که برنامه شما باز شود، از کاربر برای اجازه اعلان درخواست نمیکند. این یعنی هر اعلانی که قبلاز باز شدن برنامه و پذیرفتن اجازه توسط کاربر دریافت شود ازدست خواهد رفت.
- اکیداً توصیه میکنیم برنامهتان را بهروز کنید تا Android 13 و نسخههای بالاتر را هدفیابی کند و از میاناهای برنامهسازی کاربردی پلاتفرم برای درخواست اجازه استفاده کند. اگر این کار امکانپذیر نیست، برنامه شما باید قبلاز ارسال هرگونه اعلان به برنامه، کانالهای اعلان ایجاد کند تا کادر گفتگوی اجازه اعلان را راهاندازی کند و مطمئن شود هیچ اعلانی ازدست نمیرود. برای اطلاعات بیشتر، اجازه اعلان بهترین روشها را ببینید.
اختیاری: برداشتن اجازه POST_NOTIFICATIONS
بهطور پیشفرض، «کیت توسعه نرمافزار» FCM شامل اجازه POST_NOTIFICATIONS است.
اگر برنامه شما از پیامهای اعلان استفاده نمیکند (چه ازطریق FCM
اعلانها، چه ازطریق کیت توسعه نرمافزار دیگر، یا چه مستقیماً توسط برنامه شما پست شود) و نمیخواهید برنامه شما این اجازه را داشته باشد، میتوانید آن را بااستفاده از نشانگر ادغامکننده مانیفست
remove بردارید. بهخاطر داشته باشید که برداشتن این اجازه باعث میشود
همه اعلانها نمایش داده نشوند، نه فقط اعلانهای FCM. مورد زیر را به
فایل مانیفست برنامهتان اضافه کنید:
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" tools:node="remove"/>
دسترسی به «شناسه نصب Firebase»
در شروع اولیه برنامه، کیت توسعه نرمافزار FCM نمونه برنامه را در
FCM ثبت میکند و شناسه نمونه برنامه را برمیگرداند. اگر میخواهید نمونههای برنامه را هدفیابی کنید، باید با گسترش دادن
FirebaseMessagingService و ملغی کردن
onRegistered() به این شناسه دسترسی پیدا کنید.
بهعنوان روال مطلوب، جدیدترین شناسه بهروزرسانیشده را بازیابی کنید زیرا شناسه میتواند پساز راهاندازی اولیه تغییر کند.
فعال کردن ثبتنام ازطریق «شناسه نصب Firebase»
برای فعال کردن ثبت نمونه برنامه با FCM بااستفاده از شناسه نصب Firebase (FID)، پرچم فراداده زیر را به فایلAndroidManifest.xml اضافه کنید:
<meta-data android:name="firebase_messaging_installation_id_enabled" android:value="true" />
پیادهسازی پاسخ تماس onRegistered()
نمونههای برنامه پساز ثبت شدن در FCM بااستفاده از «شناسه نصب Firebase» (FID) هدفیابی میشوند. برای بازیابی FID پساز ثبتنام،
onRegistered() را پیادهسازی کنید.
پساز ثبت نمونه برنامه، FCM SDK
بهطور خودکار تغییرات FID را پایش میکند و وقتی تغییری تشخیص داده شود، با تابع برگشتی تماس میگیرد.
وقتی مقداردهی اولیه خودکار فعال باشد، FCM کیت توسعه نرمافزار
بهطور خودکار با زیرینه FCM همگامسازی میشود تا ثبت را تازه نگه دارد و با فراخوانی
پاسخگویی تضمین میکند که سرور برنامه شما شناسه فعلی را دارد. برای محافظت دربرابر ازدست رفتن FID یا
قدیمی شدن FID، باید هرگاه این برگشت به تماس راهاندازی میشود، FID را به سرور برنامهتان ارسال کنید.
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) }
جاوا
/** * 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); }
وقتی مقداردهی اولیه خودکار غیرفعال است، بهصورت دستی ثبت کنید
اگر باید مقداردهی اولیه خودکار را غیرفعال کنید، «کیت توسعه نرمافزار» FCM بهطور خودکار همگامسازی نمیشود یا
بازخوانی onRegistered() را
در زمان راهاندازی راهاندازی نمیکند. اکیداً توصیه میشود که پساز اعطای اجازههای اعلان،
راهاندازی خودکار را دوباره فعال کنید. برای کسب اطلاعات بیشتر،
فعال کردن مجدد مقداردهی اولیه خودکار را ببینید.
اگر باید مقداردهی اولیه خودکار غیرفعال بماند،
FirebaseMessaging.getInstance().register() را در راهاندازی برنامه فراخوانی کنید تا
ثبتنام و ارائه FID ازطریق
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. }
جاوا
// 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 (منسوخ)
در راهاندازی اولیه برنامه، کیت توسعه نرمافزار 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»
برنامههایی که به «کیت توسعه نرمافزار خدمات Play» متکی هستند باید همیشه قبلاز دسترسی به ویژگیهای «خدمات Google Play»، سازگاری دستگاه با فایل APK «خدمات Google Play» را بررسی کنند. برای کسب اطلاعات بیشتر، راهاندازی خدمات Google Play را ببینید. توصیه میشود این کار را در دو جا انجام دهید: در روش onCreate() فعالیت اصلی، و در روش onResume() آن. بررسی در onCreate() تضمین میکند که برنامه بدون بررسی موفقیتآمیز قابلاستفاده نباشد. بررسی در onResume() تضمین میکند که اگر کاربر ازطریق روش دیگری، مثلاً ازطریق دکمه بازگشت، به برنامه درحال اجرا برگردد، بررسی همچنان انجام شود.
اگر دستگاه نسخه سازگاری از «خدمات Google Play» نداشته باشد، برنامه شما میتواند
GoogleApiAvailability.makeGooglePlayServicesAvailable()
را فراخوانی کند تا به کاربران اجازه دهد «خدمات Google Play» را از «فروشگاه Play» بارگیری کنند.
جلوگیری از مقداردهی اولیه خودکار
وقتی ثبت FCM تولید میشود، کتابخانه
شناسه و دادههای پیکربندی را در Firebase بارگذاری میکند. اگر ترجیح میدهید از ثبت خودکار جلوگیری کنید، با افزودن این مقادیر فراداده به AndroidManifest.xml، جمعآوری Analytics و مقداردهی اولیه خودکار FCM را غیرفعال کنید (باید هر دو را غیرفعال کنید):
<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);
برای فعال کردن مجدد جمعآوری Analytics،
setAnalyticsCollectionEnabled()
روش کلاس FirebaseAnalytics را فراخوانی کنید. برای مثال:
setAnalyticsCollectionEnabled(true);
این مقادیر پساز تنظیم شدن، در بازراهاندازیهای برنامه حفظ میشوند.
ارسال پیام اعلان
برای اطمینان از اینکه کارخواه Android شما بهدرستی راهاندازی شده است، میتوانید بااستفاده از دستورالعملهای زیر، پیام اعلان آزمایشی ارسال کنید:
برنامه را در دستگاه هدف نصب و اجرا کنید.
مطمئن شوید برنامه در پسزمینه دستگاه باشد.
در کنسول Firebase، به DevOps و تعامل > پیامرسانی بروید
پویشی ایجاد کنید.
اگر این اولین پیام شما است:
ایجاد اولین پویش را انتخاب کنید.
پیامهای اعلان Firebase را انتخاب کنید و سپس ایجاد را انتخاب کنید.
اگر قبلاً پویشهایی ایجاد کردهاید:
در برگه پویشها، پویش جدید را انتخاب کنید.
روی اعلانها کلیک کنید.
نوشتار پیام را وارد کنید. همه فیلدهای دیگر اختیاری هستند.
ارسال پیام آزمایشی را از قاب سمت راست انتخاب کنید.
در فیلد برچسبگذاریشده افزودن کد ثبت FCM، کد ثبت را که در بخش قبلی این راهنما دریافت کردهاید وارد کنید.
آزمایش را انتخاب کنید.
دستگاه کارخواه هدف، با برنامه در پسزمینه، باید اعلان را دریافت کند.
برای دریافت اطلاعات آماری درباره ارسال پیام به برنامهتان، به DevOps و تعامل > پیامرسانی > داشبورد گزارشها در کنسول Firebase بروید. این داشبورد تعداد پیامهای ارسالشده و بازشده در دستگاههای Apple و Android را بههمراه دادههای «ظهورها» (اعلانهایی که کاربران دیدهاند) برای برنامههای Android ثبت میکند.
مراحل بعدی
پساز تکمیل مراحل راهاندازی، در اینجا چند گزینه برای پیشبرد کار با FCM برای Android آورده شده است: