Настройка клиентского приложения Firebase Cloud Messaging с помощью Unity

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

Прежде чем начать

Предпосылки

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

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

    • Xcode 13.3.1 или выше
    • CocoaPods 1.12.0 или выше

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

    • Для iOS — предназначено для iOS 13 и выше.
    • Для tvOS — предназначено для tvOS 13 и выше
    • Для Android — ориентирован на API уровня 21 (Lollipop) или выше

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

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

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

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

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

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

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

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

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

  2. В центре страницы обзора проекта щелкните значок Unity ( ), чтобы запустить рабочий процесс настройки.

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

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

  4. Введите идентификатор(ы) платформы вашего проекта Unity.

    • Для iOS — введите идентификатор iOS вашего проекта Unity в поле идентификатора пакета iOS .

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

  5. (Необязательно) Введите псевдонимы, специфичные для платформы вашего проекта Unity.
    Эти псевдонимы являются внутренними, удобными идентификаторами и видны только вам в консоли Firebase .

  6. Нажмите «Зарегистрировать приложение» .

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

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

    • Для iOS — нажмите «Загрузить GoogleService-Info.plist» .

    • Для Android — нажмите «Загрузить google-services.json» .

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

  3. Вернитесь в консоль Firebase , в рабочем процессе настройки нажмите кнопку Далее .

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

  1. В консоли Firebase нажмите «Загрузить Firebase Unity SDK» , затем распакуйте SDK в удобное место.

    • Вы можете снова загрузить 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. В окне Импорт пакета Unity нажмите Импорт .

  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.

Загрузите свой ключ аутентификации APNs для поддержки Apple

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

  1. Внутри вашего проекта в консоли Firebase выберите значок шестеренки, выберите Настройки проекта , а затем выберите вкладку Облачные сообщения .

  2. В разделе «Ключ аутентификации APNs» в настройках приложения iOS нажмите кнопку «Загрузить» .

  3. Перейдите к месту сохранения ключа, выберите его и нажмите «Открыть» . Добавьте идентификатор ключа (доступен в Центре разработчиков Apple ) и нажмите «Загрузить» .

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

Шаг 1: Добавьте структуру уведомлений пользователей

  1. Щелкните по проекту в Xcode, затем выберите вкладку «Общие» в области «Редактор» .

  2. Прокрутите вниз до раздела Связанные фреймворки и библиотеки , затем нажмите кнопку + , чтобы добавить фреймворк.

  3. В появившемся окне прокрутите до UserNotifications.framework , щелкните эту запись, затем щелкните Добавить .

Шаг 2: Включите push-уведомления

  1. Щелкните по проекту в Xcode, затем выберите вкладку Возможности в области Редактора .

  2. Включите функцию Push-уведомлений .

  3. Прокрутите вниз до раздела Фоновые режимы , затем переключите его в положение Вкл .

  4. Установите флажок Удаленные уведомления в разделе Фоновые режимы .

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

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

При инициализации для экземпляра клиентского приложения запрашивается регистрационный токен. Приложение получит токен вместе с событием OnTokenReceived , которое следует кэшировать для дальнейшего использования. Этот токен понадобится вам, если вы хотите отправлять сообщения именно на это устройство.

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

Вся установка выглядит так:

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

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

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

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

На Android Firebase Cloud Messaging поставляется с пользовательской точкой входа Activity, которая заменяет стандартную UnityPlayerActivity . Если вы не используете пользовательскую точку входа, эта замена происходит автоматически, и вам не нужно предпринимать никаких дополнительных действий. Приложения, не использующие стандартную точку входа Activity или предоставляющие собственный Assets/Plugins/AndroidManifest.xml потребуют дополнительной настройки.

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

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

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

Настройка пользовательской точки входа Activity

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

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

/**
 * 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 older 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 ensures 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="true" >
</service>

Примечание о доставке сообщений на Android

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

Сообщения, полученные во время работы приложения в фоновом режиме, содержат содержимое поля уведомления, используемое для заполнения уведомления в системном трее, но это содержимое не будет передано в FCM . То есть, FirebaseMessage.Notification будет иметь значение null.

В итоге:

Состояние приложения Уведомление Данные Оба
Передний план Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
Фон Системный лоток Firebase.Messaging.FirebaseMessaging.MessageReceived Уведомление: системный трей
Данные: в дополнениях к намерению.

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

FCM генерирует регистрационный токен для таргетинга устройств. При генерации токена библиотека загружает идентификатор и данные конфигурации в Firebase. Если вы хотите получить явное согласие перед использованием токена, вы можете запретить генерацию токена во время настройки, отключив FCM (а на Android — Analytics). Для этого добавьте значение метаданных в файл Info.plist (а не GoogleService-Info.plist ) на Apple или в файл AndroidManifest.xml на 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>

Быстрый 

FirebaseMessagingAutoInitEnabled = NO

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

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

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

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>

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

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

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

Чтобы добавить в свое приложение другое, более продвинутое поведение, ознакомьтесь с руководствами по отправке сообщений с сервера приложений:

Имейте в виду, что для использования этих функций вам понадобится реализация сервера .