Integrate asset delivery (Unity)

Use the steps in this guide to access your app’s asset packs from your Unity C# code. If you haven't built an app bundle with asset packs, see Build for Unity before going further.

Overview

The Play Asset Delivery Unity API provides the functionality for requesting asset packs, managing downloads, and accessing the assets. You implement this API according to the delivery type of the asset pack you wish to access. These steps are shown in the following flowchart.

Figure 1. Flow diagram for accessing asset packs

Retrieve AssetBundles

Import the Play Asset Delivery library and call the RetrieveAssetBundleAsync() method to retrieve an 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 delivery

Asset packs configured as install-time are immediately available at app launch. You can use the following to load a scene from the AssetBundle:

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 and on-demand delivery

These sections apply to fast-follow and on-demand asset packs.

Check status

Each asset pack is stored in a separate folder in the app's internal storage. Use the isDownloaded() method to determine if an asset pack has already been downloaded.

Monitor the download

Query the PlayAssetBundleRequest object to monitor the status of the request:

// Download progress of request, between 0.0f and 1.0f. The value will always be
// 1.0 for assets delivered upfront.
// 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:
        // AssetBundle download is pending - N/A for upfront assets
    case AssetDeliveryStatus.Retrieving:
        // AssetBundle is being downloaded and transferred to app storage
        // N/A for upfront assets
    case AssetDeliveryStatus.Available:
        // AssetBundle is downloaded on disk but NOT loaded - N/A for upfront assets
    case AssetDeliveryStatus.Loading:
        // AssetBundle is being loaded
    case AssetDeliveryStatus.Loaded:
        // AssetBundle has finished loading, assets can now be loaded
    case AssetDeliveryStatus.Failed:
        // AssetBundle retrieval has failed
    case AssetDeliveryStatus.WaitingForWifi:
        // AssetBundle retrieval paused until either the device connects via Wi-Fi,
        // or the user accepts the PlayAssetDelivery.ShowCellularDataConfirmation dialog
    default:
        break;
}

Large downloads

Asset packs larger than 150MB can download automatically, but only on Wi-Fi. If the user is not on Wi-Fi, the PlayAssetBundleRequest status is set to AssetDeliveryStatus.WaitingForWifi. In this case, pause the download until the device connects to Wi-Fi, or prompt the user for approval to download the pack over a cellular connection:

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;
    }
}

Cancel a request (on-demand only)

If you need to cancel the request before the AssetBundles are loaded into memory, call the AttemptCancel() method on the PlayAssetBundleRequest object:

// 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
}

Request asset packs asynchronously

In most cases, you should use Coroutines to request asset packs asynchronously and monitor progress, as shown by the following:

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 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;

For more information on handling errors, see the list of AssetDeliveryErrorCodes.

Other Play Core API methods

The following are some additional API methods you may want to use in your app.

Check download size

Check the size of an AssetBundle by making an asynchronous call to Google Play and setting a callback method for when the operation completes:

PlayAsyncOperation<long> getSizeOperation = PlayAssetDelivery.GetDownloadSize(assetBundleName);

getSizeOperation.Completed += (operation) =>
            {
                if(operation.Error != AssetDeliveryErrorCode.NoError) {
                    // Error while retrieving download size
                } else {
                    // Download size is given in bytes
                    long downloadSize = operation.GetResult();
                }
            };

Remove AssetBundles

You can remove fast-follow and on-demand AssetBundles that are not currently loaded into memory. Make the following asynchronous call and set a callback method for when it completes:

PlayAsyncOperation<string> removeOperation = PlayAssetDelivery.RemoveAssetBundle(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
                }
            };

Next step

Test asset delivery locally and from Google Play.