Asset Delivery einbinden (Kotlin und Java)

Folgen Sie den Schritten in diesem Leitfaden, um über Ihre Java-Software auf die Asset-Packs Ihrer App zuzugreifen. Code.

Build für Kotlin und Java

Führe die folgenden Schritte aus, um Play Asset Delivery in die Android-App deines Projekts App Bundle aus. Sie müssen für diese Schritte nicht Android Studio verwenden.

Hinweis: Eine interaktive Anleitung finden Sie in der Play Asset Delivery im Codelab für native Spiele verwenden

1. Aktualisieren Sie die Version des Android-Gradle-Plug-ins in der build.gradle-Datei in 4.0.0 oder höher geändert.

2. Erstellen Sie im obersten Verzeichnis Ihres Projekts ein Verzeichnis für das Asset. packen. Dieser Verzeichnisname wird als Name des Asset-Packs verwendet. Asset-Pack-Namen muss mit einem Buchstaben beginnen und darf nur Buchstaben, Ziffern und Unterstriche enthalten.

3. Erstellen Sie im Verzeichnis des Asset-Packs eine build.gradle-Datei und fügen Sie den folgenden Code. Geben Sie den Namen des Asset-Packs und nur einen Zustellungstyp:

   Cool

   // 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. Füge in der App-Datei build.gradle des Projekts die Namen der einzelnen Asset-Packs hinzu in Ihrem Projekt verwenden:

   Cool

   // 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. Nehmen Sie in der Datei settings.gradle des Projekts alle Asset-Packs in Ihr wie unten dargestellt:

   Cool

   // 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. Erstellen Sie im Verzeichnis des Asset-Packs das folgende Unterverzeichnis: src/main/assets

7. Platzieren Sie Assets im Verzeichnis src/main/assets. Sie können auch Unterverzeichnisse ein. Die Verzeichnisstruktur für Ihre Anwendung sollte jetzt so aussehen:

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

8. Android App Bundle mit Gradle erstellen Im generierten App-Bundle enthält das Verzeichnis auf Stammverzeichnisebene jetzt Folgendes: Folgendes:

   • asset-pack-name/manifest/AndroidManifest.xml: Konfiguriert die Kennung und den Übermittlungsmodus des Asset-Packs
   • asset-pack-name/assets/your-asset-directories: Verzeichnis, das alle Assets enthält, die als Teil des Asset-Packs übermittelt wurden

   Gradle generiert das Manifest für jedes Asset-Pack und gibt die assets/ aus. für Sie erstellen.

9. Optional: Fügen Sie die Play Asset Delivery Library hinzu, wenn Sie die Fast-Follow- und On-Demand-Übermittlung verwenden möchten.

   Cool

   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. Optional: Konfigurieren Sie Ihr App Bundle so, dass es unterschiedliche Texturen unterstützt. Komprimierungsformaten.

Hinweis :Damit du deine App als App Bundle und nicht als eigenständiges APK ausführen kannst, auf die gebündelten Assets zugreifen. Sie können auch die Standardkonfiguration für Ausführung/Fehlerbehebung bearbeiten. die App als APK und nicht als Bundle bereitzustellen. Weitere Informationen finden Sie unter Erstelle und teste dein Android App Bundle.

In die Play Asset Delivery API einbinden

Play Asset Delivery Java API stellt die AssetPackManager Klasse zum Anfordern von Asset-Packs, zum Verwalten von Downloads und zum Zugreifen auf die Assets. Sie müssen Ihrem Projekt zuerst die Asset Delivery-Bibliothek von Google Play hinzufügen.

Du implementierst diese API je nach Art der Übermittlung des gewünschten Asset-Packs um darauf zuzugreifen. Diese Schritte sind im folgenden Flussdiagramm dargestellt.

Hinweis :Du verwendest für den Zugriff auf install-time-Asset-Packs eine andere API als fast-follow- und on-demand-Asset-Packs.

Abbildung 1: Flussdiagramm für den Zugriff auf Asset-Packs

Installationszeitpunkt

Als install-time konfigurierte Asset-Packs sind sofort in der App verfügbar Markteinführung. Verwenden Sie die Java- AssetManager API für den Zugriff auf Assets in diesem Modus ausgeliefert wird:

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

Schnelle Folgen- und On-Demand-Bereitstellung

In den folgenden Abschnitten wird beschrieben, wie Sie Informationen zu Asset-Packs erhalten, wie Sie die API aufrufen, um den Download zu starten, und wie Sie auf die heruntergeladenen Pakete zugreifen. Diese Abschnitte gelten für fast-follow und on-demand Asset-Packs.

Status prüfen

Jedes Asset-Pack wird in einem separaten Ordner im internen Speicher der App gespeichert. Verwenden Sie die Methode getPackLocation() Methode zum Ermitteln des Stammordners eines Asset-Packs. Diese Methode gibt das Ereignis folgende Werte:

Rückgabewert	Status
Ein gültiges AssetPackLocation-Objekt	Stammordner des Asset-Packs ist bereit für sofortigen Zugriff unter assetsPath()
null	Unbekanntes Asset-Pack oder unbekannte Assets sind nicht verfügbar

Hinweis :Zwischen App-Starts sollten die im Cache gespeicherten Asset-Pack-Standorte nicht verwendet werden. Die App sollte bei jeder Einführung überprüft werden, ob Asset-Packs vorhanden sind. Medienelement werden möglicherweise aufgrund von App-Updates ungültig oder wenn der Nutzer die App-Daten löscht.

Downloadinformationen zu Asset-Packs

Apps müssen vor dem Abrufen des Assets die Größe des Downloads angeben packen. Verwenden Sie die Methode requestPackStates() oder die getPackStates() um die Größe des Downloads zu bestimmen und zu ermitteln, ob das Paket bereits wird heruntergeladen.

Kotlin

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

Java

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

requestPackStates() ist eine Anhalten-Funktion, die einen AssetPackStates -Objekt, während getPackStates() eine asynchrone Methode ist, die ein Task<AssetPackStates>-Objekt zurückgibt. Die packStates() eines AssetPackStates-Objekts gibt Map<String, AssetPackState> zurück. Diese Karte enthält den Status jedes angeforderten Assets Paket mit dem Namen:

Kotlin

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

Java

Map<String, AssetPackState> AssetPackStates#packStates()

Die endgültige Anfrage sieht so aus:

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

Die folgenden AssetPackState die Größe des Asset-Packs, die bisher heruntergeladene Menge (falls angefordert) und dem bereits an die App überwiesenen Betrag:

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

Den Status eines Asset-Packs kannst du über das status() -Methode, die den Status als Ganzzahl zurückgibt, die einer Konstanten entspricht im Feld AssetPackStatus . Ein Asset-Pack, das noch nicht installiert ist, hat den Status AssetPackStatus.NOT_INSTALLED

Schlägt eine Anfrage fehl, verwenden Sie die Methode errorCode() -Methode, deren Rückgabewert einem konstanten Feld im AssetPackErrorCode .

Installieren

Verwenden Sie den requestFetch() oder fetch() um ein Asset-Pack zum ersten Mal herunterzuladen oder die Aktualisierung eines Asset-Pack:

Kotlin

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

Java

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

Diese Methode gibt ein AssetPackStates -Objekt, das eine Liste der Pakete sowie deren anfängliche Downloadstatus und -größe enthält. Wenn ein über requestFetch() oder fetch() angefordertes Asset-Pack bereits heruntergeladen wird, wird der Download zurückgegeben und kein weiterer Download gestartet wird.

Hinweis: In den meisten Fällen implementieren Sie eine listener, um den Download und wie im nächsten Abschnitt beschrieben.

Downloadstatus überwachen

Sie sollten eine AssetPackStateUpdatedListener um den Installationsstatus des Assets zu verfolgen Sets. Die Statusaktualisierungen sind pro Packung aufgeschlüsselt, um die Verfolgung des Status einzelner Asset-Packs. Du kannst jetzt verfügbare Asset-Packs verwenden bevor alle anderen Downloads für Ihre Anfrage abgeschlossen sind.

Kotlin

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

Java

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

Hinweis :Der Play Store löst automatisch den Download von fast-follow aus. nachdem der Nutzer die App installiert oder aktualisiert hat. Diese Pakete sind jedoch möglicherweise sofort einsatzbereit sein. Sie müssen den Status von fast-follow prüfen bei jeder App-Einführung. Wenn der Download läuft, überwachen Sie ihn mit einem Listener. Falls der Download abgebrochen oder angehalten wurde, können Sie ihn mit der Schaltfläche fetch(), wie im Abschnitt Installieren beschrieben.

Große Downloads

Ist der Download größer als 200 MB und der Nutzer ist nicht mit einem WLAN verbunden, wird der Download beginnt erst, wenn der Nutzer ausdrücklich seine Einwilligung erteilt hat, um mit der über eine mobile Datenverbindung herunterladen. Wenn der Download groß ist und Der Nutzer verliert die WLAN-Verbindung, der Download wird angehalten und es ist eine ausdrückliche Zustimmung erforderlich, können Sie eine mobile Datenverbindung verwenden. Ein pausiertes Paket hat den Status WAITING_FOR_WIFI Verwenden Sie showConfirmationDialog() .

Wenn die App diese Methode nicht aufruft, wird der Download angehalten und automatisch fortgesetzt werden, wenn der Nutzer wieder eine WLAN-Verbindung hat.

Erforderliche Nutzerbestätigung

Wenn ein Paket den Status REQUIRES_USER_CONFIRMATION hat, wird der Download nicht bis der Nutzer das mit showConfirmationDialog() Dieser Status kann auftreten, wenn die App von Google Play nicht erkannt wird, z. B. die App per Sideload geladen wurde. Beachten Sie, dass das Aufrufen showConfirmationDialog() führt in diesem Fall dazu, dass die App aktualisiert wird. Nach der Aktualisierung benötigen Sie um die Assets erneut anzufordern.

Im Folgenden sehen Sie eine Beispielimplementierung eines Listeners:

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

Alternativ können Sie den getPackStates() , um den Status aktueller Downloads abzurufen. AssetPackStates enthält den Downloadfortschritt, den Downloadstatus und etwaige Fehlercodes.

Auf Asset-Packs zugreifen

Nach der Downloadanfrage kannst du über Dateisystemaufrufe auf ein Asset-Pack zugreifen erreicht die COMPLETED Bundesstaat. Verwenden Sie die Methode getPackLocation() zum Abrufen des Stammordners des Asset-Packs.

Assets werden im Verzeichnis assets im Stammverzeichnis des Asset-Packs gespeichert -Verzeichnis. Sie können den Pfad zum Verzeichnis assets mit der Methode Convenience-Methode assetsPath() Verwenden Sie die folgende Methode, um den Pfad zu einem bestimmten Asset abzurufen:

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

Andere Methoden der Play Asset Delivery API

Im Folgenden finden Sie einige zusätzliche API-Methoden, die Sie in Ihrer App verwenden können.

Anfrage abbrechen

Verwenden Sie cancel() um eine aktive Asset-Pack-Anfrage abzubrechen. Bitte beachten Sie, dass diese Anfrage .

Asset-Pack entfernen

Verwenden Sie requestRemovePack() oder removePack() um die Entfernung eines Asset-Packs zu planen.

Standorte mehrerer Asset-Packs abrufen

Verwenden Sie getPackLocations() um den Status mehrerer Asset-Packs gleichzeitig abzufragen. Asset-Packs und ihre Standorte. Die von getPackLocations() zurückgegebene Karte enthält einen Eintrag für jedes Paket, das derzeit heruntergeladen wird und aktuell ist.

Nächster Schritt

Testen Sie Play Asset Delivery lokal und von Google Play