支持应用内更新 (Unity)

本指南介绍如何在您的应用中使用 Unity 支持 应用内更新。对于您的实现使用 Kotlin 编程语言或 Java 编程语言 的情况，以及您的实现使用 原生代码 (C/C++) 的情况，分别提供了单独的指南。

设置您的开发环境

从 Google 为 Unity 提供的软件包 下载 Play 应用内更新 Unity 插件的最新版本。

Unity SDK 概述

Play 应用内更新 API 是 Play Core SDK 系列的一部分。Unity 插件提供了一个 AppUpdateManager 类来处理您的应用和 Play API 之间的通信。您必须在使用该类管理应用内更新之前实例化该类。

AppUpdateManager appUpdateManager = new AppUpdateManager();

检查更新可用性

在请求更新之前，请检查您的应用是否有可用更新。使用 AppUpdateManager 在 协程 中检查更新。

IEnumerator CheckForUpdate()
{
  PlayAsyncOperation<AppUpdateInfo, AppUpdateErrorCode> appUpdateInfoOperation =
    appUpdateManager.GetAppUpdateInfo();

  // Wait until the asynchronous operation completes.
  yield return appUpdateInfoOperation;

  if (appUpdateInfoOperation.IsSuccessful)
  {
    var appUpdateInfoResult = appUpdateInfoOperation.GetResult();
    // Check AppUpdateInfo's UpdateAvailability, UpdatePriority,
    // IsUpdateTypeAllowed(), etc. and decide whether to ask the user
    // to start an in-app update.
  }
  else
  {
    // Log appUpdateInfoOperation.Error.
  }
}

返回的 AppUpdateInfo 实例包含更新可用性状态。如果应用内更新正在进行，该实例还会报告正在进行的更新的状态。

检查更新陈旧程度

除了检查更新是否可用之外，您可能还想检查自用户上次通过 Play 商店收到更新通知以来经过了多长时间。这可以帮助您决定是否应该启动灵活更新或立即更新。例如，您可以在通知用户灵活更新之前等待几天，然后再要求立即更新几天。

使用 ClientVersionStalenessDays 检查更新在 Play 商店中可用的天数。

var stalenessDays = appUpdateInfoOperation.ClientVersionStalenessDays;

检查更新优先级

Google Play 开发者 API 允许您设置每个更新的优先级。这使您的应用能够决定如何强烈地向用户推荐更新。例如，考虑以下设置更新优先级的策略

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

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

如 Play 开发者 API 文档 中所述，使用 Google Play 开发者 API 设置优先级。应用内更新优先级应在 Edit.tracks 资源中指定，该资源传递到 Edit.tracks: update 方法中。以下示例演示了发布版本代码为 88 且 inAppUpdatePriority 为 5 的应用。

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

在您的应用代码中，您可以使用 UpdatePriority 检查给定更新的优先级级别。

var priority = appUpdateInfoOperation.UpdatePriority;

开始更新

在确保更新可用后，您可以使用 AppUpdateManager.StartUpdate() 请求更新。在请求更新之前，请确保您拥有最新的 AppUpdateInfo 对象。您还必须创建一个 AppUpdateOptions 对象来配置更新流程。

以下示例创建了用于立即更新流程的 AppUpdateOptions 对象。

// Creates an AppUpdateOptions defining an immediate in-app
// update flow and its parameters.
var appUpdateOptions = AppUpdateOptions.ImmediateAppUpdateOptions();

以下示例创建了用于灵活更新流程的 AppUpdateOptions 对象。

// Creates an AppUpdateOptions defining a flexible in-app
// update flow and its parameters.
var appUpdateOptions = AppUpdateOptions.FlexibleAppUpdateOptions();

该 AppUpdateOptions 对象还包含一个 AllowAssetPackDeletion 字段，该字段定义在存储空间有限的情况下，是否允许更新清除 资源包。默认情况下，此字段设置为 false，但您可以将 allowAssetPackDeletion 可选参数传递给 ImmediateAppUpdateOptions() 或 FlexibleAppUpdateOptions()，将其设置为 true。

// Creates an AppUpdateOptions for an immediate flow that allows
// asset pack deletion.
var appUpdateOptions =
  AppUpdateOptions.ImmediateAppUpdateOptions(allowAssetPackDeletion: true);

// Creates an AppUpdateOptions for a flexible flow that allows asset
// pack deletion.
var appUpdateOptions =
  AppUpdateOptions.FlexibleAppUpdateOptions(allowAssetPackDeletion: true);

后续步骤取决于您是请求 灵活更新 还是 立即更新。

处理灵活更新

在拥有最新的 AppUpdateInfo 对象和正确配置的 AppUpdateOptions 对象后，您可以调用 AppUpdateManager.StartUpdate() 来异步请求更新流程。

IEnumerator StartFlexibleUpdate()
{
  // Creates an AppUpdateRequest that can be used to monitor the
  // requested in-app update flow.
  var startUpdateRequest = appUpdateManager.StartUpdate(
    // The result returned by PlayAsyncOperation.GetResult().
    appUpdateInfoResult,
    // The AppUpdateOptions created defining the requested in-app update
    // and its parameters.
    appUpdateOptions);

  while (!startUpdateRequest.IsDone)
  {
  // For flexible flow,the user can continue to use the app while
  // the update downloads in the background. You can implement a
  // progress bar showing the download status during this time.
  yield return null;
  }

}

对于灵活更新流程，您必须在下载成功完成之后触发应用更新的安装。为此，请调用 AppUpdateManager.CompleteUpdate()，如以下示例所示

IEnumerator CompleteFlexibleUpdate()
{
  var result = appUpdateManager.CompleteUpdate();
  yield return result;

  // If the update completes successfully, then the app restarts and this line
  // is never reached. If this line is reached, then handle the failure (e.g. by
  // logging result.Error or by displaying a message to the user).
}

处理立即更新

在拥有最新的 AppUpdateInfo 对象和正确配置的 AppUpdateOptions 对象后，您可以调用 AppUpdateManager.StartUpdate() 来异步请求更新流程。

IEnumerator StartImmediateUpdate()
{
  // Creates an AppUpdateRequest that can be used to monitor the
  // requested in-app update flow.
  var startUpdateRequest = appUpdateManager.StartUpdate(
    // The result returned by PlayAsyncOperation.GetResult().
    appUpdateInfoResult,
    // The AppUpdateOptions created defining the requested in-app update
    // and its parameters.
    appUpdateOptions);
  yield return startUpdateRequest;

  // If the update completes successfully, then the app restarts and this line
  // is never reached. If this line is reached, then handle the failure (for
  // example, by logging result.Error or by displaying a message to the user).
}

对于立即更新流程，Google Play 会显示一个用户确认对话框。当用户接受请求后，Google Play 会自动下载并安装更新，然后在安装成功后将应用重新启动到更新后的版本。

错误处理

本节介绍常见错误的解决方案。

• 如果 StartUpdate() 抛出 ArgumentNullException，则表示 AppUpdateInfo 为 null。请确保在启动更新流程之前，从 GetAppUpdateInfo() 返回的 AppUpdateInfo 对象不为 null。
• 如果 PlayAsyncOperation 返回 ErrorUpdateUnavailable 错误代码，请确保有更新的应用版本可用，该版本具有相同的应用程序 ID 和签名密钥。
• 如果 PlayAsyncOperation 返回 ErrorUpdateNotAllowed 错误代码，则表示 AppUpdateOptions 对象指示的更新类型对于可用更新不可用。在启动更新流程之前，请检查 AppUpdateInfo 对象是否指示所选更新类型是允许的。

后续步骤

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