Начало работы с 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 23 (Marshmallow) или выше.

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

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

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

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

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

  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 и в рабочем процессе настройки нажмите Далее.

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

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

  1. Нажмите на проект в Xcode и выберите вкладку General (Общие) в области редактора.
  2. Прокрутите страницу до раздела Linked Frameworks and Libraries (Связанные фреймворки и библиотеки) и нажмите кнопку +, чтобы добавить фреймворк.
  3. В открывшемся окне прокрутите список до UserNotifications.framework, нажмите на этот элемент и выберите Добавить.
  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, следуйте инструкциям ниже.

Как настроить точку входа в приложение Android

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

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

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

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

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

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

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

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

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 одним из следующих способов: