Play Asset Delivery Unity API 集成
该 「Play Asset Delivery Unity API」 提供了请求资产包,下载管理,和访问资源的功能。「确保」首先将 Unity 插件添加到你的项目中。
你在 API 中使用的函数取决于你创建资产包的方式。
- 如果你使用 UI 配置 AssetBundles,请「选择插件配置的资产包」。
- 如果你使用 API 配置资产包,请选「择API 配置的资产包」。
你可以根据要访问的资产包的交付类型实施 API。这些步骤显示在以下流程图中。
检索 AssetBundles
导入 Play Asset Delivery API 并调用该 RetrieveAssetBundleAsync()方法来检索 AssetBundle。
using Google.Play.AssetDelivery; // Loads the AssetBundle from disk, downloading the asset pack containing it if necessary. PlayAssetBundleRequest bundleRequest = PlayAssetDelivery.RetrieveAssetBundleAsync(asset-bundle-name);
安装时交货
资产包配置为「install-time」在应用程序启动时立即可用。你可以使用以下命令从 AssetBundle 加载场景:
1.AssetBundle assetBundle = bundleRequest.AssetBundle; // You may choose to load scenes from the AssetBundle. For example: string[] scenePaths = assetBundle.GetAllScenePaths(); SceneManager.LoadScene(scenePaths[path-index]);
快速跟进和按需交付
这些部分适用于「fast-follow」和「on-demand」资产包。
检查状态
每个资产包都存储在应用程序内部存储的单独文件夹中。使用该 「isDownloaded()」 方法确定是否已下载资产包。
监控下载
查询PlayAssetBundleRequest 监控请求状态的 对象:
// Download progress of request, between 0.0f and 1.0f. The value will always be // 1.0 for assets delivered as install-time. // NOTE: A value of 1.0 will only signify the download is complete. It will still need to be loaded. float progress = bundleRequest.DownloadProgress; // Returns true if: // * it had either completed the download, installing, and loading of the AssetBundle, // * OR if it has encountered an error. bool done = bundleRequest.IsDone; // Returns status of retrieval request. AssetDeliveryStatus status = bundleRequest.Status; switch(status) { case AssetDeliveryStatus.Pending: // Asset pack download is pending - N/A for install-time assets. case AssetDeliveryStatus.Retrieving: // Asset pack is being downloaded and transferred to app storage. // N/A for install-time assets. case AssetDeliveryStatus.Available: // Asset pack is downloaded on disk but NOT loaded into memory. // For PlayAssetPackRequest(), this indicates that the request is complete. case AssetDeliveryStatus.Loading: // Asset pack is being loaded. case AssetDeliveryStatus.Loaded: // Asset pack has finished loading, assets can now be loaded. // For PlayAssetBundleRequest(), this indicates that the request is complete. case AssetDeliveryStatus.Failed: // Asset pack retrieval has failed. case AssetDeliveryStatus.WaitingForWifi: // Asset pack retrieval paused until either the device connects via Wi-Fi, // or the user accepts the PlayAssetDelivery.ShowCellularDataConfirmation dialog. default: break; }
大量下载
大于 150MB 的资产包可以自动下载,但只能通过 Wi-Fi 下载。如果用户未连接到 Wi-Fi,则PlayAssetBundleRequest状态设置为 AssetDeliveryStatus.WaitingForWifi 并暂停下载。在这种情况下,要么等待设备连接到 Wi-Fi,然后继续下载,要么提示用户批准通过蜂窝连接下载包。
if(bundleRequest.Status == AssetDeliveryStatus.WaitingForWifi) { var userConfirmationOperation = PlayAssetDelivery.ShowCellularDataConfirmation(); yield return userConfirmationOperation; switch(userConfirmationOperation.GetResult()) { case ConfirmationDialogResult.Unknown: // userConfirmationOperation finished with an error. Something went // wrong when displaying the prompt to the user, and they weren't // able to interact with the dialog. In this case, we recommend // developers wait for Wi-Fi before attempting to download again. // You can get more info by calling GetError() on the operation. case ConfirmationDialogResult.Accepted: // User accepted the confirmation dialog - download will start // automatically (no action needed). case ConfirmationDialogResult.Declined: // User canceled or declined the dialog. Await Wi-Fi connection, or // re-prompt the user. default: break; } }
取消请求(仅限按需)
如果需要在 AssetBundles 加载到内存之前取消请求,请调用 对象AttemptCancel() 上的方法 PlayAssetBundleRequest:
// Will only attempt if the status is Pending, Retrieving, or Available - otherwise // it will be a no-op. bundleRequest.AttemptCancel(); // Check to see if the request was successful by checking if the error code is Canceled. if(bundleRequest.Error == AssetDeliveryErrorCode.Canceled) { // Request was successfully canceled. }
异步请求资产包
在大多数情况下,你应该使用 Coroutines异步请求资产包并监控进度,如下所示:
private IEnumerator LoadAssetBundleCoroutine(string assetBundleName) { PlayAssetBundleRequest bundleRequest = PlayAssetDelivery.RetrieveAssetBundleAsync(assetBundleName); while (!bundleRequest.IsDone) { if(bundleRequest.Status == AssetDeliveryStatus.WaitingForWifi) { var userConfirmationOperation = PlayAssetDelivery.ShowCellularDataConfirmation(); // Wait for confirmation dialog action. yield return userConfirmationOperation; if((userConfirmationOperation.Error != AssetDeliveryErrorCode.NoError) || (userConfirmationOperation.GetResult() != ConfirmationDialogResult.Accepted)) { // The user did not accept the confirmation - handle as needed. } // Wait for Wi-Fi connection OR confirmation dialog acceptance before moving on. yield return new WaitUntil(() => bundleRequest.Status != AssetDeliveryStatus.WaitingForWifi); } // Use bundleRequest.DownloadProgress to track download progress. // Use bundleRequest.Status to track the status of request. yield return null; } if (bundleRequest.Error != AssetDeliveryErrorCode.NoError) { // There was an error retrieving the bundle. For error codes NetworkError // and InsufficientStorage, you may prompt the user to check their // connection settings or check their storage space, respectively, then // try again. yield return null; } // Request was successful. Retrieve AssetBundle from request.AssetBundle. AssetBundle assetBundle = bundleRequest.AssetBundle;
其他 Play Core API 方法
以下是你可能希望在应用中使用的一些其他 API 方法。
检查下载大小
通过对 Google Play 进行异步调用并设置操作完成时的回调方法来检查 AssetBundle 的大小:
public IEnumerator GetDownloadSize() { PlayAsyncOperation<long> getSizeOperation = PlayAssetDelivery.GetDownloadSize(assetPackName); yield return getSizeOperation; if(operation.Error != AssetDeliveryErrorCode.NoError) { // Error while retrieving download size. } else { // Download size is given in bytes. long downloadSize = operation.GetResult(); } }
移除 AssetBundles
你可以删除当前未加载到内存中的快速关注和按需 AssetBundle。进行以下异步调用并设置完成时的回调方法:
1.PlayAsyncOperation<string> removeOperation = PlayAssetDelivery.RemoveAssetPack(assetBundleName); removeOperation.Completed += (operation) => { if(operation.Error != AssetDeliveryErrorCode.NoError) { // Error while attempting to remove AssetBundles. } else { // Files were deleted OR files did not exist to begin with. } };
测试
在 Unity Editor 中,选择Google > Build and Run。
行为
「install-time」 包将在应用程序安装过程中安装。
「fast-follow」包的行为与「on-demand」包一样。也就是说,当游戏被侧载时它们不会被自动获取。开发者需要在游戏开始时手动请求;这不需要你的应用程序中的任何代码更改。
限制
以下是本地测试的限制:
- Packs 从外部存储而不是 Play 中获取,因此您无法测试您的代码在出现网络错误的情况下的行为。
- 本地测试不包括等待 Wi-Fi 场景。
- 不支持更新。在安装新版本的构建之前,请手动卸载以前的版本。
使用内部应用共享进行测试
当你接近发布候选版本时,请使用尽可能真实的配置来测试你的游戏,以确保你的游戏在生产环境中为您的用户提供良好的性能。 构建您的应用程序包。
要使用内部应用程序共享测试资产交付,请执行以下操作:
- 构建你的应用程序包。
- 按照 Play 管理中心的说明进行操作,了解如何在 内部共享您的应用。
- 在测试设备上,单击您刚刚上传的应用程序版本的内部应用程序共享链接。
- 从点击链接后看到的 Google Play 商店页面安装应用程序。
搞定齐活。