Asset-Auslieferung einbinden (nativ)

Folgen Sie den Schritten in dieser Anleitung, um über Ihren C- und C++-Code auf die Asset-Packs Ihrer App zuzugreifen.

Auf GitHub ist ein Beispiel für den Integrationscode verfügbar.

Für native Anzeigen erstellen

Führe die folgenden Schritte aus, um Play Asset Delivery im 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-Packs verwendet. Namen von Asset-Packs müssen mit einem Buchstaben beginnen und dürfen 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 hinzu. Gib den Namen des Asset-Packs 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 App-Datei build.gradle des Projekts die Namen aller 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 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-Packs das folgende Unterverzeichnis: src/main/assets.

7. Platzieren Sie Assets im Verzeichnis src/main/assets. Hier können Sie 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 Stammverzeichnisebene 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-Packs übermittelt wurden

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

9. (Optional) Konfiguriere dein App Bundle so, dass es verschiedene Texturkomprimierungsformate unterstützt.

In die Play Asset Delivery-Bibliothek einbinden

Die Implementierung dieser API richtet sich nach dem Übermittlungstyp des Asset-Packs, auf das du zugreifen möchtest. Diese Schritte sind im folgenden Flussdiagramm dargestellt.

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

Das Play Core Native SDK enthält 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. Verwende die SDK Manager-UI, um Version 10.0 der Android SDK Platform (API-Level 29) zu installieren.
   • Installieren Sie die Android SDK-Befehlszeilentools und verwenden Sie sdkmanager, um Version 10.0 (API-Level 29) der Android SDK Platform zu installieren.

2. Bereiten Sie Android Studio für die native Entwicklung vor. Installieren Sie dazu mit dem SDK Manager das neueste CMake- und Android Native Development Kit (NDK). Weitere Informationen zum Erstellen oder Importieren von nativen Projekten findest du unter Erste Schritte mit dem NDK.

3. Lade die ZIP-Datei herunter und entpacke sie zusammen mit deinem 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:

   Cool

       // 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.3.0'
           implementation 'com.google.android.play:review:2.0.1'
   
           // 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.3.0")
       implementation("com.google.android.play:review:2.0.1")
   
       // 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 Core Native SDK

Diese Daten werden erhoben, wenn du dein App-Paket in die Play Console hochlädst. Wenn Sie diesen Datenerfassungsprozess deaktivieren möchten, entfernen Sie den Import $playcoreDir/playcore-native-metadata.jar in der Datei build.gradle.

Hinweis: Die Datenerhebung im Zusammenhang mit deiner Nutzung des Play Core Native SDK und der Nutzung der erhobenen Daten durch Google erfolgt separat und unabhängig von der Sammlung der Bibliotheksabhängigkeiten, die Google beim Hochladen deines App-Pakets in die Play Console in Gradle deklariert hat.

Installationszeitpunkt

Als install-time konfigurierte Asset-Packs sind sofort beim Start der App verfügbar. Verwende 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);

Schnelle Folgen- und On-Demand-Bereitstellung

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

App-Start

Rufen Sie immer AssetPackManager_init() auf, um die Asset-Pack-API zu initialisieren, bevor Sie eine andere Funktion aufrufen. Suchen Sie nach Fehlercodes für Asset-Packs.

#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()

Downloadinformationen zu Asset-Packs

Apps müssen die Größe des Downloads angeben, bevor das Asset-Pack abgerufen werden kann. Mit der Funktion AssetPackManager_requestInfo() können Sie eine asynchrone Anfrage zum Ermitteln der Größe des Downloads und der Information, ob das Paket bereits heruntergeladen wird, starten. 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, sehen Sie sich die Fehlercodes des Asset-Packs 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. 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

Verwenden Sie AssetPackManager_requestDownload(), um ein Asset-Pack zum ersten Mal herunterzuladen oder eine Aktualisierung des Asset-Packs anzufordern:

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

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

Große Downloads

Ist der Download größer als 200 MB und der Nutzer ist nicht mit einem WLAN verbunden, wird der Download erst gestartet, wenn der Nutzer dem Download über eine mobile Datenverbindung ausdrücklich zugestimmt hat. Wenn der Download sehr groß ist und der Nutzer die WLAN-Verbindung verliert, wird 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. Verwenden Sie folgenden Code, um den UI-Ablauf auszulösen, mit dem der Nutzer um Zustimmung 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 mit AssetPackManager_showConfirmationDialog() angezeigte Dialogfeld akzeptiert. Dieser Status kann auftreten, wenn die App von Google 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

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

• ASSET_PACK_STORAGE_APK: Das Asset-Pack ist 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 zu dem Verzeichnis abzurufen, das die Assets enthält, 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, verwenden Sie Funktionen wie fopen oder ifstream, um auf die Dateien zuzugreifen.

Andere Play Core API-Methoden

Im Folgenden 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. Bei dieser Anfrage handelt es sich um einen Best-Effort-Vorgang.

Entfernung beantragen

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

Nächste Schritte

Teste Play Asset Delivery lokal und bei Google Play.