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

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


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

В зависимости от платформы, на которую вы настраиваете таргетинг, вам нужно будет выполнить дополнительные действия.

iOS+

Подмена метода

Чтобы использовать плагин FCM Flutter на устройствах Apple, требуется подмена метода. Без него ключевые функции Firebase, такие как обработка регистрации FCM, не будут работать должным образом.

Android

Сервисы Google Play

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

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

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

Веб-приложение

Настройте учетные данные для сайтов с помощью системы "FCM"

Веб-интерфейс FCM использует учетные данные, которые называются ключами VAPID (Voluntary Application Server Identification), чтобы авторизовать запросы на отправку в поддерживаемые сервисы веб-push-уведомлений. Чтобы подписать приложение на push-уведомления, необходимо связать пару ключей с проектом Firebase. Вы можете сгенерировать новую пару ключей или импортировать существующую через консоль Firebase.

Установите плагин FCM

  1. Если вы ещё этого не сделали, установите и инициализируйте плагины Firebase для Flutter.

  2. Чтобы установить плагин, выполните следующую команду в корневом каталоге проекта Flutter:

    flutter pub add firebase_messaging

  3. После этого пересоберите приложение Flutter:

    flutter run

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

Чтобы отправить уведомление на устройство, зарегистрируйте его в FCM с помощью register(). Если разрешение на уведомления не предоставлено, этот метод запросит его у пользователя. В противном случае он передает FID через onRegistered в случае успеха или отклоняет будущий запрос из-за ошибки.

// You may set the permission requests to "provisional" which allows the user to choose what type
// of notifications they would like to receive once the user receives a notification.
final notificationSettings = await FirebaseMessaging.instance.requestPermission(provisional: true);

// For apple platforms, make sure the APNS token is available before making any FCM plugin API calls
final apnsToken = await FirebaseMessaging.instance.getAPNSToken();
if (apnsToken != null) {
 // APNS token is available, make FCM plugin API requests...
}

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

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

Чтобы включить регистрацию экземпляра приложения в FCM с помощью идентификатора установки Firebase (FID), сначала включите FID в конфигурации приложения для платформ Android и Apple (для веб-платформы статическая конфигурация не требуется):

Android

Добавьте элемент <meta-data> в элемент <application> файла AndroidManifest.xml:

<meta-data android:name="firebase_messaging_installation_id_enabled"
           android:value="true" />

iOS+

Добавьте ключ FirebaseMessagingInstallationIdEnabled в файл Info.plist и задайте для него значение true (YES):

<key>FirebaseMessagingInstallationIdEnabled</key>
<true/>

Подписаться на трансляцию "onRegistered"

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

На платформах Android и Apple FCM автоматически регистрирует экземпляр приложения при запуске, если включена автоинициализация (по умолчанию). Однако требуется явный вызов register():

  • На сайте. Также можно передать объекты vapidKey и serviceWorkerScriptPath.
  • На платформах Android и Apple, если автоматическая инициализация отключена или после вызова unregister(). Вы также можете в любое время вызвать register(), чтобы запустить onRegistered с уже зарегистрированным FID.

Всегда подписывайтесь на onRegistered перед вызовом register(), чтобы прослушиватель был активен при создании события регистрации.

final messaging = FirebaseMessaging.instance;

messaging.onRegistered
    .listen((String installationId) {
      // TODO: Send the Firebase Installation ID (FID) to your application server.
    })
    .onError((err) {
      // Error getting Firebase Installation ID.
    });

// Required on Web, and on Android/Apple if auto-initialization is disabled.
await messaging.register(
  // Optional on Web (ignored on Android and Apple platforms)
  vapidKey: "BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu",
);

Поток onRegistered передает FID в следующих случаях:

  1. Автоматически при первом запуске приложения и обычной синхронизации на платформах Android и Apple, если включена автоматическая инициализация.
  2. Каждый раз, когда завершается вызов register(), выполненный вручную (даже если экземпляр приложения уже зарегистрирован, onRegistered по-прежнему выдает уже зарегистрированный FID).
  3. При каждом изменении идентификатора установки Firebase и повторной регистрации приложения в FCM, а также при активации события pushsubscriptionchange на сайте.

Получив идентификатор установки Firebase (FID), отправьте его на сервер приложения и сохраните удобным для вас способом.

Как получить доступ к токену регистрации (устарело)

Чтобы отправить сообщение на определенное устройство, вам нужно знать его токен регистрации. Чтобы получить токен регистрации для экземпляра приложения, вызовите getToken(). Если разрешение на уведомления не предоставлено, этот метод запросит его у пользователя. В противном случае возвращается токен или отклоняется будущий запрос из-за ошибки.

На веб-платформах передайте открытый ключ VAPID в getToken():

final fcmToken = await FirebaseMessaging.instance.getToken(vapidKey: "BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu");

Чтобы получать уведомления об обновлении токена, подпишитесь на поток onTokenRefresh:

FirebaseMessaging.instance.onTokenRefresh
    .listen((fcmToken) {
      // TODO: If necessary send token to application server.

      // Note: This callback is fired at each app startup and whenever a new
      // token is generated.
    })
    .onError((err) {
      // Error getting token.
    });

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

Когда создается регистрация FCM, библиотека загружает идентификатор и данные конфигурации в Firebase. Если вы хотите предотвратить автоматическую регистрацию, отключите автоматическую инициализацию во время сборки.

Если автоматическая инициализация отключена, вы можете зарегистрировать экземпляр приложения во время выполнения, вызвав register() (сначала подпишитесь на onRegistered, чтобы получить идентификатор установки Firebase):

await FirebaseMessaging.instance.register();

iOS

Если вы используете iOS, добавьте значение метаданных в Info.plist:

FirebaseMessagingAutoInitEnabled = NO

Android

Чтобы отключить сбор данных Аналитики и автоматическую инициализацию FCM на устройстве Android, добавьте в файл 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 во время выполнения

Чтобы включить автоматическую инициализацию для определенного экземпляра приложения, вызовите setAutoInitEnabled():

await FirebaseMessaging.instance.setAutoInitEnabled(true);

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

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

  1. Установите и запустите приложение на целевом устройстве. На устройствах Apple необходимо принять запрос на разрешение получать удаленные уведомления.

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

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

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

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

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

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

    • Если у вас уже есть кампании:

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

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

  5. Введите текст сообщения.

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

  7. В поле Добавьте идентификатор установки Firebase или токен регистрации FCM введите зарегистрированный идентификатор установки Firebase или токен регистрации.

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

После нажатия кнопки Тестировать целевое клиентское устройство, на котором приложение работает в фоновом режиме, должно получить уведомление.

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

Обработка взаимодействия

Когда пользователь нажимает на уведомление, режим работы по умолчанию на Android и iOS — открывать приложение. Если приложение закрыто, оно будет запущено, а если работает в фоновом режиме – переведено в активный.

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

Пакет firebase-messaging предоставляет два способа обработки этого взаимодействия:

  1. getInitialMessage(): Если приложение открывается из закрытого состояния, этот метод возвращает Future, содержащий RemoteMessage. После использования RemoteMessage будет удален.
  2. onMessageOpenedApp – Stream, который публикует RemoteMessage, когда приложение открывается из фонового режима.

Чтобы у пользователей не возникало проблем, необходимо предусмотреть оба сценария. В примере кода ниже показано, как это сделать.

class Application extends StatefulWidget {
  @override
  State createState() => _Application();
}

class _Application extends State {
  // In this example, suppose that all messages contain a data field with the key 'type'.
  Future setupInteractedMessage() async {
    // Get any messages which caused the application to open from
    // a terminated state.
    RemoteMessage? initialMessage =
        await FirebaseMessaging.instance.getInitialMessage();

    // If the message also contains a data property with a "type" of "chat",
    // navigate to a chat screen
    if (initialMessage != null) {
      _handleMessage(initialMessage);
    }

    // Also handle any interaction when the app is in the background using a
    // Stream listener
    FirebaseMessaging.onMessageOpenedApp.listen(_handleMessage);
  }

  void _handleMessage(RemoteMessage message) {
    if (message.data['type'] == 'chat') {
      Navigator.pushNamed(context, '/chat',
        arguments: ChatArguments(message),
      );
    }
  }

  @override
  void initState() {
    super.initState();

    // Run code required to handle interacted messages in an async function
    // as initState() must not be async
    setupInteractedMessage();
  }

  @override
  Widget build(BuildContext context) {
    return Text("...");
  }
}

Способ обработки взаимодействия зависит от ваших настроек. Приведенный выше пример – это базовый пример использования StatefulWidget.

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

После завершения настройки вы можете выполнить следующие действия с FCM для Flutter: