Integrare la distribuzione degli asset (Kotlin e Java)

Segui i passaggi descritti in questa guida per accedere ai pacchetti di asset della tua app dal codice Java.

Compila per Kotlin e Java

Segui questa procedura per integrare Play Asset Delivery nell'app bundle Android del tuo progetto. Non è necessario utilizzare Android Studio per eseguire questi passaggi.

Nota: per un tutorial guidato, consulta il codelab sull'utilizzo di Play Asset Delivery nei giochi nativi.

1. Aggiorna la versione del plug-in Android per Gradle nel file build.gradle del progetto a 4.0.0 o versioni successive.

2. Nella directory di primo livello del progetto, crea una directory per il pacchetto di asset. Questo nome di directory viene utilizzato come nome del pacchetto di asset. I nomi dei pacchetti di asset devono iniziare con una lettera e possono contenere solo lettere, numeri e trattini bassi.

3. Nella directory del pacchetto di asset, crea un file build.gradle e aggiungi il seguente codice. Assicurati di specificare il nome del pacchetto di asset e un solo tipo di caricamento:

   Groovy

   // In the asset pack's build.gradle file:
   plugins {
     id 'com.android.asset-pack'
   }
   
   assetPack {
       packName = "asset-pack-name" // Directory name for the asset pack
       dynamicDelivery {
           deliveryType = "[ install-time | fast-follow | on-demand ]"
       }
   }
   

   Kotlin

   // In the asset pack's build.gradle.kts file:
   plugins {
     id("com.android.asset-pack")
   }
   
   assetPack {
     packName.set("asset-pack-name") // Directory name for the asset pack
     dynamicDelivery {
       deliveryType.set("[ install-time | fast-follow | on-demand ]")
     }
   }
   

4. Nel file build.gradle dell'app del progetto, aggiungi il nome di ogni asset pack nel progetto come mostrato di seguito:

   Groovy

   // In the app build.gradle file:
   android {
       ...
       assetPacks = [":asset-pack-name", ":asset-pack2-name"]
   }
   

   Kotlin

   // In the app build.gradle.kts file:
   android {
       ...
       assetPacks += listOf(":asset-pack-name", ":asset-pack2-name")
   }
   

5. Nel file settings.gradle del progetto, includi tutti i pacchetti di asset come mostrato di seguito:

   Groovy

   // In the settings.gradle file:
   include ':app'
   include ':asset-pack-name'
   include ':asset-pack2-name'
   

   Kotlin

   // In the settings.gradle.kts file:
   include(":app")
   include(":asset-pack-name")
   include(":asset-pack2-name")
   

6. Nella directory del pacchetto di asset, crea la seguente sottodirectory: src/main/assets.

7. Inserisci gli asset nella directory src/main/assets. Puoi anche creare sottodirectory qui. La struttura di directory della tua app dovrebbe ora avere il seguente aspetto:

   • build.gradle
   • settings.gradle
   • app/
   • asset-pack-name/build.gradle
   • asset-pack-name/src/main/assets/your-asset-directories

8. Crea l'app bundle Android con Gradle. Nell'app bundle generato, la directory di primo livello ora include quanto segue:

   • asset-pack-name/manifest/AndroidManifest.xml: configura l'identificatore e la modalità di caricamento del pacchetto di asset
   • asset-pack-name/assets/your-asset-directories: directory contenente tutte le risorse caricate nell'asset pack

   Gradle genera il manifest per ogni asset pack e genera la directory assets/ per te.

9. (Facoltativo) Includi la Play Asset Delivery Library se prevedi di utilizzare il caricamento in tempo reale e on demand

   Groovy

   implementation "com.google.android.play:asset-delivery:2.2.2"
   // For Kotlin use asset-delivery-ktx
   implementation "com.google.android.play:asset-delivery-ktx:2.2.2"
   

   Kotlin

   implementation("com.google.android.play:asset-delivery:2.2.2")
   // For Kotlin use core-ktx
   implementation("com.google.android.play:asset-delivery-ktx:2.2.2")
   

10. (Facoltativo) Configura l'app bundle in modo da supportare diversi formati di compressione delle texture.

Nota: per accedere agli asset raggruppati, devi eseguire l'app come app bundle anziché come APK autonomo. In alternativa, puoi modificare la configurazione di esecuzione/debug predefinita per caricare l'app come APK anziché come bundle. Consulta Creare e testare Android App Bundle.

Eseguire l'integrazione con l'API Play Asset Delivery

L'API Java Play Asset Delivery fornisce la classe AssetPackManager per richiedere pacchetti di asset, gestire i download e accedere agli asset. Assicurati innanzitutto di aggiungere la libreria Play Asset Delivery al progetto.

Implementa questa API in base al tipo di caricamento del pacchetto di asset a cui vuoi accedere. Questi passaggi sono riportati nel seguente diagramma di flusso.

Nota: per accedere ai pacchetti di asset install-time devi utilizzare un'API diversa rispetto ai pacchetti di asset fast-follow e on-demand.

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

Pubblicazione al momento dell'installazione

I pacchetti di asset configurati come install-time sono disponibili immediatamente al lancio dell'app. Utilizza l'API AssetManager di Java per accedere agli asset pubblicati in questa modalità:

Kotlin

import android.content.res.AssetManager
...
val context: Context = createPackageContext("com.example.app", 0)
val assetManager: AssetManager = context.assets
val stream: InputStream = assetManager.open("asset-name")

Java

import android.content.res.AssetManager;
...
Context context = createPackageContext("com.example.app", 0);
AssetManager assetManager = context.getAssets();
InputStream is = assetManager.open("asset-name");

Fast-follow e distribuzione on demand

Le sezioni seguenti mostrano come ottenere informazioni sui pacchetti di asset prima di scaricarli, come chiamare l'API per avviare il download e come accedere ai pacchetti scaricati. 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 getPackLocation() per determinare la cartella principale di un asset pack. Questo metodo restituisce i seguenti valori:

Valore restituito	Stato
Un oggetto AssetPackLocation valido	La cartella principale del pacchetto di asset è pronta per l'accesso immediato all'indirizzo assetsPath()
null	Asset pack o asset sconosciuti non disponibili

Nota: non fare affidamento sulle posizioni dei pacchetti di asset memorizzati nella cache tra un lancio dell'app e l'altro. L'app deve sempre verificare l'esistenza dei pacchetti di asset a ogni avvio. I pacchetti di asset potrebbero diventare non validi a causa degli aggiornamenti dell'app o se l'utente cancella i dati dell'app.

Visualizzare le informazioni di download dei pacchetti di asset

Le app sono tenute a indicare le dimensioni del download prima di recuperare il pacchetto di asset. Utilizza il metodo requestPackStates() o getPackStates() per determinare le dimensioni del download e se il pacchetto è già in download.

Kotlin

suspend fun requestPackStates(packNames: List<String>): AssetPackStates

Java

Task<AssetPackStates> getPackStates(List<String> packNames)

requestPackStates() è una funzione di sospensione che restituisce un oggetto AssetPackStates mentre getPackStates() è un metodo asincrono che restituisce un Task<AssetPackStates>. Il metodo packStates() di un oggetto AssetPackStates restituisce un Map<String, AssetPackState>. Questa mappa contiene lo stato di ogni pacchetto di asset richiesto, indicato dal nome:

Kotlin

AssetPackStates#packStates(): Map<String, AssetPackState>

Java

Map<String, AssetPackState> AssetPackStates#packStates()

La richiesta finale è mostrata di seguito:

Kotlin

const val assetPackName = "assetPackName"
coroutineScope.launch {
  try {
    val assetPackStates: AssetPackStates =
      manager.requestPackStates(listOf(assetPackName))
    val assetPackState: AssetPackState =
      assetPackStates.packStates()[assetPackName]
  } catch (e: RuntimeExecutionException) {
    Log.d("MainActivity", e.message)
  }
}

Java

final String assetPackName = "myasset";

assetPackManager
    .getPackStates(Collections.singletonList(assetPackName))
    .addOnCompleteListener(new OnCompleteListener<AssetPackStates>() {
        @Override
        public void onComplete(Task<AssetPackStates> task) {
            AssetPackStates assetPackStates;
            try {
                assetPackStates = task.getResult();
                AssetPackState assetPackState =
                    assetPackStates.packStates().get(assetPackName);
            } catch (RuntimeExecutionException e) {
                Log.d("MainActivity", e.getMessage());
                return;
            })

I seguenti metodi AssetPackState forniscono le dimensioni del pacchetto di asset, la quantità scaricata fino a quel momento (se richiesta) e la quantità già trasferita all'app:

• totalBytesToDownload()
• bytesDownloaded()
• transferProgressPercentage()

Per ottenere lo stato di un pacchetto di asset, utilizza il metodo status(), che restituisce lo stato come un intero corrispondente a un campo costante nella classe AssetPackStatus. Un asset pack non ancora installato ha lo stato AssetPackStatus.NOT_INSTALLED.

Se una richiesta non va a buon fine, utilizza il metodo errorCode(), il cui valore restituito corrisponde a un campo costante nella classe AssetPackErrorCode.

Installa

Utilizza il metodo requestFetch() o fetch() per scaricare un asset pack per la prima volta o per richiedere il completamento dell'aggiornamento di un asset pack:

Kotlin

suspend fun AssetPackManager.requestFetch(packs: List<String>): AssetPackStates

Java

Task<AssetPackStates> fetch(List<String> packNames)

Questo metodo restituisce un oggetto AssetPackStates contenente un elenco di pacchetti, i relativi stati di download iniziali e le dimensioni. Se un pacchetto di risorse richiesto tramite requestFetch() o fetch() è già in fase di download, viene restituito lo stato del download e non viene avviato alcun download aggiuntivo.

Nota: nella maggior parte dei casi, implementi un listener per monitorare il processo di download e installazione, come descritto nella sezione successiva.

Monitorare gli stati di download

Devi implementare un AssetPackStateUpdatedListener per monitorare l'avanzamento dell'installazione dei set di asset. Gli aggiornamenti dello stato sono suddivisi per pacchetto per supportare il monitoraggio dello stato dei singoli pacchetti di asset. Puoi iniziare a utilizzare i pacchetti di asset disponibili prima del completamento di tutti gli altri download per la tua richiesta.

Kotlin

fun registerListener(listener: AssetPackStateUpdatedListener)
fun unregisterListener(listener: AssetPackStateUpdatedListener)

Java

void registerListener(AssetPackStateUpdatedListener listener)
void unregisterListener(AssetPackStateUpdatedListener listener)

Nota: il Play Store attiva automaticamente il download di eventuali pacchetti fast-follow dopo che l'utente ha installato o aggiornato l'app. Tuttavia, questi pacchetti potrebbero non essere subito pronti per l'uso. Devi controllare lo stato dei fast-follow pacchetti a ogni avvio dell'app. Se il download è in corso, monitoralo con un ascoltatore. Se il download viene annullato o messo in pausa, puoi riprenderlo utilizzando il metodo fetch(), come descritto nella sezione Installazione.

Download di grandi dimensioni

Se il download è superiore a 200 MB e l'utente non è connesso al Wi-Fi, il download non viene avviato finché l'utente non dà il consenso esplicito a procedere con il download utilizzando una connessione dati mobili. Analogamente, se il download è di grandi dimensioni e l'utente perde la connessione Wi-Fi, il download viene messo in pausa e per procedere utilizzando una connessione dati mobili è necessario il consenso esplicito. Un pacchetto in pausa ha lo stato WAITING_FOR_WIFI. Per attivare il flusso dell'interfaccia utente che richiede il consenso dell'utente, utilizza il metodo showConfirmationDialog().

Tieni presente che se l'app non chiama questo metodo, il download viene messo in pausa e riprende automaticamente solo quando l'utente torna a una connessione Wi-Fi.

Conferma dell'utente richiesta

Se un pacchetto ha lo stato REQUIRES_USER_CONFIRMATION, il download non procede finché l'utente non accetta la finestra di dialogo visualizzata con showConfirmationDialog(). Questo stato può verificarsi quando l'app non è riconosciuta da Google Play, ad esempio se è stata installata tramite sideload. Tieni presente che in questo caso la chiamata a showConfirmationDialog() causerà l'aggiornamento dell'app. Dopo l'aggiornamento, dovrai nuovamente richiedere le risorse.

Di seguito è riportato un esempio di implementazione di un listener:

Kotlin

private val activityResultLauncher = registerForActivityResult(
    ActivityResultContracts.StartIntentSenderForResult()
) { result ->
    if (result.resultCode == RESULT_OK) {
        Log.d(TAG, "Confirmation dialog has been accepted.")
    } else if (result.resultCode == RESULT_CANCELED) {
        Log.d(TAG, "Confirmation dialog has been denied by the user.")
    }
}

assetPackManager.registerListener { assetPackState ->
  when(assetPackState.status()) {
    AssetPackStatus.PENDING -> {
      Log.i(TAG, "Pending")
    }
    AssetPackStatus.DOWNLOADING -> {
      val downloaded = assetPackState.bytesDownloaded()
      val totalSize = assetPackState.totalBytesToDownload()
      val percent = 100.0 * downloaded / totalSize

      Log.i(TAG, "PercentDone=" + String.format("%.2f", percent))
    }
    AssetPackStatus.TRANSFERRING -> {
      // 100% downloaded and assets are being transferred.
      // Notify user to wait until transfer is complete.
    }
    AssetPackStatus.COMPLETED -> {
      // Asset pack is ready to use. Start the game.
    }
    AssetPackStatus.FAILED -> {
      // Request failed. Notify user.
      Log.e(TAG, assetPackState.errorCode())
    }
    AssetPackStatus.CANCELED -> {
      // Request canceled. Notify user.
    }
    AssetPackStatus.WAITING_FOR_WIFI,
    AssetPackStatus.REQUIRES_USER_CONFIRMATION -> {
      if (!confirmationDialogShown) {
        assetPackManager.showConfirmationDialog(activityResultLauncher);
        confirmationDialogShown = true
      }
    }
    AssetPackStatus.NOT_INSTALLED -> {
      // Asset pack is not downloaded yet.
    }
    AssetPackStatus.UNKNOWN -> {
      Log.wtf(TAG, "Asset pack status unknown")
    }
  }
}

Java

assetPackStateUpdateListener = new AssetPackStateUpdateListener() {
    private final ActivityResultLauncher<IntentSenderRequest> activityResultLauncher =
      registerForActivityResult(
          new ActivityResultContracts.StartIntentSenderForResult(),
          new ActivityResultCallback<ActivityResult>() {
            @Override
            public void onActivityResult(ActivityResult result) {
              if (result.getResultCode() == RESULT_OK) {
                Log.d(TAG, "Confirmation dialog has been accepted.");
              } else if (result.getResultCode() == RESULT_CANCELED) {
                Log.d(TAG, "Confirmation dialog has been denied by the user.");
              }
            }
          });

    @Override
    public void onStateUpdate(AssetPackState assetPackState) {
      switch (assetPackState.status()) {
        case AssetPackStatus.PENDING:
          Log.i(TAG, "Pending");
          break;

        case AssetPackStatus.DOWNLOADING:
          long downloaded = assetPackState.bytesDownloaded();
          long totalSize = assetPackState.totalBytesToDownload();
          double percent = 100.0 * downloaded / totalSize;

          Log.i(TAG, "PercentDone=" + String.format("%.2f", percent));
          break;

        case AssetPackStatus.TRANSFERRING:
          // 100% downloaded and assets are being transferred.
          // Notify user to wait until transfer is complete.
          break;

        case AssetPackStatus.COMPLETED:
          // Asset pack is ready to use. Start the game.
          break;

        case AssetPackStatus.FAILED:
          // Request failed. Notify user.
          Log.e(TAG, assetPackState.errorCode());
          break;

        case AssetPackStatus.CANCELED:
          // Request canceled. Notify user.
          break;

        case AssetPackStatus.WAITING_FOR_WIFI:
        case AssetPackStatus.REQUIRES_USER_CONFIRMATION:
          if (!confirmationDialogShown) {
            assetPackManager.showConfirmationDialog(activityResultLauncher);
            confirmationDialogShown = true;
          }
          break;

        case AssetPackStatus.NOT_INSTALLED:
          // Asset pack is not downloaded yet.
          break;
        case AssetPackStatus.UNKNOWN:
          Log.wtf(TAG, "Asset pack status unknown")
          break;
      }
    }
}

In alternativa, puoi utilizzare il metodo getPackStates() per ottenere lo stato dei download in corso. AssetPackStates contiene l'avanzamento e lo stato del download, nonché eventuali codici di errore relativi a errori.

Accedere ai pacchetti di asset

Puoi accedere a un pacchetto di asset utilizzando le chiamate al file system dopo che la richiesta di download ha raggiunto lo stato COMPLETED. Utilizza il metodo getPackLocation() per ottenere la cartella principale del pacchetto di asset.

Gli asset vengono archiviati nella directory assets all'interno della directory principale del pacchetto di asset. Puoi ottenere il percorso della directory assets utilizzando il metodo di utilità assetsPath(). Utilizza il seguente metodo per ottenere il percorso di un asset specifico:

Kotlin

private fun getAbsoluteAssetPath(assetPack: String, relativeAssetPath: String): String? {
    val assetPackPath: AssetPackLocation =
      assetPackManager.getPackLocation(assetPack)
      // asset pack is not ready
      ?: return null

    val assetsFolderPath = assetPackPath.assetsPath()
    // equivalent to: FilenameUtils.concat(assetPackPath.path(), "assets")
    return FilenameUtils.concat(assetsFolderPath, relativeAssetPath)
}

Java

private String getAbsoluteAssetPath(String assetPack, String relativeAssetPath) {
    AssetPackLocation assetPackPath = assetPackManager.getPackLocation(assetPack);

    if (assetPackPath == null) {
        // asset pack is not ready
        return null;
    }

    String assetsFolderPath = assetPackPath.assetsPath();
    // equivalent to: FilenameUtils.concat(assetPackPath.path(), "assets");
    String assetPath = FilenameUtils.concat(assetsFolderPath, relativeAssetPath);
    return assetPath;
}

Altri metodi dell'API Play Asset Delivery

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

Annulla richiesta

Utilizza cancel() per annullare una richiesta di pacchetti di asset attivi. Tieni presente che questa richiesta è un'operazione di tipo "best effort".

Rimuovere un pacchetto di asset

Utilizza requestRemovePack() o removePack() per pianificare la rimozione di un pacchetto di asset.

Ottenere le posizioni di più pacchetti di asset

Utilizza getPackLocations() per eseguire query collettive sullo stato di più pacchetti di asset, in modo da visualizzare una mappa dei pacchetti di asset e delle relative posizioni. La mappa restituita da getPackLocations() contiene una voce per ogni pacchetto attualmente scaricato e aggiornato.

Passaggio successivo

Eseguire il test di Play Asset Delivery localmente e da Google Play.