Начало работы с Firebase Cloud Messaging в приложениях Unity

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


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

Чтобы написать кросс-платформенное клиентское приложение Firebase Cloud Messaging с помощью Unity, используйте API Firebase Cloud Messaging. Unity SDK работает как на Android, так и на Apple, но для каждой платформы требуется дополнительная настройка.

Подготовка

Требования

  • Установите Unity 2021 LTS или более поздней версии. Более ранние версии также могут быть совместимы, но не будут активно поддерживаться.

  • Только для платформ Apple. Установите следующее:

    • Xcode 26.2 или более поздней версии.
    • CocoaPods 1.12.0 или более поздней версии.

  • Убедитесь, что ваш проект Unity соответствует следующим требованиям:

    • Для iOS – iOS 15 или более поздней версии.
    • Для tvOS – предназначено для tvOS 15 или более поздней версии.
    • Для Android – целевой уровень API 24 (Nougat) или выше.

  • Настройте устройство или используйте эмулятор для запуска проекта Unity.

    • Для iOS или tvOS. Настройте физическое устройство для запуска приложения и выполните следующие задачи:

      • Получите ключ аутентификации службы push-уведомлений Apple для своего аккаунта разработчика Apple.
      • Включите push-уведомления в XCode, выбрав App (Приложение) > Capabilities (Возможности).

    • Для Android. Эмуляторы должны использовать образ эмулятора с Google Play.

Если у вас нет проекта Unity и вы просто хотите попробовать продукт Firebase, скачайте один из наших примеров для быстрого запуска.

Шаг 1. Создайте проект Firebase

Прежде чем добавить Firebase в проект Unity, создайте проект Firebase, который будет связан с проектом Unity. Подробнее о проектах Firebase…

Шаг 2. Зарегистрируйте приложение в Firebase

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

  1. Перейдите в консоль Firebase.

  2. На странице Project Overview (Обзор проекта) нажмите на значок Unity (). Будет запущен мастер настройки.

    Если вы уже добавили приложение в проект Firebase, нажмите Добавить приложение, чтобы посмотреть варианты платформ.

  3. Выберите, какую целевую сборку проекта Unity вы хотите зарегистрировать. Вы также можете зарегистрировать обе сборки одновременно.

  4. Введите идентификаторы проекта Unity для нужных платформ.

    • Для iOS. Введите идентификатор iOS проекта Unity в поле Идентификатор пакета iOS.

    • Для Android — Введите Android ID проекта Unity в поле Название пакета Android.
      Термины название пакета и идентификатор приложения часто используются как взаимозаменяемые.

  5. Необязательно. Введите псевдонимы проекта Unity для разных платформ.
    Эти псевдонимы являются внутренними идентификаторами и видны только вам в консоли Firebase.

  6. Нажмите Register app (Зарегистрировать приложение).

Шаг 3. Добавьте файлы конфигурации Firebase

  1. Получите файлы конфигурации Firebase для нужных платформ в процессе настройки консоли Firebase.

    • Для iOS нажмите Скачать GoogleService-Info.plist.

    • Для Android нажмите Скачать google-services.json.

  2. Откройте окно Project(Проект) в проекте Unity и переместите файлы конфигурации в папку Assets.

  3. Вернитесь в консоль Firebase и в процессе настройки нажмите Next (Далее).

Шаг 4. Добавьте Firebase Unity SDK

  1. В консоли Firebase нажмите Скачать SDK Firebase Unity и распакуйте его в удобном месте.

    • Вы можете в любое время скачать Firebase Unity SDK.

    • SDK Firebase Unity не зависит от платформы.

  2. В открытом проекте Unity выберите Assets (Объекты) > Import Package (Импортировать пакет) > Custom Package (Пользовательский пакет).

  3. Выберите из распакованного SDK поддерживаемые продукты Firebase, которые вы хотите использовать в своем приложении.

    Чтобы использовать все возможности Firebase Cloud Messaging, рекомендуем включить Google Analytics в проекте. Кроме того, при настройке Analytics вам нужно добавить в приложение пакет Firebase для Analytics.

    Analytics: включено

    • Добавьте пакет Firebase для Google Analytics: FirebaseAnalytics.unitypackage
    • Добавьте пакет для Firebase Cloud Messaging: FirebaseMessaging.unitypackage

    Analytics не включено

    Добавьте пакет для Firebase Cloud Messaging: FirebaseMessaging.unitypackage

  4. В окне Import Unity Package нажмите Import.

  5. Вернитесь в консоль Firebase и в процессе настройки нажмите Next (Далее).

Шаг 5. Проверьте версию сервисов Google Play

Для некоторых продуктов в Firebase Unity SDK для Android требуется Google Play services. Узнайте, какие продукты зависят от этого. Чтобы использовать эти продукты, необходимо обновить Google Play services.

Добавьте в начало приложения следующую инструкцию using и код инициализации. Вы можете проверить версию Google Play services и при необходимости обновить ее до требуемой, прежде чем вызывать другие методы в SDK.

using Firebase.Extensions;

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWithOnMainThread(task => {
  var dependencyStatus = task.Result;
  if (dependencyStatus == Firebase.DependencyStatus.Available) {
    // Create and hold a reference to your FirebaseApp,
    // where app is a Firebase.FirebaseApp property of your application class.
       app = Firebase.FirebaseApp.DefaultInstance;

    // Set a flag here to indicate whether Firebase is ready to use by your app.
  } else {
    UnityEngine.Debug.LogError(System.String.Format(
      "Could not resolve all Firebase dependencies: {0}", dependencyStatus));
    // Firebase Unity SDK is not safe to use here.
  }
});

Ваш проект Unity зарегистрирован и настроен для использования Firebase.

Как настроить платформы Apple

Чтобы настроить FCM на платформах Unity и Apple, следуйте инструкциям ниже.

Загрузите ключ аутентификации APNs

Загрузите ключ аутентификации APNs в Firebase. Если у вас ещё нет ключа аутентификации APNs, создайте его в Центре разработчиков Apple.

  1. В консоли Firebase выберите Settings (Настройки) > General (Общие). Затем нажмите на вкладку Обмен сообщениями в облаке.
  2. В разделе Конфигурация приложения для iOS найдите пункт Ключ аутентификации APNs и нажмите Загрузить, чтобы загрузить ключ аутентификации для разработки, ключ аутентификации для рабочей среды или оба ключа. Обязательно заполните как минимум одно из этих полей.
  3. Перейдите к месту, где сохранен ключ, выберите его и нажмите Открыть. Добавьте идентификатор ключа (его можно найти в Центре участников Apple Developer) и нажмите Загрузить.

Как включить push-уведомления на платформах Apple

  1. Нажмите на проект в Xcode и выберите вкладку General (Общие) в разделе Editor area (Область редактора).
  2. Прокрутите страницу до раздела Linked Frameworks and Libraries (Связанные фреймворки и библиотеки) и нажмите кнопку +, чтобы добавить фреймворк.
  3. В открывшемся окне найдите UserNotifications.framework, нажмите на эту запись, а затем выберите Add (Добавить).
  4. Нажмите на проект в Xcode и выберите вкладку Возможности в области редактора.
  5. Включите Push-уведомления.
  6. Прокрутите экран до раздела Фоновые режимы и включите его.
  7. Установите флажок Удаленные уведомления в разделе Фоновые режимы.

Инициализация Firebase Cloud Messaging

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

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

Android

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

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

Swift

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

FirebaseMessagingInstallationIdEnabled = YES

Как зарегистрироваться на мероприятия FCM

Библиотека Firebase Cloud Messaging будет инициализирована при добавлении обработчиков для событий RegistrationReceived или MessageReceived.

При инициализации Firebase Cloud Messaging регистрирует экземпляр клиентского приложения для получения сообщений с помощью идентификатора установки Firebase (FID). Приложение получает FID с событием RegistrationReceived. Вам нужно сохранить его на сервере, чтобы отправлять сообщения на это устройство.

Кроме того, если вы хотите получать входящие сообщения, вам нужно зарегистрироваться на мероприятие OnMessageReceived.

Настройка будет выглядеть следующим образом:

public void Start() {
  Firebase.Messaging.FirebaseMessaging.RegistrationReceived +=
      OnRegistrationReceived;
  Firebase.Messaging.FirebaseMessaging.MessageReceived +=
      OnMessageReceived;
}

public void OnRegistrationReceived(
    object sender,
    Firebase.Messaging.RegistrationReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received Firebase Installation ID: " +
                        e.InstallationId);
  // TODO: Send the Firebase Installation ID (FID) to your app server to target
  // this device for messages.
}

public void OnMessageReceived(
    object sender,
    Firebase.Messaging.MessageReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received a new message from: " + e.Message.From);
}

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

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

Вы также можете вручную запустить регистрацию с помощью FCM во время выполнения, используя RegisterAsync():

// Manually register with FCM
Firebase.Messaging.FirebaseMessaging.RegisterAsync().ContinueWith(task => {
  if (task.IsCompleted) {
    // Note: The registered Installation ID is delivered to the
    // RegistrationReceived event handler.
    UnityEngine.Debug.Log("Registered with FCM");
  }
});

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

Если ваше приложение по-прежнему использует устаревшие API токенов, вы можете прослушивать TokenReceived:

// Deprecated: Use RegistrationReceived instead
public void Start() {
  Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
}

public void OnTokenReceived(
    object sender,
    Firebase.Messaging.TokenReceivedEventArgs token) {
  UnityEngine.Debug.Log("Received Registration Token: " + token.Token);
}

Настройте платформы Android

Ниже приведены инструкции по настройке FCM для Unity и Android.

Настройка Activity точки входа Android

В Firebase Cloud Messaging входит специальная точка входа, которая заменяет стандартную UnityPlayerActivity. Если вы не используете собственную точку входа, замена произойдет автоматически и вам не нужно будет ничего делать.

Плагин Firebase Cloud Messaging Unity для Android поставляется с двумя дополнительными файлами:

  • Assets/Plugins/Android/libmessaging_unity_player_activity.jar содержит действие MessagingUnityPlayerActivity, которое заменяет стандартное действие UnityPlayerActivity.
  • Assets/Plugins/Android/AndroidManifest.xml указывает приложению, что точкой входа в него является MessagingUnityPlayerActivity.

Эти файлы предоставляются, поскольку стандартный UnityPlayerActivity не обрабатывает переходы жизненного цикла объектов activity onStop и onRestart и не реализует onNewIntent, необходимый для корректной обработки входящих сообщений в Firebase Cloud Messaging.

Как настроить действие для собственной точки входа

Если в вашем приложении не используется стандартный класс UnityPlayerActivity, удалите предоставленный класс AndroidManifest.xml и убедитесь, что ваш собственный класс правильно обрабатывает все переходы жизненного цикла объекта activity в Android (пример показан ниже). Если ваше специальное действие расширяет UnityPlayerActivity, вы можете вместо этого расширить com.google.firebase.MessagingUnityPlayerActivity, который реализует все необходимые методы.

Если вы используете собственное действие, а не расширяете com.google.firebase.MessagingUnityPlayerActivity, добавьте в него следующие фрагменты кода.

/**
 * Workaround for when a message is sent containing both a Data and Notification payload.
 *
 * When the app is in the background, if a message with both a data and notification payload is
 * received the data payload is stored on the Intent passed to onNewIntent. By default, that
 * intent does not get set as the Intent that started the app, so when the app comes back online
 * it doesn't see a new FCM message to respond to. As a workaround, we override onNewIntent so
 * that it sends the intent to the MessageForwardingService which forwards the message to the
 * FirebaseMessagingService which in turn sends the message to the application.
 */
@Override
protected void onNewIntent(Intent intent) {
  Intent message = new Intent(this, MessageForwardingService.class);
  message.setAction(MessageForwardingService.ACTION_REMOTE_INTENT);
  message.putExtras(intent);
  message.setData(intent.getData());
  // For earlier versions of Firebase C++ SDK (< 7.1.0), use `startService`.
  // startService(message);
  MessageForwardingService.enqueueWork(this, message);
}

/**
 * Dispose of the mUnityPlayer when restarting the app.
 *
 * This makes sure that when the app starts up again it does not start with stale data.
 */
@Override
protected void onCreate(Bundle savedInstanceState) {
  if (mUnityPlayer != null) {
    mUnityPlayer.quit();
    mUnityPlayer = null;
  }
  super.onCreate(savedInstanceState);
}

В новых версиях Firebase C++ SDK (начиная с 7.1.0) используется JobIntentService, что требует дополнительных изменений в файле AndroidManifest.xml.

<service android:name="com.google.firebase.messaging.MessageForwardingService"
     android:permission="android.permission.BIND_JOB_SERVICE"
     android:exported="false" >
</service>

Доставка сообщений на устройствах Android

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

Если приложение работает в фоновом режиме, то для уведомления в области уведомлений используется контент из поля notification, но этот контент не передается в FCM. Это означает, что значение переменной FirebaseMessage.Notification будет нулевым.

В целом можно выделить следующее.

Состояние приложения Уведомление Данные Оба варианта
В активном режиме Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
Общая информация Область уведомлений Firebase.Messaging.FirebaseMessaging.MessageReceived Уведомление: область уведомлений
Данные: в дополнительных параметрах намерения.

FCM позволяет отправлять сообщения, содержащие ссылку на контент в вашем приложении. Чтобы получать такие сообщения, необходимо добавить новый фильтр интентов в Activity, которое обрабатывает ссылки на контент в вашем приложении. Фильтр интентов должен перехватывать ссылки на контент вашего домена. В файле AndroidManifest.xml:

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="http"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="https"/>
</intent-filter>

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

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="*.example.com" android:scheme="http"/>
  <data android:host="*.example.com" android:scheme="https"/>
</intent-filter>

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

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

FCM генерирует токен регистрации для таргетинга на устройства. При создании токена библиотека загружает идентификатор и данные конфигурации в Firebase. Если вы хотите получить явное согласие пользователя перед использованием токена, вы можете запретить его создание во время настройки, отключив FCM (а на устройствах Android – ещё и Аналитику). Вы можете добавить значение метаданных в Info.plist (не в GoogleService-Info.plist) на Apple или в AndroidManifest.xml на Android:

Android

<?xml version="1.0" encoding="utf-8"?>
<application>
  <meta-data android:name="firebase_messaging_auto_init_enabled"
             android:value="false" />
  <meta-data android:name="firebase_analytics_collection_enabled"
             android:value="false" />
</application>

Swift

FirebaseMessagingAutoInitEnabled = NO

Чтобы снова включить FCM, вызовите метод во время выполнения:

Firebase.Messaging.FirebaseMessaging.RegistrationOnInitEnabled = true;

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

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

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