Asset Delivery (native) integrieren

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

Beispielcode für die Integration ist auf GitHub verfügbar.

Für native Apps entwickeln

Führen Sie die folgenden Schritte aus, um Play Asset Delivery in das Android App Bundle Ihres Projekts einzubinden. Sie müssen Android Studio nicht verwenden, um diese Schritte auszuführen.

Hinweis :Eine Anleitung finden Sie im Codelab zur Verwendung von Play Asset Delivery in nativen Spielen.

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. Asset-Pack-Namen müssen mit einem Buchstaben beginnen und dürfen nur Buchstaben, Zahlen und Unterstriche enthalten.

3. Erstellen Sie im Asset-Pack-Verzeichnis eine build.gradle-Datei und fügen Sie den folgenden Code hinzu. Geben Sie den Namen des Asset-Packs und nur einen Bereitstellungstyp 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 Datei build.gradle der App 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 die Datei settings.gradle des Projekts alle Asset-Packs ein, die in Ihrem Projekt enthalten sind, wie unten gezeigt:

   // 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. Legen Sie Assets im Verzeichnis src/main/assets ab. Sie können hier auch Unterverzeichnisse erstellen. Die Verzeichnisstruktur für Ihre 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. 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 Bereitstellungsmodus des Asset-Packs.
   • asset-pack-name/assets/your-asset-directories: Verzeichnis, das alle Assets enthält, die als Teil des Asset-Packs bereitgestellt werden

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

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

In die Play Asset Delivery-Bibliothek einbinden

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

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

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

Das Play Core Native SDK enthält die C-Headerdatei play/asset_pack.h, mit der Asset-Packs angefordert, Downloads verwaltet und auf die Assets zugegriffen werden kann.

Entwicklungsumgebung für das Play Core Native SDK einrichten

Herunterladen Play Core Native SDK

Bevor Sie herunterladen können, müssen Sie den folgenden Nutzungsbedingungen zustimmen.

Nutzungsbedingungen

Last modified: September 24, 2020

1. By using the Play Core Software Development Kit, you agree to these terms in addition to the Google APIs Terms of Service ("API ToS"). If these terms are ever in conflict, these terms will take precedence over the API ToS. Please read these terms and the API ToS carefully.
2. For purposes of these terms, "APIs" means Google's APIs, other developer services, and associated software, including any Redistributable Code.
3. “Redistributable Code” means Google-provided object code or header files that call the APIs.
4. Subject to these terms and the terms of the API ToS, you may copy and distribute Redistributable Code solely for inclusion as part of your API Client. Google and its licensors own all right, title and interest, including any and all intellectual property and other proprietary rights, in and to Redistributable Code. You will not modify, translate, or create derivative works of Redistributable Code.
5. Google may make changes to these terms at any time with notice and the opportunity to decline further use of the Play Core Software Development Kit. Google will post notice of modifications to the terms at https://developer.android.com/guide/playcore/license. Changes will not be retroactive.

Ich habe die Nutzungsbedingungen gelesen und stimme ihnen zu.

Play Core Native SDK Play Core Native SDK

play-core-native-sdk-1.15.4.zip

1. Sie haben folgende Möglichkeiten:

   • Installieren Sie Android Studio 4.0 oder höher. Installieren Sie die Android SDK-Plattformversion 10.0 (API-Level 29) über die SDK Manager-Benutzeroberfläche.
   • 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 aktuelle Version von CMake und des 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.4.zip	39,6 MiB	92b43246860d4ce4772a3a0786212d9b4781920e112d81b93ca1c5ebd8da89cb

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

   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.3.0'
           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.3.0")
       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 versionsbezogene Daten erheben, damit Google das Produkt verbessern kann. Dazu gehören:

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

Diese Daten werden erhoben, wenn Sie Ihr App-Paket in die Play Console hochladen. Wenn Sie diese Datenerhebung deaktivieren möchten, entfernen Sie den $playcoreDir/playcore-native-metadata.jar-Import in der Datei „build.gradle“.

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

Bereitstellung bei der Installation

Als install-time konfigurierte Asset-Packs sind sofort beim Start der App 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-Bereitstellung

In den folgenden Abschnitten wird beschrieben, wie Sie die API initialisieren, wie Sie Informationen zu Asset-Packs abrufen, bevor Sie sie herunterladen, wie Sie die API aufrufen, um den Download zu starten, und wie Sie auf die heruntergeladenen Packs 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 vorhanden sind.

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

Achten Sie außerdem darauf, die folgenden Funktionen in onPause() und onResume() von ANativeActivityCallbacks aufzurufen:

• AssetPackErrorCode AssetPackManager_onPause()
• AssetPackErrorCode AssetPackManager_onResume()

Downloadinformationen zu Asset-Packs abrufen

Apps müssen die Größe des Downloads angeben, bevor das Asset-Pack abgerufen wird. Verwenden Sie die Funktion AssetPackManager_requestInfo(), um eine asynchrone Anfrage für die Größe des Downloads und dafür 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 Spielschleife auf). Wenn eine Anfrage fehlschlägt, sehen Sie sich die Fehlercodes für 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 intransparenten Typ AssetPackDownloadState als Ausgabepointer 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 ein Update eines 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 intransparenten Typ AssetPackDownloadState zurück. Informationen zur Verwendung dieses Typs finden Sie unter Downloadinformationen abrufen.

Hinweis :In der Benachrichtigungsleiste des Android-Systems wird der Downloadfortschritt für fast-follow- und on-demand-Asset-Packs angezeigt. Der Nutzer kann den Download jederzeit über diese Leiste abbrechen.

Große Downloads

Wenn der Download größer als 200 MB ist und der Nutzer nicht mit einem WLAN verbunden ist, wird der Download erst gestartet, wenn der Nutzer ausdrücklich seine Einwilligung dazu gibt, den Download über eine mobile Datenverbindung fortzusetzen. Wenn der Download groß ist und der Nutzer die WLAN-Verbindung verliert, wird der Download pausiert. Für die Fortsetzung über eine mobile Datenverbindung ist eine ausdrückliche Einwilligung erforderlich. Ein pausiertes Paket hat den Status WAITING_FOR_WIFI. Verwenden Sie Folgendes, um den UI-Ablauf auszulösen, in dem der Nutzer um 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. Beachten Sie, dass durch den Aufruf von AssetPackManager_showConfirmationDialog() in diesem Fall die App aktualisiert wird. Fordern Sie die Assets nach dem Update noch einmal an.

Auf Asset-Packs zugreifen

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

• ASSET_PACK_STORAGE_APK: Das Asset-Pack wird als APK installiert. Informationen zum Zugriff auf diese Assets finden Sie unter Bereitstellung zur Installationszeit.
• 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 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);
}

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

Hinweis :Verlassen Sie sich zwischen App-Starts nicht auf zwischengespeicherte Asset-Pack-Speicherorte. Die App sollte bei jedem Start prüfen, ob Asset-Packs vorhanden sind. Asset-Packs können durch App-Updates oder wenn der Nutzer die App-Daten löscht ungültig werden.

Andere Play Core API-Methoden

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

Anfrage abbrechen

Mit AssetPackManager_cancelDownload() können Sie eine aktive Asset-Pack-Anfrage abbrechen. Beachten Sie, dass diese Anfrage auf Best-Effort-Basis erfolgt.

Entfernung beantragen

Verwenden Sie AssetPackManager_requestRemoval(), um das Entfernen eines Asset-Packs zu planen.

Nächste Schritte

Play Asset Delivery lokal und über Google Play testen