Как начать работу с Firebase Cloud Messaging в приложениях Android

Выберите платформу: iOS+ Android Веб Flutter Unity C++


В этом руководстве рассказывается, как начать работу с Firebase Cloud Messaging в клиентских приложениях Android, чтобы надежно отправлять сообщения.

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

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

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

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 (уровень API 32) или более ранних версий

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

  • Если приложение создает первый канал уведомлений, когда оно работает в фоновом режиме (а именно так поступает SDK FCM при получении уведомления FCM), Android не разрешит показ уведомления и не запросит у пользователя разрешение на уведомления до следующего запуска приложения. Это означает, что все уведомления, полученные до того, как пользователь откроет приложение и предоставит разрешение, будут потеряны.
  • Мы настоятельно рекомендуем обновить приложение, чтобы оно поддерживало Android 13 и более поздние версии. Это позволит вам использовать API платформы для запроса разрешений. Если это невозможно, ваше приложение должно создавать каналы уведомлений до отправки любых уведомлений, чтобы вызвать диалоговое окно запроса разрешения на уведомления и убедиться, что уведомления не будут потеряны. Подробнее о запросах разрешений на отправку уведомлений…

Как удалить разрешение POST_NOTIFICATIONS (необязательно)

По умолчанию SDK FCM включает разрешение POST_NOTIFICATIONS. Если ваше приложение не использует уведомления (ни через FCMnotifications, ни через другой SDK, ни напрямую), и вы не хотите, чтобы в нем было это разрешение, вы можете удалить его с помощью маркера объединения манифестов remove. Обратите внимание, что после отмены этого разрешения вы не будете получать никаких уведомлений, а не только уведомлений от FCM. Добавьте в файл манифеста приложения следующее:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" tools:node="remove"/>

Как получить доступ к идентификатору установки Firebase

При первом запуске приложения SDK FCM регистрирует экземпляр приложения в FCM и возвращает идентификатор экземпляра приложения. Если вы хотите настроить таргетинг на отдельные экземпляры приложений, вам нужно получить доступ к этому идентификатору, расширив FirebaseMessagingService и переопределив onRegistered(). Рекомендуем получать последний обновленный идентификатор, поскольку он может меняться после первого запуска.

Как включить регистрацию с помощью идентификатора установки Firebase

Чтобы разрешить регистрацию экземпляра приложения в FCM с помощью идентификатора установки Firebase (FID), добавьте в файл AndroidManifest.xml следующий флаг метаданных: 
<meta-data
    android:name="firebase_messaging_installation_id_enabled"
    android:value="true" />

Как реализовать обратный вызов onRegistered()

На экземпляры приложений настраивается таргетинг с помощью идентификатора установки Firebase (FID) после регистрации в FCM. Чтобы получить FID при регистрации, реализуйте обратный вызов onRegistered(). После регистрации экземпляра приложения SDK FCM автоматически отслеживает изменения FID и вызывает обратный вызов при обнаружении изменений. Если автоинициализация включена, SDK FCM автоматически синхронизируется с серверной частью FCM, чтобы поддерживать актуальность регистрации, и вызывает функцию обратного вызова, чтобы ваш сервер приложений получил текущий идентификатор. Чтобы избежать потери или устаревания идентификатора установки, отправляйте его на сервер приложения при каждом срабатывании этого обратного вызова.

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

Java

  /**
   * 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);
  }

Как зарегистрироваться вручную, если автоинициализация отключена

Если вам нужно отключить автоматическую инициализацию, SDK 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.
      }

Java

  // 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 (поддержка прекращена)

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

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

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

Когда генерируется 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, выполните вызов во время выполнения:

Kotlin

Firebase.messaging.isAutoInitEnabled = true

Java

FirebaseMessaging.getInstance().setAutoInitEnabled(true);

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

setAnalyticsCollectionEnabled(true);

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

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

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

  1. Установите и запустите приложение на целевом устройстве.

  2. Убедитесь, что приложение работает в фоновом режиме.

  3. В консоли Firebase выберите DevOps & Engagement (DevOps и взаимодействие) > Messaging (Обмен сообщениями).

  4. Создайте кампанию.

    • Если это ваше первое сообщение:

      1. Выберите Создать первую кампанию.

      2. Выберите Уведомления Firebase и нажмите Создать.

    • Если вы уже создавали кампании:

      1. На вкладке Кампании нажмите Новая кампания.

      2. Нажмите Уведомления.

  5. Введите текст сообщения. Остальные поля необязательны.

  6. На панели справа выберите Отправить тестовое сообщение.

  7. В поле Добавить токен регистрации FCM введите токен регистрации, полученный в предыдущем разделе этого руководства.

  8. Нажмите Проверить.

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

Чтобы узнать, как сообщения доставляются в ваше приложение, откройте раздел DevOps и вовлеченность > Обмен сообщениями > Отчеты на панели управления Firebase. На этой панели управления регистрируется количество сообщений, отправленных и открытых на устройствах Apple и Android, а также данные о показах (уведомлениях, которые видели пользователи) для приложений Android.

Дальнейшие действия

После того как вы выполните все шаги по настройке, вы можете: FCM