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

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


В этом руководстве описано, как начать работу с 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 15 и выше.
    • Для tvOS — целевая платформа: tvOS 15 и выше.
    • Для Android — ориентирован на API уровня 23 (Marshmallow) или выше.

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

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

    • Для 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 bundle ID» .

    • Для 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 .

    • 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. В окне «Импорт пакета 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.

Настройка работы с платформами Apple

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

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

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

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

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

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

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

  1. В Xcode щелкните по своему проекту, затем выберите вкладку «Общие» в области редактора .
  2. Прокрутите страницу до раздела «Связанные фреймворки и библиотеки» , затем нажмите кнопку «+» , чтобы добавить фреймворк.
  3. В появившемся окне прокрутите до раздела UserNotifications.framework , щелкните по этой записи, а затем нажмите «Добавить» .
  4. В Xcode щелкните по своему проекту, затем выберите вкладку «Возможности» в области редактора .
  5. Включите push-уведомления .
  6. Прокрутите до пункта «Режимы фона» , затем переключите его в положение «Вкл.» .
  7. Установите флажок «Удаленные уведомления» в разделе «Фоновые режимы» .

Инициализация 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

Для настройки FCM на платформах Unity и Android воспользуйтесь приведенными ниже инструкциями.

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

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

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

В итоге:

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

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>

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

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

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

Быстрый 

FirebaseMessagingAutoInitEnabled = NO

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

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

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

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

После завершения этапов настройки, вот несколько вариантов для дальнейшей работы с FCM для Unity: