Join us in person and online for Firebase Summit on October 18, 2022. Learn how Firebase can help you accelerate app development, release your app with confidence, and scale with ease. Register now

Настройте клиентское приложение Firebase Cloud Messaging на Android

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Клиентам FCM требуются устройства под управлением Android 4.4 или более поздней версии, на которых также установлено приложение Google Play Store, или эмулятор под управлением Android 4.4 с API Google. Обратите внимание, что вы не ограничены развертыванием приложений для Android через Google Play Store.

Настройте 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>
  • (Необязательно) В компоненте приложения элементы метаданных для установки значка и цвета уведомления по умолчанию. 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" />
  • (Необязательно) Начиная с 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" />

Запросить разрешение на уведомление во время выполнения на Android 13+

Android 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() {
    // 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);
        }
    }
}

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)
        }
    }
}

Как правило, вы должны отображать пользовательский интерфейс, объясняющий пользователю функции, которые будут включены, если они предоставят приложению разрешения на публикацию уведомлений. Этот пользовательский интерфейс должен предоставлять пользователю возможность согласиться или отклонить, например кнопки « ОК » и «Нет, спасибо ». Если пользователь выбирает OK , запросите разрешение напрямую. Если пользователь выбирает « Нет, спасибо », разрешить пользователю продолжить работу без уведомлений.

Дополнительные сведения о том, когда ваше приложение должно запрашивать разрешение POST_NOTIFICATIONS у пользователя, см. в POST_NOTIFICATIONS Разрешение на выполнение уведомлений.

Разрешения на уведомления для приложений, ориентированных на Android 12L (уровень API 32) или ниже

Android автоматически запрашивает у пользователя разрешение при первом создании канала уведомлений вашим приложением, пока приложение находится на переднем плане. Однако есть важные предостережения относительно времени создания канала и запросов на разрешение:

  • Если ваше приложение создает свой первый канал уведомлений, когда оно работает в фоновом режиме (что делает 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"/>

Доступ к токену регистрации устройства

При первоначальном запуске приложения пакет SDK FCM создает маркер регистрации для экземпляра клиентского приложения. Если вы хотите настроить таргетинг на отдельные устройства или создать группы устройств, вам потребуется получить доступ к этому токену, расширив 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

Приложения, использующие SDK Play Services, всегда должны проверять устройство на наличие совместимого APK сервисов Google Play перед доступом к функциям сервисов Google Play. Это рекомендуется делать в двух местах: в onCreate() основного действия и в его onResume() . Проверка в onCreate() гарантирует, что приложение нельзя будет использовать без успешной проверки. Проверка в onResume() гарантирует, что если пользователь вернется к работающему приложению каким-либо другим способом, например, с помощью кнопки «Назад», проверка все равно будет выполнена.

Если на устройстве нет совместимой версии сервисов Google Play, ваше приложение может вызвать GoogleApiAvailability.makeGooglePlayServicesAvailable() , чтобы разрешить пользователям загружать сервисы Google Play из Play Store.

Запретить автоматическую инициализацию

Когда генерируется токен регистрации FCM, библиотека загружает идентификатор и данные конфигурации в Firebase. Если вы предпочитаете предотвратить автогенерацию токенов, отключите сбор аналитики и автоматическую инициализацию 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);

Эти значения сохраняются при перезапуске приложения после их установки.

Следующие шаги

После настройки клиентского приложения вы готовы начать отправку нисходящих сообщений с помощью компоновщика уведомлений . Эта функциональность демонстрируется в образце быстрого запуска, который вы можете загрузить, запустить и просмотреть.

Чтобы добавить другое, более сложное поведение в ваше приложение, вы можете объявить фильтр намерений и реализовать действие для ответа на входящие сообщения. Подробнее см. в руководствах по отправке сообщений с сервера приложений:

Имейте в виду, что для использования этих функций вам потребуется реализация сервера и серверные протоколы (HTTP или XMPP) или реализация Admin SDK .