Начните работу с Firebase Cloud Messaging


В этом кратком руководстве описывается, как настроить Firebase Cloud Messaging в мобильных и веб-клиентских приложениях для надежной отправки сообщений. Сведения о серверных средах см. в разделе «Ваша серверная среда» и FCM .

Начало работы с Firebase Cloud Messaging и Android

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

Настройка SDK

Если вы еще этого не сделали, добавьте Firebase в свой Android-проект .

Для оптимальной работы с FCM мы настоятельно рекомендуем включить Google Analytics в вашем проекте. Google Analytics необходим для отчётности о доставке сообщений FCM .

Отредактируйте манифест вашего приложения

Добавьте в манифест вашего приложения следующее:

  • Служба, расширяющая 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+

В Android 13 представлено новое разрешение для отображения уведомлений. Оно касается всех приложений на Android 13 и более поздних версиях, использующих уведомления FCM .

По умолчанию FCM SDK (версии 23.0.6 или выше) включает разрешение 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)
        }
    }
}
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

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

Дополнительные рекомендации о том, когда ваше приложение должно запрашивать у пользователя разрешение 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"/>

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

При первом запуске приложения FCM SDK генерирует регистрационный токен для экземпляра клиентского приложения. Если вы хотите настроить таргетинг на отдельные устройства или создать группы устройств, вам потребуется получить доступ к этому токену, расширив 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)
}
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, должны всегда проверять наличие совместимого APK-файла сервисов Google Play на устройстве перед доступом к функциям сервисов Google Play. Рекомендуется делать это в двух местах: в методе onCreate() основной активности и в методе onResume() . Проверка в onCreate() гарантирует, что приложение не будет запущено без успешной проверки. Проверка в onResume() гарантирует, что если пользователь вернётся в запущенное приложение другими способами, например, нажав кнопку «Назад», проверка всё равно будет выполнена.

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

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

При генерации регистрационного токена 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 

Firebase.messaging.isAutoInitEnabled = true
MainActivity.kt

Java 

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

Чтобы снова включить сбор данных Analytics, вызовите метод setAnalyticsCollectionEnabled() класса FirebaseAnalytics . Например: 

setAnalyticsCollectionEnabled(true);

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

Отправить уведомление

Чтобы убедиться, что ваш Android-клиент настроен правильно, вы можете отправить тестовое уведомление, следуя следующим инструкциям:

  1. Установите и запустите приложение на целевом устройстве.
  2. Убедитесь, что приложение работает в фоновом режиме на устройстве.
  3. В консоли Firebase откройте страницу «Сообщения» .
  4. Если это ваше первое сообщение, выберите Создать первую кампанию , Уведомления Firebase , а затем Создать .
  5. В противном случае на вкладке «Кампании» выберите «Новая кампания» , а затем «Уведомления» .
  6. Введите текст сообщения. Остальные поля необязательны для заполнения.
  7. Выберите Отправить тестовое сообщение на правой панели.
  8. В поле Добавить регистрационный токен FCM введите регистрационный токен, полученный вами в предыдущем разделе данного руководства.
  9. Выберите Тест .

Уведомление должно прийти на целевое клиентское устройство с приложением, работающим в фоновом режиме.

Дополнительную информацию о доставке сообщений в ваше приложение можно найти на панели отчетности FCM , где регистрируется количество отправленных и открытых сообщений на устройствах Apple и Android, а также данные о показах (уведомлениях, которые видят пользователи) для приложений Android.

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

После настройки клиентского приложения вы можете начать получать сообщения или отправлять их своим пользователям: