این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

یک برنامه مشتری 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 درخواست کند. تا زمانی که کاربر این مجوز را اعطا نکند، برنامه شما مجاز به نمایش اعلان‌ها نخواهد بود.

برای درخواست مجوز اجرای جدید:

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

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

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

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

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

خدمات 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، یک تماس در زمان اجرا برقرار کنید:

Java

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

Kotlin+KTX

Firebase.messaging.isAutoInitEnabled = trueMainActivity.kt

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

setAnalyticsCollectionEnabled(true);

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

مراحل بعدی

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

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

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

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

SDK را تنظیم کنید

مانیفست برنامه خود را ویرایش کنید

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

Java

Kotlin+KTX

مجوزهای اعلان برای برنامه‌هایی که Android 12L (سطح API 32) یا پایین‌تر را هدف قرار می‌دهند

اختیاری: حذف مجوز POST_NOTIFICATIONS

به رمز ثبت دستگاه دسترسی پیدا کنید

رمز ثبت نام فعلی را بازیابی کنید

Java

Kotlin+KTX

نظارت بر تولید توکن

Java

Kotlin+KTX

خدمات Google Play را بررسی کنید

جلوگیری از مقداردهی اولیه خودکار

Java

Kotlin+KTX

مراحل بعدی

اختیاری: حذف مجوز `POST_NOTIFICATIONS`