本指南介绍了如何使用 Unity 在您的应用中支持 应用内更新。对于使用 Kotlin 编程语言或 Java 编程语言 的实现情况,以及使用 原生代码 (C/C++) 的实现情况,有单独的指南。
设置您的开发环境
从 Google 的 Unity 软件包 下载最新版本的 Play 应用内更新 Unity 插件。
Unity SDK 概述
应用内更新 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
字段。发布中所有新添加的版本都被视为与该发布具有相同的优先级。优先级只能在推出新版本时设置,以后无法更改。
如 Google Play 开发者 API 文档中所述,使用 Google Play 开发者 API 设置优先级。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
为空。在启动更新流程之前,请确保从GetAppUpdateInfo()
返回的AppUpdateInfo
对象不为空。 - 如果
PlayAsyncOperation
返回错误代码ErrorUpdateUnavailable
,请确保存在具有相同应用程序 ID 和签名密钥的更新应用版本。 - 如果
PlayAsyncOperation
返回错误代码ErrorUpdateNotAllowed
,则表示AppUpdateOptions
对象指示了可用更新不允许的更新类型。在启动更新流程之前,请检查AppUpdateInfo
对象是否指示所选更新类型是允许的。
后续步骤
测试应用的应用内更新 以验证您的集成是否正常工作。