Catch up on highlights from Firebase at Google I/O 2023. Learn more

یک برنامه مشتری Firebase Cloud Messaging در Android راه اندازی کنید

کلاینت‌های 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>
    AndroidManifest.xml
  • (اختیاری) در مولفه برنامه، عناصر فراداده برای تنظیم نماد و رنگ اعلان پیش‌فرض. هر زمان که پیام‌های دریافتی نماد یا رنگ را مشخص نکرده باشند، Android از این مقادیر استفاده می‌کند.
    • <!-- 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" />
    AndroidManifest.xml
  • (اختیاری) از Android 8.0 (سطح API 26) و بالاتر، کانال‌های اعلان پشتیبانی و توصیه می‌شوند. FCM یک کانال اعلان پیش فرض را با تنظیمات اولیه ارائه می دهد. اگر ترجیح می‌دهید کانال پیش‌فرض خود را ایجاد کرده و از آن استفاده کنید، default_notification_channel_id مطابق شکل روی شناسه شی کانال اطلاع‌رسانی خود تنظیم کنید. هر زمان که پیام‌های دریافتی کانال اعلان تنظیم نکرده باشند، FCM از این مقدار استفاده می‌کند. برای کسب اطلاعات بیشتر، به مدیریت کانال‌های اعلان مراجعه کنید.
    • <meta-data
    android:name="com.google.firebase.messaging.default_notification_channel_id"
    android:value="@string/default_notification_channel_id" />
    AndroidManifest.xml

درخواست مجوز اعلان زمان اجرا در Android 13+

اندروید 13 مجوز زمان اجرا جدیدی را برای نمایش اعلان ها معرفی می کند. این روی همه برنامه‌هایی که در Android نسخه 13 یا بالاتر اجرا می‌شوند و از اعلان‌های FCM استفاده می‌کنند، تأثیر می‌گذارد.

به طور پیش فرض، FCM SDK (نسخه 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)
        }
    }
}
MainActivity.kt

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);
        }
    }
}
MainActivity.java

به طور کلی، شما باید یک رابط کاربری نمایش دهید که ویژگی هایی را که کاربر در صورت اعطای مجوز به برنامه برای ارسال اعلان ها فعال می شود، توضیح دهد. این رابط کاربری باید گزینه‌های موافقت یا رد را برای کاربر فراهم کند، مانند دکمه‌های 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() را فراخوانی کنید:

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)
}
MyFirebaseMessagingService.kt

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);
}
MyFirebaseMessagingService.java

پس از دریافت رمز، می توانید آن را به سرور برنامه خود ارسال کرده و با استفاده از روش دلخواه خود، آن را ذخیره کنید.

خدمات 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" />
AndroidManifest.xml

برای فعال کردن مجدد راه اندازی خودکار FCM، یک تماس در زمان اجرا برقرار کنید:

Kotlin+KTX

Firebase.messaging.isAutoInitEnabled = true
MainActivity.kt

Java

FirebaseMessaging.getInstance().setAutoInitEnabled(true);
MainActivity.java

برای فعال کردن مجدد مجموعه Analytics، متد setAnalyticsCollectionEnabled() از کلاس FirebaseAnalytics را فراخوانی کنید. مثلا:

setAnalyticsCollectionEnabled(true);

پس از تنظیم، این مقادیر در سراسر راه اندازی مجدد برنامه باقی می مانند.

مراحل بعدی

پس از راه‌اندازی برنامه سرویس گیرنده، آماده ارسال پیام‌های پایین‌دستی با سازنده Notifications هستید. این عملکرد در نمونه شروع سریع نشان داده شده است، که می توانید آن را دانلود، اجرا و مرور کنید.

برای افزودن سایر رفتارهای پیشرفته تر به برنامه خود، می توانید یک فیلتر قصد اعلام کنید و یک فعالیت برای پاسخ به پیام های دریافتی اجرا کنید. برای جزئیات، به راهنمای ارسال پیام از سرور برنامه مراجعه کنید:

به خاطر داشته باشید که برای استفاده از این ویژگی‌ها، به اجرای سرور و پروتکل‌های سرور (HTTP یا XMPP) یا پیاده‌سازی Admin SDK نیاز دارید.