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

Чтобы написать кроссплатформенное клиентское приложение Firebase Cloud Messaging с помощью Unity, используйте API Firebase Cloud Messaging . Unity SDK работает как для 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 — настройте физическое устройство для запуска приложения и выполните следующие задачи:

      • Получите ключ аутентификации Apple Push Notification для своей учетной записи Apple Developer .
      • Включите push-уведомления в XCode в разделе «Приложение» > «Возможности» .

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

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

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

Прежде чем вы сможете добавить Firebase в свой проект Unity, вам необходимо создать проект Firebase для подключения к вашему проекту Unity. Посетите раздел «Понимание проектов 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. Добавьте SDK Firebase Unity

  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 , которые должны быть обновлены, прежде чем SDK можно будет использовать.

Добавьте следующий оператор using и код инициализации в начале вашего приложения. Вы можете проверить и при необходимости обновить Google Play services до версии, требуемой Firebase Unity SDK, прежде чем вызывать любые другие методы в 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.

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

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

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

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

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

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

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

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

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

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

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

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

  2. Установите для параметра Push-уведомления значение « Вкл .».

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

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

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

Библиотека сообщений Firebase Cloud будет инициализирована при добавлении обработчиков событий 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

В Android Firebase Cloud Messaging поставляется в комплекте с пользовательской точкой входа, которая заменяет UnityPlayerActivity по умолчанию. Если вы не используете пользовательскую точку входа, эта замена происходит автоматически, и вам не нужно предпринимать никаких дополнительных действий. Приложениям, которые не используют точку входа по умолчанию или предоставляют свои собственные 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 .

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

Если ваше приложение не использует 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 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="false" >
</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 позволяет отправлять сообщения, содержащие глубокую ссылку на ваше приложение. Чтобы получать сообщения, содержащие глубокие ссылки, необходимо добавить новый фильтр намерений в действие, которое обрабатывает глубокие ссылки для вашего приложения. Фильтр намерений должен улавливать глубокие ссылки вашего домена. Если ваши сообщения не содержат глубокой ссылки, эта настройка не требуется. В 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. Чтобы узнать больше, ознакомьтесь с примером быстрого запуска , демонстрирующим эту функциональность.

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

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