Поддержка обновлений внутри приложения (Unreal Engine)

В этом руководстве описывается, как поддерживать обновления внутри приложения в вашем приложении с помощью Unreal Engine. Существуют отдельные руководства для случаев, когда ваша реализация использует язык программирования Kotlin или язык программирования Java , а также для случаев, когда ваша реализация использует собственный код (C/C++) или Unity .

Обзор SDK Unreal Engine

API обновлений в приложениях Play является частью семейства Play Core SDK. API для Unreal Engine предлагает класс UInAppUpdatesManager для управления связью между вашим приложением и API Play. После отправки запроса ваше приложение может проверить статус запроса с помощью EAppUpdateErrorCode .

Поддерживаемые версии Unreal Engine

Плагин поддерживает Unreal Engine 5.0 и все последующие версии.

Настройте среду разработки

Настраивать

  1. Загрузите плагин Play Unreal Engine из репозитория GitHub.

  2. Скопируйте папку GooglePlay в папку Plugins вашего проекта Unreal Engine.

  3. Откройте проект Unreal Engine и нажмите «Редактировать» → «Плагины» .

  4. Найдите Google Play и установите флажок «Включено» .

  5. Перезапустите проект игры и запустите сборку.

  6. Откройте файл Build.cs вашего проекта и добавьте модуль PlayInAppUpdates в PublicDependencyModuleNames :

    using UnrealBuildTool;

public class MyGame : ModuleRules
{
  public MyGame(ReadOnlyTargetRules Target) : base(Target)
  {
    // ...

    PublicDependencyModuleNames.Add("PlayInAppUpdates");

    // ...
  }
}

Проверьте наличие обновлений

Прежде чем запрашивать обновление, проверьте, доступно ли обновление для вашего приложения. Используйте UInAppUpdatesManager::RequestInfo для проверки наличия обновлений:

МойКласс.h

void MyClass::OnRequestInfoOperationCompleted(
  EAppUpdateErrorCode ErrorCode,
  UAppUpdateInfo* UpdateInfo)
{
  // Check the resulting error code.
  if (ErrorCode == EAppUpdateErrorCode::AppUpdate_NO_ERROR)
  {
    // Check AppUpdateInfo's UpdateAvailability, UpdatePriority,
    // IsUpdateTypeAllowed(), ... and decide whether to ask the user
    // to start an in-app update.
  }
}

МойКласс.cpp

void MyClass::CheckForUpdateAvailability()
{
  // Create a delegate to bind the callback function.
  FRequestInfoOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnRequestInfoOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnRequestInfoOperationCompleted);

  // Initiate the request info operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->RequestInfo(Delegate);
}

Возвращенный экземпляр UAppUpdateInfo содержит статус доступности обновления. Если обновление в приложении уже выполняется, экземпляр также сообщает о состоянии текущего обновления.

Проверка устаревания обновлений

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

Используйте UAppUpdateInfo:GetClientVersionStalenessDays , чтобы проверить количество дней с момента, когда обновление стало доступно в Play Store:

int32 ClientVersionStalenessDays = UpdateInfo->GetClientVersionStalenessDays();

Проверьте приоритет обновления

API разработчика Google Play позволяет вам устанавливать приоритет каждого обновления. Это позволяет вашему приложению решать, насколько настоятельно рекомендовать обновление пользователю. Например, рассмотрим следующую стратегию установки приоритета обновления:

  • Незначительные улучшения пользовательского интерфейса: Обновление с низким приоритетом ; не запрашивайте ни гибкого обновления, ни немедленного обновления.
  • Улучшения производительности: обновление среднего приоритета ; запросите гибкое обновление.
  • Критическое обновление безопасности: Высокоприоритетное обновление; запросите немедленное обновление.

Для определения приоритета Google Play использует целое число от 0 до 5, где 0 — значение по умолчанию, а 5 — наивысший приоритет. Чтобы установить приоритет обновления, используйте поле inAppUpdatePriority в разделе Edits.tracks.releases в API разработчика Google Play. Все новые версии, добавленные в выпуск, имеют тот же приоритет, что и сам выпуск. Приоритет можно установить только при выпуске новой версии и нельзя изменить позже.

Установите приоритет с помощью Google Play Developer API, как описано в документации Play Developer API . Приоритет обновления внутри приложения должен быть указан в ресурсе Edit.tracks передаваемом в методе Edit.tracks: update . В следующем примере демонстрируется выпуск приложения с кодом версии 88 и inAppUpdatePriority 5:

{
  "releases": [{
      "versionCodes": ["88"],
      "inAppUpdatePriority": 5,
      "status": "completed"
  }]
}

В коде вашего приложения вы можете проверить уровень приоритета для данного обновления, используя UAppUpdateInfo::UpdatePriority :

int32 Priority = UpdateInfo->GetPriority();

Начать обновление

После того, как вы подтвердите, что обновление доступно, вы можете запросить обновление с помощью UInAppUpdatesManager::StartUpdate . Прежде чем запрашивать обновление, убедитесь, что у вас есть актуальный объект UAppUpdateInfo . Также необходимо создать объект UAppUpdateOptions для настройки потока обновлений.

В следующем примере создается объект UAppUpdateOptions для немедленного потока обновления:

// Creates an UAppUpdateOptions defining an immediate in-app
// update flow and its parameters.
UAppUpdateOptions* Options = NewObject<UAppUpdateOptions>();
Options->CreateOptions(EAppUpdateType::AppUpdate_TYPE_IMMEDIATE);

В следующем примере создается объект UAppUpdateOptions для гибкого потока обновлений:

// Creates an UAppUpdateOptions defining a flexible in-app
// update flow and its parameters.
UAppUpdateOptions* Options = NewObject<UAppUpdateOptions>();
Options->CreateOptions(EAppUpdateType::AppUpdate_TYPE_FLEXIBLE);

Объект UAppUpdateOptions также содержит функцию IsAssetPackDeletionAllowed , которая возвращает, разрешено ли обновлению очищать пакеты ресурсов в случае ограниченного объема памяти устройства. По умолчанию для этого поля установлено значение false , но вы можете установить это поле с помощью UAppUpdateOptions::SetAssetPackDeletionAllowed , чтобы вместо этого установить для него значение true :

// Sets the AssetPackDeletionAllowed field to true.
Options->SetAssetPackDeletionAllowed(true);

Следующие шаги зависят от того, запрашиваете ли вы гибкое обновление или немедленное обновление .

Обеспечьте гибкое обновление

После того как у вас есть актуальный объект UAppUpdateInfo и правильно настроенный объект UAppUpdateOptions , вы можете вызвать UInAppUpdatesManager::StartUpdate , чтобы запросить поток обновления.

МойКласс.h 

void MyClass::OnStartUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
  // ...
}

МойКласс.cpp 

// .cpp
void MyClass::StartUpdate()
{
  // Create a delegate to bind the callback function.
  FUpdateOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnStartUpdateOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnStartUpdateOperationCompleted);

  // Initiate the start update operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->StartUpdate(UpdateInfo, UpdateOptions, Delegate);
}

Для обеспечения гибкого процесса обновления необходимо инициировать установку обновления приложения после успешного завершения загрузки. Для этого вызовите InAppUpdatesManager::CompleteUpdate , как показано в следующем примере:

МойКласс.h 

void MyClass::OnCompleteUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
  // ...
}

МойКласс.cpp 

void MyClass::CompleteFlexibleUpdate()
{
  // Create a delegate to bind the callback function.
  FUpdateOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnCompleteUpdateOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnCompleteUpdateOperationCompleted);

  // Initiate the complete update operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->CompleteUpdate(UpdateInfo, UpdateOptions, Delegate);
}

Обработка немедленного обновления

После того как у вас есть актуальный объект UAppUpdateInfo и правильно настроенный объект UAppUpdateOptions , вы можете вызвать InAppUpdatesManager::StartUpdate , чтобы запросить поток обновления.

МойКласс.h 

void MyClass::OnStartUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
  // ...
}

МойКласс.cpp 

void MyClass::StartUpdate()
{
  // Create a delegate to bind the callback function.
  FUpdateOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnStartUpdateOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnStartUpdateOperationCompleted);

  // Initiate the start update operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->StartUpdate(UpdateInfo, UpdateOptions, Delegate);
}

Для немедленного обновления Google Play отображает диалоговое окно подтверждения пользователя. Когда пользователь принимает запрос, Google Play автоматически загружает и устанавливает обновление, а затем перезапускает приложение с использованием обновленной версии, если установка прошла успешно.

Обработка ошибок

В этом разделе описаны решения распространенных ошибок.

  • Если UInAppUpdatesManager::StartUpdate возвращает ошибку AppUpdate_INVALID_REQUEST , это означает, что UAppUpdateInfo недействителен. Перед запуском потока обновления убедитесь, что объект UAppUpdateInfo возвращаемый из UInAppUpdatesManager::RequestInfo не равен нулю.
  • Если UInAppUpdatesManager::StartUpdate возвращает ошибку AppUpdate_NOT_ALLOWED , это означает, что объект UAppUpdateOptions указывает тип обновления, который не разрешен для доступного обновления. Прежде чем запускать поток обновлений, проверьте, указывает ли объект UAppUpdateInfo , что выбранный тип обновления разрешен.

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

Проверьте обновления внутри приложения, чтобы убедиться, что ваша интеграция работает правильно.