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

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

Прежде чем вы начнете

Предпосылки

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

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

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

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

    • Для iOS — ориентируется на iOS 11 или выше.
    • Для tvOS — предназначен для tvOS 12 или выше.
    • Для Android — уровень API 19 (KitKat) или выше.

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

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

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

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

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

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

Прежде чем вы сможете добавить Firebase в свой проект Unity, вам необходимо создать проект Firebase для подключения к вашему проекту Unity. Посетите страницу Understand Firebase Projects , чтобы узнать больше о проектах 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. Откройте окно Project вашего проекта Unity, затем переместите файлы конфигурации в папку Assets .

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

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

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

    • Вы можете снова загрузить Firebase Unity SDK в любое время.

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

  2. В открытом проекте Unity перейдите к Assets > Import Package > Custom Package .

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

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

    Аналитика включена

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

    Аналитика не включена

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

  4. В окне «Импорт пакета Unity» нажмите «Импорт» .

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

Шаг 5. Подтвердите требования к версии сервисов Google Play.

Для Firebase Unity SDK для Android требуются сервисы Google Play , которые должны быть обновлены, прежде чем можно будет использовать SDK.

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

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(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.

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

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

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

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

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

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

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

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

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

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

Инициализировать облачный обмен сообщениями Firebase

Библиотека 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 поставляется в комплекте с пользовательской точкой входа, которая заменяет 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 для правильной обработки входящих сообщений.

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

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

В итоге:

Состояние приложения Уведомление Данные Оба
Передний план 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. Чтобы узнать больше, см. пример быстрого запуска , демонстрирующий эту функциональность.

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

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