Cómo integrar Asset Delivery (Unity)

Sigue los pasos que se indican en esta guía para acceder a los paquetes de elementos de tu app desde el código C# en Unity. Si no creaste un paquete de aplicación con paquetes de elementos, consulta Cómo compilar para Unity antes de avanzar.

Descripción general

La API de Unity de Play Asset Delivery proporciona la funcionalidad para solicitar paquetes de elementos, administrar descargas y acceder a los elementos. Las funciones que usas en la API dependen de cómo creaste los paquetes de elementos.

Si creaste paquetes de elementos con la IU del complemento, selecciona Paquetes de elementos configurados por complementos.

Si creaste paquetes de elementos con la API (o la IU del complemento), selecciona Paquetes de elementos configurados por API.

Debes implementar la API según el tipo de entrega del paquete de elementos al que deseas acceder. Estos pasos se muestran en el siguiente diagrama de flujo.

Figura 1: Diagrama de flujo para acceder a paquetes de elementos

Cómo recuperar AssetBundles

Importa la Biblioteca de Play Asset Delivery y llama al método RetrieveAssetBundleAsync() para recuperar un 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);

Cómo realizar la entrega durante la instalación

Los paquetes de elementos configurados como install-time están disponibles de inmediato para el lanzamiento de la app. Puedes usar lo siguiente para cargar una escena desde 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]);

Cómo realizar entregas rápidas y a pedido

Estas secciones se aplican a los paquetes de elementos fast-follow y on-demand.

Cómo comprobar el estado

Cada paquete de elementos se almacena en una carpeta independiente del almacenamiento interno de la app. Usa el método isDownloaded() para determinar si ya se descargó un paquete de elementos.

Cómo supervisar la descarga

Consulta el objeto PlayAssetBundleRequest para supervisar el estado de la solicitud:

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

Descargas grandes

Los paquetes de elementos de más de 150 MB pueden descargarse automáticamente, pero solo en Wi-Fi. Si el usuario no está conectado a una red Wi-Fi, el estado PlayAssetBundleRequest se establece en AssetDeliveryStatus.WaitingForWifi y la descarga se pausa. En este caso, espera hasta que el dispositivo se conecte a Wi-Fi, reanuda la descarga o pídele al usuario que apruebe la descarga del paquete mediante una conexión móvil.

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

Cómo cancelar una solicitud (solo a pedido)

Si necesitas cancelar la solicitud antes de que los AssetBundles se carguen a la memoria, llama al método AttemptCancel() en 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.
}

Cómo solicitar paquetes de elementos de manera asíncrona

En la mayoría de los casos, debes usar Corrutinas para solicitar paquetes de elementos de manera asíncrona y supervisar el progreso, como se muestra de la siguiente manera:

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;

Para obtener más información sobre cómo manejar los errores, consulta la lista de AssetDeliveryErrorCodes.

Otros métodos de la API de Play Core

Estos son algunos métodos de API adicionales que te recomendamos usar en tu app.

Cómo comprobar el tamaño de descarga

Para verificar el tamaño de un AssetBundle, realiza una llamada asíncrona en Google Play y configura un método de devolución de llamada para cuando finalice la operación:

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

Cómo quitar AssetBundles

Puedes quitar los AssetBundles rápidos y a pedido que no se cargan actualmente a la memoria. Realiza la siguiente llamada asíncrona y configura un método de devolución de llamada para cuando se complete:

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

Siguiente paso

Prueba Asset Delivery de forma local y desde Google Play.