支持应用内更新 (Unreal Engine)

本指南介绍了如何使用 Unreal Engine 在您的应用中支持应用内更新。另有针对使用Kotlin 编程语言或 Java 编程语言实现，以及使用原生代码 (C/C++) 或Unity 实现的独立指南。

Unreal Engine SDK 概览

Play 应用内更新 API 属于 Play Core SDK 系列。Unreal Engine 的 API 提供了一个 UInAppUpdatesManager 类来处理您的应用与 Play API 之间的通信。发出请求后，您的应用可以使用 EAppUpdateErrorCode 检查请求的状态。

支持的 Unreal Engine 版本

该插件支持 Unreal Engine 5.0 及所有后续版本。

设置您的开发环境

  1. 从 GitHub 仓库下载 Play Unreal Engine 插件。

  2. 将 GooglePlay 文件夹复制到您的 Unreal Engine 项目中的 Plugins 文件夹内。

  3. 打开您的 Unreal Engine 项目，然后点击 Edit → Plugins。

  4. 搜索 Google Play 并勾选 Enabled 复选框。

  5. 重启游戏项目并触发构建。

  6. 打开您项目的 Build.cs 文件，并将 PlayInAppUpdates 模块添加到 PublicDependencyModuleNames 中。

    using UnrealBuildTool;

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

    PublicDependencyModuleNames.Add("PlayInAppUpdates");

    // ...
  }
}

检查更新可用性

在请求更新之前，请检查您的应用是否有可用更新。使用 UInAppUpdatesManager::RequestInfo 检查更新。

MyClass.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.
  }
}

MyClass.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 商店通知用户更新以来已经过了多长时间。这可以帮助您决定是否应发起弹性更新或立即更新。例如，您可能要等待几天才通过弹性更新通知用户，然后在此之后再过几天才要求立即更新。

使用 UAppUpdateInfo:GetClientVersionStalenessDays 检查自更新通过 Play 商店发布以来的天数。

int32 ClientVersionStalenessDays = UpdateInfo->GetClientVersionStalenessDays();

检查更新优先级

Google Play 开发者 API 允许您设置每次更新的优先级。这让您的应用可以决定向用户强烈推荐更新的程度。例如，考虑以下设置更新优先级的策略：

  • 次要 UI 改进：低优先级更新；不请求弹性更新，也不请求立即更新。
  • 性能改进：中优先级更新；请求弹性更新。
  • 关键安全更新：高优先级更新；请求立即更新。

为了确定优先级，Google Play 使用 0 到 5 之间的整数值，其中 0 是默认值，5 是最高优先级。要设置更新的优先级，请使用 Google Play 开发者 API 中 Edits.tracks.releases 下的 inAppUpdatePriority 字段。发布中所有新添加的版本都与发布具有相同的优先级。优先级只能在发布新版本时设置，之后无法更改。

按照 Play 开发者 API 文档中所述，使用 Google Play 开发者 API 设置优先级。应用内更新优先级应在 Edit.tracks: update 方法中传递的 Edit.tracks 资源中指定。以下示例演示了发布版本代码为 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 来请求更新流程。

MyClass.h

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

MyClass.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，如以下示例所示：

MyClass.h

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

MyClass.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 来请求更新流程。

MyClass.h

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

MyClass.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 无效。在开始更新流程之前，请确保从 UInAppUpdatesManager::RequestInfo 返回的 UAppUpdateInfo 对象不为空。
  • 如果 UInAppUpdatesManager::StartUpdate 返回 AppUpdate_NOT_ALLOWED 错误，这意味着 UAppUpdateOptions 对象指示的更新类型不允许进行可用更新。在开始更新流程之前，请检查 UAppUpdateInfo 对象是否指示所选更新类型是允许的。

后续步骤

测试您应用的应用内更新以验证您的集成是否正常工作。