Integrare la pubblicazione degli asset (Unity)

Quando integrano la pubblicazione di asset, i giochi Unity possono accedere ai pacchetti di asset utilizzando Addressables o AssetBundle. Addressables è la soluzione di pubblicazione di asset più recente e consigliata per i giochi creati con Unity 2019.4 o versioni successive, mentre AssetBundle fornisce il supporto dei pacchetti di asset in Unity 2017.4 e 2018.4.

Addressables di Unity

I giochi creati con Unity 2019.4 o versioni successive devono utilizzare Addressables per la pubblicazione di asset su Android. Unity fornisce un'API Play Asset Delivery (PAD) per la gestione dei pacchetti di asset Android utilizzando Addressables. Per informazioni sull'utilizzo di Addressables, consulta le seguenti risorse:

• Pacchetto Addressables per Android
• Guida PAD per Unity
• Documentazione di riferimento dell'API PAD per Unity

Utilizzare i file AssetBundle

I giochi creati con Unity 2017.4 e 2018.4 possono utilizzare i file AssetBundle per la pubblicazione di asset su Android. I file AssetBundle di Unity contengono asset serializzati che possono essere caricati dal motore Unity durante l'esecuzione dell' app. Questi file sono specifici per la piattaforma (ad esempio, creati per Android) e possono essere utilizzati in combinazione con i pacchetti di asset. Nella maggior parte dei casi, un file AssetBundle viene inserito in un singolo pacchetto di asset, con il pacchetto che utilizza lo stesso nome di AssetBundle. Se vuoi una maggiore flessibilità nella creazione di un pacchetto di asset, configura il pacchetto di asset utilizzando l'API.

In fase di runtime, utilizza la classe Play Asset Delivery per Unity per recuperare un AssetBundle incluso in un pacchetto di asset.

Prerequisiti

1. Configura l'ambiente di sviluppo:

openupm add com.google.play.assetdelivery

1. Crea AssetBundle in Unity.

Configurare AssetBundle utilizzando l'UI

1. Configura ogni AssetBundle in un pacchetto di asset:

   1. Seleziona Google > Android App Bundle > Asset Delivery.
   2. Per selezionare le cartelle che contengono direttamente i file AssetBundle, fai clic su Aggiungi cartella.

   

2. Per ogni bundle, modifica la Modalità di pubblicazione in Al momento dell'installazione, Fast Follow o On demand. Risolvi eventuali errori o dipendenze e chiudi la finestra.

   

3. Seleziona Google > Crea Android App Bundle per creare l'app bundle.

4. (Facoltativo) Configura l'app bundle in modo che supporti diversi formati di compressione delle texture.

Configurare i pacchetti di asset utilizzando l'API

Puoi configurare la pubblicazione di asset tramite script dell'editor che possono essere eseguiti nell'ambito di un sistema di compilazione automatizzato.

Utilizza la AssetPackConfig classe per definire gli asset da includere in una build di Android App Bundle, nonché la modalità di invio degli asset. Questi pacchetti di asset non devono contenere un AssetBundle.

public void ConfigureAssetPacks {
   // Creates an AssetPackConfig with a single asset pack, named
   // examplePackName, containing all the files in path/to/exampleFolder.
   var assetPackConfig = new AssetPackConfig();
   assetPackConfig.AddAssetsFolder("examplePackName",
                                   "path/to/exampleFolder",
                                   AssetPackDeliveryMode.OnDemand);

   // Configures the build system to use the newly created assetPackConfig when
   // calling Google > Build and Run or Google > Build Android App Bundle.
   AssetPackConfigSerializer.SaveConfig(assetPackConfig);

   // Alternatively, use BundleTool.BuildBundle to build an App Bundle from script.
   BuildBundle(new buildPlayerOptions(), assetPackConfig);
}

Puoi anche utilizzare il metodo statico BuildBundle nella classe Bundletoolper generare un Android App Bundle con pacchetti di asset, dati BuildPlayerOptions e AssetPackConfig.

Per un tutorial guidato, consulta il codelab Utilizzo di Play Asset Delivery nei giochi Unity.

Integrare con l'API Play Asset Delivery Unity

L' API Play Asset Delivery Unity fornisce la funzionalità per richiedere pacchetti di asset, gestire i download e accedere agli asset. Assicurati di aggiungere prima il plugin Unity al tuo progetto.

Le funzioni che utilizzi nell'API dipendono dalla modalità di creazione dei pacchetti di asset.

Se hai creato pacchetti di asset utilizzando l'UI del plugin, seleziona Pacchetti di asset configurati con il plugin.

Se hai creato pacchetti di asset utilizzando l'API (o l'UI del plugin), seleziona Pacchetti di asset configurati con l'API.

L'API è simile indipendentemente dal tipo di pubblicazione del pacchetto di asset a cui vuoi accedere. Questi passaggi sono illustrati nel seguente diagramma di flusso.

Figura 1. Diagramma di flusso per l'accesso ai pacchetti di asset

Recuperare un pacchetto di asset

Importa la libreria Play Asset Delivery e chiama il RetrieveAssetPackAsync() metodo per scaricare un pacchetto di asset se l'ultima versione del pacchetto non è già disponibile sul disco.

using Google.Play.AssetDelivery;

// After download, the assets and/or AssetBundles contained in the asset pack
// are not loaded into memory.
PlayAssetPackRequest request = PlayAssetDelivery.RetrieveAssetPackAsync(assetPackName);

Pubblicazione al momento dell'installazione

Un pacchetto di asset configurato come install-time è immediatamente disponibile all'avvio dell'app, ma devi caricare i relativi asset in memoria. Consulta Caricare gli asset in memoria.

Pubblicazione Fast Follow e on demand

Queste sezioni si applicano ai pacchetti di asset fast-follow e on-demand.

Verifica lo stato

Ogni pacchetto di asset viene archiviato in una cartella separata nella memoria interna dell'app. Utilizza il isDone() metodo per determinare se un pacchetto di asset è già stato scaricato ed è disponibile o se si è verificato un errore.

Monitorare il download

Esegui una query sull' PlayAssetPackRequest oggetto per monitorare lo stato della richiesta:

// 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 does not mean that the request has completed, only that
// the DOWNLOADING stage is finished.
float progress = request.DownloadProgress;

// Returns the status of the retrieval request.
// If the request completed successfully, this value should be AssetDeliveryStatus.Available.
// If an error occurred, this value should be AssetDeliveryStatus.Failed.

AssetDelivery status = request.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.Failed:
        // Asset pack retrieval failed.
    case AssetDeliveryStatus.WaitingForWifi:
        // Asset pack retrieval paused until either the device connects via Wi-Fi,
        // or the user accepts the PlayAssetDelivery.ShowConfirmationDialog dialog.
    case AssetDeliveryStatus.RequiresUserConfirmation:
        // Asset pack retrieval paused until the user accepts the
        // PlayAssetDelivery.ShowConfirmationDialog dialog.
    default:
        break;
}

// Returns true if status is AssetDeliveryStatus.Available or AssetDeliveryStatus.Failed.
bool done = request.IsDone;

// If AssetDeliveryStatus.Failed, find more info about the error.
AssetDeliveryErrorCode error = request.Error;

Download di grandi dimensioni

I pacchetti di asset di dimensioni superiori a 200 MB possono essere scaricati automaticamente, ma solo se il dispositivo è connesso al Wi-Fi. Se l'utente non è connesso al Wi-Fi, lo PlayAssetPackRequest stato viene impostato su AssetDeliveryStatus.WaitingForWifi e il download viene messo in pausa. In questo caso, attendi che il dispositivo si connetta al Wi-Fi, riprendendo il download, oppure chiedi all'utente l'autorizzazione per scaricare il pacchetto tramite una rete cellulare.

Conferma dell'utente obbligatoria

Se un pacchetto ha lo stato AssetDeliveryStatus.RequiresUserConfirmation, il download non verrà eseguito finché l'utente non accetta la finestra di dialogo visualizzata con PlayAssetDelivery.ShowConfirmationDialog(). Questo stato può verificarsi se l'app non viene riconosciuta da Play. Tieni presente che, in questo caso, la chiamata a PlayAssetDelivery.ShowConfirmationDialog() comporta l'aggiornamento dell'app. Dopo l'aggiornamento, richiedi di nuovo gli asset.

if(request.Status == AssetDeliveryStatus.RequiresUserConfirmation
   || request.Status == AssetDeliveryStatus.WaitingForWifi) {
    var userConfirmationOperation = PlayAssetDelivery.ShowConfirmationDialog();
    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.
        case ConfirmationDialogResult.Accepted:
            // User accepted the confirmation dialog--an update will start.
        case ConfirmationDialogResult.Declined:
            // User canceled or declined the dialog. It can be shown again.
        default:
            break;
    }
}

Annullare una richiesta (solo on demand)

Se devi annullare la richiesta prima che i pacchetti di asset vengano scaricati, chiama il AttemptCancel() metodo sull'oggetto PlayAssetPackRequest:

// Will only attempt if the status is Pending, Retrieving, or Available; otherwise
// it will be a no-op.
request.AttemptCancel();

// Check to see if the request was successful by checking if the error code is Canceled.
if(request.Error == AssetDeliveryErrorCode.Canceled) {
    // Request was successfully canceled.
}

Caricare gli asset in memoria

Una volta completata la richiesta, utilizza una di queste funzioni per caricare gli asset in memoria:

• Utilizza PlayAssetPackRequest.GetAssetLocation() per ottenere un AssetLocation oggetto. Questo fornisce il percorso, l'offset e le dimensioni dell'asset in modo che possa essere caricato dal disco.
• Se l'asset è un AssetBundle, puoi utilizzare il metodo pratico PlayAssetPackRequest.LoadAssetBundleAsync(assetPath). Il percorso dell'asset che passi deve corrispondere al percorso di AssetBundle all'interno del pacchetto di asset. Verrà restituito un AssetBundleCreateRequest.

Richiedere i pacchetti di asset in modo asincrono

Nella maggior parte dei casi, devi utilizzare le coroutine per richiedere i pacchetti di asset in modo asincrono e monitorare l'avanzamento, come mostrato di seguito:

private IEnumerator LoadAssetPackCoroutine(string assetPackName) {

    PlayAssetPackRequest request =
        PlayAssetDelivery.RetrieveAssetPackAsync(assetPackName);

    while (!request.IsDone) {
        if(request.Status == AssetDeliveryStatus.WaitingForWifi) {
            var userConfirmationOperation = PlayAssetDelivery.ShowConfirmationDialog();

            // 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(() => request.Status != AssetDeliveryStatus.WaitingForWifi);
        }

        // Use request.DownloadProgress to track download progress.
        // Use request.Status to track the status of request.

        yield return null;
    }

    if (request.Error != AssetDeliveryErrorCode.NoError) {
        // There was an error retrieving the pack. 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. Load the asset pack into memory.
    AssetBundleCreateRequest assetBundleCreateRequest = request.LoadAssetBundleAsync(path/to/exampleBundle);
    yield return assetBundleCreateRequest;
    AssetBundle assetBundle = assetBundleCreateRequest.assetBundle;

Per ulteriori informazioni sulla gestione degli errori, consulta l'elenco dei codici di errore.

Altri metodi della libreria di base Play

Di seguito sono riportati alcuni metodi API aggiuntivi che potresti voler utilizzare nella tua app.

Recuperare più pacchetti di asset

Per recuperare più pacchetti di asset contemporaneamente, utilizza la seguente funzione:

// assetPackNames is an array of strings corresponding to asset packs.
PlayAssetPackBatchRequest batchRequest = PlayAssetDelivery.RetrieveAssetPackBatchAsync(<IListstring> assetPackNames);

Monitora lo stato di ogni richiesta esaminando il Dictionary degli stati:

// Dictionary of AssetPackStates, with the asset pack name as the key.
Dictionary<string, PlayAssetPackRequest> requests = batchRequest.Requests;

// Returns true if all requests are complete.
bool requestComplete = batchRequest.IsDone;

Verificare le dimensioni del download

Verifica le dimensioni di un pacchetto di asset effettuando una chiamata asincrona a Google Play e impostando un metodo di callback per quando l'operazione è completata:

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

Rimuovere AssetBundle

Puoi rimuovere i pacchetti di asset Fast Follow e on demand che non sono attualmente caricati in memoria. Esegui la seguente chiamata asincrona e imposta un metodo di callback per quando viene completata:

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

Passaggi successivi

Testa la pubblicazione di asset localmente e da Google Play.