Integrare la pubblicazione degli asset (Unity)

Quando integri il caricamento delle risorse, i giochi Unity possono accedere ai pacchetti di asset utilizzando Addressables o AssetBundles. Gli asset indirizzabili sono la soluzione di caricamento degli asset più recente e consigliata per i giochi creati con Unity 2019.4 o versioni successive, mentre gli AssetBundle forniscono il supporto degli asset pack in Unity 2017.4 e 2018.4.

Unity Addressables

I giochi creati con Unity 2019.4 o versioni successive devono utilizzare Addressables per il caricamento degli asset su Android. Unity fornisce un'API Play Asset Delivery (PAD) per gestire i 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 il caricamento 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 della piattaforma (ad esempio, creati per Android) e possono essere utilizzati in combinazione con i pacchetti di asset. Molto spesso, un file AssetBundle viene pacchettizzato in un singolo asset pack, che utilizza lo stesso nome dell'AssetBundle. Se vuoi una maggiore flessibilità nella creazione di un pacchetto di asset, configuralo utilizzando l'API.

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

Prerequisiti

1. Configura l'ambiente di sviluppo:

OpenUPM-CLI

Se hai installato l'interfaccia a riga di comando OpenUPM, puoi installare il registry OpenUPM con il seguente comando:

openupm add com.google.play.assetdelivery

OpenUPM

1. Apri le impostazioni del gestore dei pacchetti selezionato l'opzione di menu di Unity Modifica > Impostazioni progetto > Gestore dei pacchetti.

2. Aggiungi OpenUPM come registry con ambito alla finestra Gestione pacchetti:

   Name: package.openupm.com
   URL: https://package.openupm.com
   Scopes: com.google.external-dependency-manager
     com.google.play.common
     com.google.play.core
     com.google.play.assetdelivery
     com.google.android.appbundle
   

3. Apri il menu del gestore dei pacchetti selezionando l'opzione di menu di Unity Finestra > Gestore dei pacchetti.

4. Imposta il menu a discesa Ambito gestore in modo da selezionare I miei registry.

5. Seleziona il pacchetto Plug-in di integrità di Google Play per Unity dall'elenco dei pacchetti e premi Installa.

Importa da GitHub

1. Scarica la release .unitypackage più recente da GitHub.

2. Importa il file .unitypackage selezionando l'opzione del menu Unity Asset > Importa pacchetto > Pacchetto personalizzato e importando tutti gli elementi.

Nota: se scarichi e utilizzi i plug-in Unity di Google Play, accetti i Termini di servizio del kit di sviluppo software Play Core.

1. Crea AssetBundle in Unity.

   Nota: puoi utilizzare il browser AssetBundle di Unity per creare e gestire gli AssetBundle nel tuo progetto Unity.

Configurare gli AssetBundle utilizzando l'interfaccia utente

1. Configura ogni AssetBundle in un asset pack:

   1. Seleziona Google > Android App Bundle > Impostazioni di caricamento delle risorse.
   2. Per selezionare le cartelle che contengono direttamente i file AssetBundle, fai clic su Aggiungi cartella.

   

2. Per ogni bundle, imposta Modalità di importazione su Ora installazione, Seguito rapido 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 da supportare diversi formati di compressione delle texture.

Configurare i pacchetti di asset utilizzando l'API

Puoi configurare il caricamento degli asset tramite script di editor che possono essere eseguiti nell'ambito di un sistema di compilazione automatico.

Utilizza la classe AssetPackConfig per definire quali asset includere in una build Android App Bundle, nonché la modalità di caricamento 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 Bundletool per generare un app bundle Android con asset pack, a condizione che siano presenti BuildPlayerOptions e AssetPackConfig.

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

Integrazione con l'API Unity di Play Asset Delivery

L'API Unity Play Asset Delivery offre la funzionalità per richiedere pacchetti di asset, gestire i download e accedere agli asset. Assicurati di aggiungere il plug-in Unity al progetto.

Le funzioni che utilizzi nell'API dipendono dal modo in cui hai creato gli asset pack.

Se hai creato pacchetti di asset utilizzando l'interfaccia utente del plug-in, seleziona Pacchetti di asset configurati tramite plug-in.

Se hai creato pacchetti di asset utilizzando l'API (o l'interfaccia utente del plug-in), seleziona Pacchetti di asset configurati tramite API.

Pacchetti di asset configurati tramite plug-in Pacchetti di asset configurati tramite API

L'API viene implementata in base al tipo di caricamento del pacchetto di asset a cui vuoi accedere. Questi passaggi sono illustrati nel seguente diagramma di flusso.

Figura 1. Diagramma di flusso per accedere ai pacchetti di asset

Recupera AssetBundles

Importa la libreria Play Asset Delivery e chiama il metodo RetrieveAssetBundleAsync() per recuperare 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);

Pubblicazione al momento dell'installazione

I pacchetti di asset configurati come install-time sono disponibili immediatamente al lancio dell'app. Per caricare una scena dall'AssetBundle, puoi utilizzare quanto segue:

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 e distribuzione 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 nello spazio di archiviazione interno dell'app. Utilizza il metodo isDownloaded() per determinare se un pacchetto di asset è già stato scaricato.

Monitora il download

Esegui una query sull'oggetto PlayAssetBundleRequest 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 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.ShowConfirmationDialog dialog.
    case AssetDeliveryStatus.RequiresUserConfirmation:
        // Asset pack retrieval paused until the user accepts the
        // PlayAssetDelivery.ShowConfirmationDialog dialog.
    default:
        break;
}

Download di grandi dimensioni

I pacchetti di asset di dimensioni superiori a 200 MB possono essere scaricati automaticamente, ma solo tramite Wi-Fi. Se l'utente non è connesso al Wi-Fi, lo stato PlayAssetBundleRequest 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 o chiedendo all'utente l'approvazione per scaricare il pacchetto tramite una connessione di rete mobile.

Conferma dell'utente richiesta

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 è riconosciuta da Google Play. Tieni presente che in questo caso la chiamata a PlayAssetDelivery.ShowConfirmationDialog() provoca 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 gli AssetBundle vengano caricati nella memoria, chiama il metodo AttemptCancel() sull'oggetto 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.
}

Richiedi pacchetti di asset in modo asincrono

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

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;

Per ulteriori informazioni sulla gestione degli errori, consulta l'elenco di AssetDeliveryErrorCodes.

Altri metodi dell'API Play Core

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

Controlla le dimensioni del download

Controlla le dimensioni di un AssetBundle effettuando una chiamata asincrona a Google Play e impostando un metodo di callback per il completamento dell'operazione:

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 AssetBundles

Puoi rimuovere gli AssetBundle di tipo fast-follow e on demand che non sono attualmente caricati in memoria. Esegui la seguente chiamata asincrona e imposta un metodo di callback per il completamento:

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 il caricamento degli asset localmente e da Google Play.