Asset-Auslieferung einbinden (nativ)

Anhand der Schritte in dieser Anleitung können Sie über Ihren C- und C++-Code auf die Asset-Packs Ihrer App zugreifen.

Ein Beispiel für Integrationscode ist auf GitHub verfügbar.

Für native Anzeigen erstellen

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

1. Aktualisieren Sie die Version des Android-Gradle-Plug-ins in der Datei build.gradle Ihres Projekts auf 4.0.0 oder höher.

2. Erstellen Sie im obersten Verzeichnis Ihres Projekts ein Verzeichnis für das Asset-Pack. Dieser Verzeichnisname wird als Name des Asset-Pakets verwendet. Namen von Asset-Paketen müssen mit einem Buchstaben beginnen und dürfen nur Buchstaben, Ziffern und Unterstriche enthalten.

3. Erstellen Sie im Asset-Pack-Verzeichnis eine build.gradle-Datei und fügen Sie den folgenden Code hinzu. Du musst den Namen des Asset-Packs und nur einen Übermittlungstyp angeben:

   // 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 ]"
       }
   }
   

4. Fügen Sie in der App-Datei build.gradle des Projekts den Namen jedes Asset-Packs in Ihrem Projekt hinzu, wie unten gezeigt:

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

5. Fügen Sie in der Datei settings.gradle des Projekts alle Asset-Packs in Ihrem Projekt ein, wie unten dargestellt:

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

6. Erstellen Sie im Asset-Pack-Verzeichnis das folgende Unterverzeichnis: src/main/assets.

7. Platzieren Sie Assets im Verzeichnis src/main/assets. Sie können hier auch Unterverzeichnisse erstellen. 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 Stammebene jetzt 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-Pakets übermittelt wurden

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

9. (Optional) Konfigurieren Sie Ihr App-Bundle so, dass es verschiedene Formate für die Texturkomprimierung unterstützt.

In die Play Asset Delivery Library einbinden

Sie implementieren diese API entsprechend dem Übermittlungstyp des Asset-Packs, auf das Sie zugreifen möchten. Diese Schritte sind im folgenden Flussdiagramm dargestellt.

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

Das Play Core Native SDK stellt die C-Header-Datei play/asset_pack.h bereit, um Asset-Packs anzufordern, Downloads zu verwalten und auf die Assets zuzugreifen.

Entwicklungsumgebung für das Play Core Native SDK einrichten

1. Sie haben folgende Möglichkeiten:

   • Installieren Sie Android Studio Version 4.0 oder höher. Installiere die Android SDK Platform-Version 10.0 (API-Level 29) über die SDK-Manager-Benutzeroberfläche.
   • Installiere die Android SDK-Befehlszeilentools und verwende sdkmanager, um die Android SDK Platform Version 10.0 (API-Ebene 29) zu installieren.

2. Bereiten Sie Android Studio für die native Entwicklung vor. Verwenden Sie dazu den SDK Manager, um das neueste CMake und Android Native Development Kit (NDK) zu installieren. Weitere Informationen zum Erstellen oder Importieren nativer Projekte finden Sie unter Erste Schritte mit dem NDK.

3. Laden Sie die ZIP-Datei herunter und entpacken Sie sie zusammen mit Ihrem Projekt.

   Downloadlink	Größe	SHA-256-Prüfsumme
   play-core-native-sdk-1.14.0.zip	36 MiB	782a8522d937848c83a715c9a258b95a3ff2879a7cd71855d137b41c00786a5e

4. Aktualisieren Sie die Datei build.gradle Ihrer App wie unten gezeigt:

   Groovig

       // App build.gradle
   
       plugins {
         id 'com.android.application'
       }
   
       // Define a path to the extracted Play Core SDK files.
       // If using a relative path, wrap it with file() since CMake requires absolute paths.
       def playcoreDir = file('../path/to/playcore-native-sdk')
   
       android {
           defaultConfig {
               ...
               externalNativeBuild {
                   cmake {
                       // Define the PLAYCORE_LOCATION directive.
                       arguments "-DANDROID_STL=c++_static",
                                 "-DPLAYCORE_LOCATION=$playcoreDir"
                   }
               }
               ndk {
                   // Skip deprecated ABIs. Only required when using NDK 16 or earlier.
                   abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
               }
           }
           buildTypes {
               release {
                   // Include Play Core Library proguard config files to strip unused code while retaining the Java symbols needed for JNI.
                   proguardFile '$playcoreDir/proguard/common.pgcfg'
                   proguardFile '$playcoreDir/proguard/gms_task.pgcfg'
                   proguardFile '$playcoreDir/proguard/per-feature-proguard-files'
                   ...
               }
               debug {
                   ...
               }
           }
           externalNativeBuild {
               cmake {
                   path 'src/main/CMakeLists.txt'
               }
           }
       }
   
       dependencies {
           // Import these feature-specific AARs for each Google Play Core library.
           implementation 'com.google.android.play:app-update:2.0.0'
           implementation 'com.google.android.play:asset-delivery:2.0.0'
           implementation 'com.google.android.play:integrity:1.0.1'
           implementation 'com.google.android.play:review:2.0.0'
   
           // Import these common dependencies.
           implementation 'com.google.android.gms:play-services-tasks:18.0.2'
           implementation files("$playcoreDir/playcore-native-metadata.jar")
           ...
       }
       

   Kotlin

   // App build.gradle
   
   plugins {
       id("com.android.application")
   }
   
   // Define a path to the extracted Play Core SDK files.
   // If using a relative path, wrap it with file() since CMake requires absolute paths.
   val playcoreDir = file("../path/to/playcore-native-sdk")
   
   android {
       defaultConfig {
           ...
           externalNativeBuild {
               cmake {
                   // Define the PLAYCORE_LOCATION directive.
                   arguments += listOf("-DANDROID_STL=c++_static", "-DPLAYCORE_LOCATION=$playcoreDir")
               }
           }
           ndk {
               // Skip deprecated ABIs. Only required when using NDK 16 or earlier.
               abiFilters.clear()
               abiFilters += listOf("armeabi-v7a", "arm64-v8a", "x86", "x86_64")
           }
       }
       buildTypes {
           release {
               // Include Play Core Library proguard config files to strip unused code while retaining the Java symbols needed for JNI.
               proguardFile("$playcoreDir/proguard/common.pgcfg")
               proguardFile("$playcoreDir/proguard/gms_task.pgcfg")
               proguardFile("$playcoreDir/proguard/per-feature-proguard-files")
               ...
           }
           debug {
               ...
           }
       }
       externalNativeBuild {
           cmake {
               path = "src/main/CMakeLists.txt"
           }
       }
   }
   
   dependencies {
       // Import these feature-specific AARs for each Google Play Core library.
       implementation("com.google.android.play:app-update:2.0.0")
       implementation("com.google.android.play:asset-delivery:2.0.0")
       implementation("com.google.android.play:integrity:1.0.1")
       implementation("com.google.android.play:review:2.0.0")
   
       // Import these common dependencies.
       implementation("com.google.android.gms:play-services-tasks:18.0.2")
       implementation(files("$playcoreDir/playcore-native-metadata.jar"))
       ...
   }
   

5. Aktualisieren Sie die CMakeLists.txt-Dateien Ihrer App wie unten gezeigt:

   cmake_minimum_required(VERSION 3.6)
   
   ...
   
   # Add a static library called “playcore” built with the c++_static STL.
   include(${PLAYCORE_LOCATION}/playcore.cmake)
   add_playcore_static_library()
   
   // In this example “main” is your native code library, i.e. libmain.so.
   add_library(main SHARED
           ...)
   
   target_include_directories(main PRIVATE
           ${PLAYCORE_LOCATION}/include
           ...)
   
   target_link_libraries(main
           android
           playcore
           ...)
   

Datenerhebung

Das Play Core Native SDK kann versionsbezogene Daten erheben, damit Google das Produkt verbessern kann. Dazu gehören:

• Paketname der App
• Paketversion der App
• Version des Play Core Native SDK

Diese Daten werden erhoben, wenn du dein App-Paket in die Play Console hochlädst. Wenn du diese Datenerhebung deaktivieren möchtest, entferne den $playcoreDir/playcore-native-metadata.jar-Import aus der Datei build.gradle.

Hinweis: Diese Datenerhebung im Zusammenhang mit Ihrer Nutzung des Play Core Native SDK und der Verwendung der erhobenen Daten durch Google ist unabhängig von der Sammlung von Bibliotheksabhängigkeiten, die Google beim Hochladen Ihres App-Pakets in die Play Console deklariert und in Gradle deklariert wird.

Installationszeitpunkt-Lieferung

Als install-time konfigurierte Asset-Packs sind sofort beim Start der App verfügbar. Mit der NDK AAssetManager API kannst du auf Assets zugreifen, die in diesem Modus ausgeliefert werden:

#include <android/asset_manager.h>
#include <android_native_app_glue.h>
...
AAssetManager* assetManager = app->activity->assetManager;
AAsset* asset = AAssetManager_open(assetManager, "asset-name", AASSET_MODE_BUFFER);
size_t assetLength = AAsset_getLength(asset);
char* buffer = (char*) malloc(assetLength + 1);
AAsset_read(asset, buffer, assetLength);

Schnelle Lieferung und On-Demand-Bereitstellung

In den folgenden Abschnitten wird beschrieben, wie Sie die API initialisieren, Informationen zu Asset-Packs vor dem Herunterladen abrufen, die API zum Starten des Downloads aufrufen und auf die heruntergeladenen Pakete zugreifen. Diese Abschnitte gelten für fast-follow- und on-demand-Asset-Packs.

App-Start

Rufen Sie immer AssetPackManager_init() auf, um die Asset Pack API zu initialisieren, bevor Sie eine andere Funktion aufrufen. Prüfen Sie, ob Asset-Pack-Fehlercodes vorliegen.

#include "play/asset_pack.h"
...
AssetPackErrorCode AssetPackManager_init(JavaVM* jvm, jobject android_context);

Außerdem müssen die folgenden Funktionen in onPause() und onResume() von ANativeActivityCallbacks aufgerufen werden:

• AssetPackErrorCode AssetPackManager_onPause()
• AssetPackErrorCode AssetPackManager_onResume()

Informationen zu Asset-Packs herunterladen

Apps müssen die Größe des Downloads offenlegen, bevor das Asset-Pack abgerufen wird. Mit der Funktion AssetPackManager_requestInfo() wird eine asynchrone Anfrage nach der Größe des Downloads und danach gestartet, ob das Paket bereits heruntergeladen wird. Verwenden Sie dann AssetPackManager_getDownloadState(), um den Downloadstatus abzufragen. Rufen Sie diese Funktion beispielsweise einmal pro Frame in Ihrer Spielschleife auf. Wenn eine Anfrage fehlschlägt, prüfen Sie die Asset-Pack-Fehlercodes.

AssetPackErrorCode AssetPackManager_requestInfo();      // Call once
AssetPackErrorCode AssetPackManager_getDownloadState(); // Call once per frame in your game loop

Die Funktion AssetPackManager_getDownloadState() gibt den intransparenten Typ AssetPackDownloadState als Ausgabezeiger zurück. Verwenden Sie diesen Zeiger, um die folgenden Funktionen aufzurufen:

AssetPackDownloadState* state;
AssetPackErrorCode error_code = AssetPackManager_getDownloadState(asset-pack-name, &state);
AssetPackDownloadStatus status = AssetPackDownloadState_getStatus(state);
uint64_t downloadedBytes = AssetPackDownloadState_getBytesDownloaded(state);
uint64_t totalBytes = AssetPackDownloadState_getTotalBytesToDownload(state));
AssetPackDownloadState_destroy(state);

Installieren

Mit AssetPackManager_requestDownload() kannst du zum ersten Mal ein Asset-Pack herunterladen oder den Abschluss eines Asset-Packs anfordern:

AssetPackErrorCode AssetPackManager_requestDownload();  // Call once
AssetPackErrorCode AssetPackManager_getDownloadState(); // Call once per frame in your game loop

Die Funktion AssetPackManager_getDownloadState() gibt den intransparenten Typ AssetPackDownloadState zurück. Informationen zur Verwendung dieses Typs finden Sie unter Downloadinformationen abrufen.

Große Downloads

Wenn der Download größer als 200 MB ist und der Nutzer keine WLAN-Verbindung hat, wird der Download erst gestartet, wenn der Nutzer ausdrücklich seine Einwilligung für den Download über eine mobile Datenverbindung erteilt hat. Genauso wird bei einem großen Download der Download angehalten und es ist eine ausdrückliche Zustimmung erforderlich, um über eine mobile Datenverbindung fortzufahren. Ein pausiertes Paket hat den Status WAITING_FOR_WIFI. So löst du den UI-Ablauf aus, bei dem der Nutzer um seine Einwilligung gebeten wird:

• AssetPackManager_showConfirmationDialog()
• AssetPackManager_getShowConfirmationDialogStatus()

Erforderliche Nutzerbestätigung

Wenn ein Paket den Status REQUIRES_USER_CONFIRMATION hat, wird der Download erst fortgesetzt, wenn der Nutzer das Dialogfeld mit AssetPackManager_showConfirmationDialog() akzeptiert. Dieser Status kann auftreten, wenn die App von Play nicht erkannt wird. Wenn Sie in diesem Fall AssetPackManager_showConfirmationDialog() aufrufen, wird die Anwendung aktualisiert. Fordern Sie die Assets nach der Aktualisierung noch einmal an.

Auf Asset-Packs zugreifen

Sie können mithilfe von Dateisystemaufrufen auf ein Asset-Pack zugreifen, wenn die Downloadanfrage den Status COMPLETED erreicht. Jedes Asset-Pack wird in einem separaten Verzeichnis im internen Speicher der Anwendung gespeichert. Verwenden Sie AssetPackManager_getAssetPackLocation(), um ein AssetPackLocation-Element für das angegebene Asset-Pack abzurufen. Verwenden Sie AssetPackLocation_getStorageMethod() für diesen Speicherort, um die Speichermethode zu bestimmen:

• ASSET_PACK_STORAGE_APK: Das Asset-Pack wird als APK installiert. Informationen zum Zugriff auf diese Assets finden Sie unter Install-time Delivery.
• ASSET_PACK_STORAGE_FILES: Verwenden Sie AssetPackLocation_getAssetsPath(), um einen Dateipfad zum Verzeichnis mit den Assets abzurufen, oder null, wenn die Assets nicht heruntergeladen wurden. Ändern Sie keine heruntergeladenen Dateien in diesem Dateipfad.

AssetPackLocation* location;

AssetPackErrorCode error_code = AssetPackManager_getAssetPackLocation(asset-pack-name, &location);

if (error_code == ASSET_PACK_NO_ERROR) {
    AssetPackStorageMethod storage_method = AssetPackLocation_getStorageMethod(location);
    const char* assets_path = AssetPackLocation_getAssetsPath(location);
    AssetPackLocation_destroy(location);
}

Sobald Sie die Assets gefunden haben, können Sie mit Funktionen wie fopen oder ifstream auf die Dateien zugreifen.

Andere Play Core API-Methoden

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

Anfrage abbrechen

Verwenden Sie AssetPackManager_cancelDownload(), um eine aktive Asset-Pack-Anfrage abzubrechen. Beachten Sie, dass es sich bei dieser Anfrage um einen Best-Effort-Vorgang handelt.

Entfernung beantragen

Mit AssetPackManager_requestRemoval() kannst du das Entfernen eines Asset-Packs planen.

Nächste Schritte

Teste die Play Asset Delivery lokal und über Google Play.