Asset-Auslieferung einbinden (nativ)

Folgen Sie der Anleitung in diesem Leitfaden, um über Ihren C- und C++-Code auf die Asset-Packs Ihrer App zuzugreifen.

Beispiel-Integrationscode ist auf GitHub verfügbar.

Für native Apps entwickeln

Führen Sie die folgenden Schritte aus, um die Play Asset Delivery in das Android-App-Bundle Ihres Projekts einzubinden. Sie müssen dazu 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-Paket. Dieser Verzeichnisname wird als Name des Asset-Pakets verwendet. Asset-Pack-Namen müssen mit einem Buchstaben beginnen und dürfen nur Buchstaben, Zahlen und Unterstriche enthalten.

3. Erstellen Sie im Verzeichnis des Asset-Pakets eine build.gradle-Datei und fügen Sie den folgenden Code hinzu. Gib den Namen des Asset-Pakets und nur einen Übermittlungstyp an:

   // 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 build.gradle-Datei der App des Projekts den Namen jedes Asset-Pakets 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 settings.gradle-Datei des Projekts alle Asset-Pakete in Ihr Projekt ein, wie unten gezeigt:

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

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

7. Lege die Assets im Verzeichnis src/main/assets ab. Hier können Sie auch Unterverzeichnisse erstellen. Die Verzeichnisstruktur Ihrer App sollte jetzt so aussehen:

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

8. Erstellen Sie das Android App Bundle mit Gradle. Im generierten App-Bundle enthält das Verzeichnis auf Stammebene jetzt Folgendes:

   • asset-pack-name/manifest/AndroidManifest.xml: Kennung und Bereitstellungsmodus des Asset-Pakets konfigurieren
   • asset-pack-name/assets/your-asset-directories: Verzeichnis mit allen Assets, die im Asset-Paket bereitgestellt werden

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

9. Optional: Konfigurieren Sie Ihr App-Bundle so, dass verschiedene Texturkomprimierungsformate unterstützt werden.

Play Asset Delivery Library einbinden

Du implementierst diese API entsprechend dem Bereitstellungstyp des Asset-Pakets, auf das du zugreifen möchtest. Diese Schritte sind im folgenden Flussdiagramm dargestellt.

Abbildung 1. Flussdiagramm für den Zugriff auf Asset-Pakete

Das Play Core Native SDK bietet die C-Headerdatei play/asset_pack.h zum Anfordern von Asset-Packs, zum Verwalten von Downloads und zum Zugriff auf die Assets.

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. Verwenden Sie die Benutzeroberfläche des SDK-Managers, um die Android SDK-Plattformversion 10.0 (API-Level 29) zu installieren.
   • Installieren Sie die Android SDK-Befehlszeilentools und verwenden Sie sdkmanager, um die Android SDK-Plattformversion 10.0 (API-Level 29) zu installieren.

2. Bereiten Sie Android Studio für die native Entwicklung vor, indem Sie mit dem SDK Manager die neueste Version von CMake und das Android Native Development Kit (NDK) 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 neben Ihrem Projekt.

   Downloadlink	Größe	SHA-256-Prüfsumme
   play-core-native-sdk-1.15.3.zip	37,8 MiB	9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

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

   Groovy

       // 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.1.0'
           implementation 'com.google.android.play:asset-delivery:2.2.2'
           implementation 'com.google.android.play:integrity:1.4.0'
           implementation 'com.google.android.play:review:2.0.2'
   
           // 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.1.0")
       implementation("com.google.android.play:asset-delivery:2.2.2")
       implementation("com.google.android.play:integrity:1.4.0")
       implementation("com.google.android.play:review:2.0.2")
   
       // 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 beschrieben:

   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 versionenbezogene 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 erfasst, wenn Sie Ihr App-Paket in die Play Console hochladen. Wenn Sie diese Datenerhebung deaktivieren möchten, entfernen Sie den Import von $playcoreDir/playcore-native-metadata.jar in der Datei „build.gradle“.

Hinweis: Diese Datenerhebung im Zusammenhang mit Ihrer Nutzung des Play Core Native SDK und die Verwendung der erhobenen Daten durch Google sind getrennt und unabhängig von der Erhebung von Bibliotheksabhängigkeiten durch Google, die in Gradle deklariert werden, wenn Sie Ihr App-Paket in die Play Console hochladen.

Bereitstellung bei der Installation

Asset-Pakete, die als install-time konfiguriert sind, sind beim Starten der App sofort verfügbar. Verwenden Sie die NDK AAssetManager API, um auf Assets zuzugreifen, die in diesem Modus bereitgestellt 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);

Fast-Follow- und On-Demand-Auslieferung

In den folgenden Abschnitten wird beschrieben, wie Sie die API initialisieren, wie Sie Informationen zu Asset-Packs vor dem Herunterladen abrufen, 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.

App-Start

Rufe immer AssetPackManager_init() auf, um die Asset-Paket-API zu initialisieren, bevor du eine andere Funktion aufrufst. Prüfe, ob Fehlercodes für Asset-Pakete vorliegen.

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

Außerdem müssen Sie die folgenden Funktionen in den onPause() und onResume() von ANativeActivityCallbacks aufrufen:

• AssetPackErrorCode AssetPackManager_onPause()
• AssetPackErrorCode AssetPackManager_onResume()

Downloadinformationen zu Asset-Packs abrufen

Apps müssen die Größe des Downloads offenlegen, bevor das Asset-Paket abgerufen wird. Verwende die Funktion AssetPackManager_requestInfo(), um eine asynchrone Anfrage zur Größe des Downloads und dazu zu starten, 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 Game-Schleife auf. Wenn eine Anfrage fehlschlägt, sieh dir die Fehlercodes für Asset-Pakete an.

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

Die Funktion AssetPackManager_getDownloadState() gibt den opaken Typ AssetPackDownloadState als Ausgabezeiger zurück. Mit diesem Verweis können Sie die folgenden Funktionen aufrufen:

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

Verwende AssetPackManager_requestDownload(), um ein Asset-Paket zum ersten Mal herunterzuladen oder ein Asset-Paket-Update anzufordern:

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 nicht mit einem WLAN verbunden ist, beginnt der Download erst, wenn der Nutzer ausdrücklich seine Einwilligung zum Fortsetzen des Downloads über eine mobile Datenverbindung erteilt. Wenn der Download groß ist und die WLAN-Verbindung des Nutzers unterbrochen wird, wird der Download pausiert und es ist eine ausdrückliche Einwilligung erforderlich, um mit einer mobilen Datenverbindung fortzufahren. Ein pausiertes Paket hat den Status WAITING_FOR_WIFI. Verwenden Sie Folgendes, um den UI-Ablauf auszulösen, 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 Google Play nicht erkannt wird. Hinweis: Wenn Sie in diesem Fall AssetPackManager_showConfirmationDialog() aufrufen, wird die App aktualisiert. Bitten Sie nach dem Update noch einmal um die Assets.

Auf Asset-Packs zugreifen

Sie können über Dateisystemaufrufe auf ein Asset-Pack zugreifen, nachdem die Downloadanfrage den Status COMPLETED erreicht hat. Jedes Asset-Paket wird in einem separaten Verzeichnis im internen Speicher der App gespeichert. Verwenden Sie AssetPackManager_getAssetPackLocation(), um einen AssetPackLocation für das angegebene Asset-Paket abzurufen. Verwenden Sie AssetPackLocation_getStorageMethod() an diesem Speicherort, um die Speichermethode zu ermitteln:

• ASSET_PACK_STORAGE_APK: Das Asset-Paket wird als APK installiert. Informationen zum Zugriff auf diese Assets finden Sie unter Übermittlung bei der Installation.
• ASSET_PACK_STORAGE_FILES: Mit AssetPackLocation_getAssetsPath() können Sie den Dateipfad zum Verzeichnis mit den Assets abrufen. Wenn die Assets nicht heruntergeladen wurden, ist der Wert „null“. Ändern Sie heruntergeladene Dateien in diesem Dateipfad nicht.

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

Wenn Sie die Assets gefunden haben, verwenden Sie Funktionen wie fopen oder ifstream, um auf die Dateien zuzugreifen.

Weitere Play Core API-Methoden

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

Anfrage abbrechen

Mit AssetPackManager_cancelDownload() können Sie einen aktiven Asset-Paket-Antrag abbrechen. Beachten Sie, dass diese Anfrage auf Best-Effort-Basis bearbeitet wird.

Entfernung beantragen

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

Nächste Schritte

Testen Sie die Play Asset Delivery lokal und bei Google Play.