Asset Delivery (native) integrieren

Folge der Anleitung in diesem Leitfaden, um über deinen C- und C++-Code auf die Asset-Packs deiner App zuzugreifen.

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

Für native Apps entwickeln

So binden Sie Play Asset Delivery in das Android App Bundle Ihres Projekts ein: Sie müssen Android Studio nicht verwenden, um diese Schritte auszuführen.

Hinweis: Eine Anleitung finden Sie im Codelab Play Asset Delivery in nativen Spielen 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. Erstelle im obersten Verzeichnis deines 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, Ziffern 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 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. Erstelle im Asset-Pack-Verzeichnis das folgende Unterverzeichnis: src/main/assets.

7. Lege die Assets im Verzeichnis src/main/assets ab. Sie können hier auch Unterverzeichnisse erstellen. Die Verzeichnisstruktur Ihrer 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 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/ für Sie aus.

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

In die Play Asset Delivery-Bibliothek einbinden

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

Hinweis: Für den Zugriff auf install-time-Asset-Packs wird eine andere API verwendet 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 stellt die C-Header-Datei play/asset_pack.h bereit, mit der Asset-Packs angefordert, Downloads verwaltet und Assets aufgerufen werden können.

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.16.0.zip

1. Führen Sie eine der folgenden Aktionen aus:

   • Installieren Sie Android Studio Version 4.0 oder höher. Installieren Sie über die Benutzeroberfläche des SDK-Managers die Android SDK-Plattformversion 10.0 (API-Level 29).
   • 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 neuesten Versionen von CMake und dem 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 extrahieren Sie sie in Ihr Projekt.

   Downloadlink	Größe	SHA-256-Prüfsumme
   play-core-native-sdk-1.16.0.zip	54,8 MiB	008b8fedc6179a6dc6ccc21af75591afc7036f78f3d5559d844f1b923934fef0

4. Aktualisieren Sie die Datei build.gradle 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.6.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.6.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 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
           ...)
   

Datenerfassung

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 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 aus der Datei „build.gradle“.

Diese Datenerhebung im Zusammenhang mit Ihrer Nutzung des Play Core Native SDK und die Verwendung der erhobenen Daten durch Google erfolgen 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

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 und On-Demand-Lieferung

In den folgenden Abschnitten wird beschrieben, wie du die API initialisierst, Informationen zu Asset-Packs vor dem Herunterladen abrufst, die API aufrufst, um den Download zu starten, und auf die heruntergeladenen Packs zugreifst. Diese Abschnitte gelten für fast-follow- und on-demand-Asset-Packs.

App-Start

Rufe immer AssetPackManager_init() auf, um die Asset Pack API zu initialisieren, bevor du eine andere Funktion aufrufst. Prüfen Sie, ob Fehlercodes für Asset-Packs 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()

Downloadinformationen zu Asset-Packs abrufen

In Apps muss die Größe des Downloads offengelegt werden, bevor das Asset-Pack abgerufen wird. Verwende die Funktion AssetPackManager_requestInfo(), um eine asynchrone Anfrage zur Größe des Downloads und zum Status des Downloads zu starten. Verwende dann AssetPackManager_getDownloadState(), um den Downloadstatus abzufragen (rufe diese Funktion beispielsweise einmal pro Frame in deiner Spielschleife auf). Wenn eine Anfrage fehlschlägt, prüfen Sie die Fehlercodes für Asset-Packs.

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

Verwende AssetPackManager_requestDownload(), um ein Asset-Paket zum ersten Mal herunterzuladen oder um ein Update für ein Asset-Paket 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 Android-Systembenachrichtigungsleiste 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 dem WLAN verbunden ist, wird der Download erst gestartet, wenn der Nutzer ausdrücklich zustimmt, den Download über eine mobile Datenverbindung fortzusetzen. Wenn der Download groß ist und der Nutzer die WLAN-Verbindung verliert, wird der Download pausiert und es ist eine ausdrückliche Einwilligung erforderlich, um den Download über eine mobile Datenverbindung fortzusetzen. Ein pausiertes Paket hat den Status WAITING_FOR_WIFI. Verwenden Sie Folgendes, um den UI-Ablauf auszulösen, mit dem der Nutzer zur Einwilligung aufgefordert 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 akzeptiert, das mit AssetPackManager_showConfirmationDialog() angezeigt wird. Dieser Status kann auftreten, wenn die App von Google Play nicht erkannt wird. Beachten Sie, dass der Aufruf von AssetPackManager_showConfirmationDialog() in diesem Fall dazu führt, dass die App aktualisiert wird. Fordern Sie die Assets nach der Aktualisierung noch einmal an.

Auf Asset-Packs zugreifen

Sie können über Dateisystemaufrufe auf ein Asset-Paket zugreifen, nachdem die Downloadanfrage den Status COMPLETED erreicht hat. Jedes Asset-Pack wird in einem separaten Verzeichnis im internen Speicher der App gespeichert. Verwenden Sie AssetPackManager_getAssetPackLocation(), um einen AssetPackLocation 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-Paket wird als APK installiert. Informationen zum Zugriff auf diese Assets finden Sie unter Auslieferung bei der Installation.
• 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);
}

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

Hinweis :Verlassen Sie sich nicht auf im Cache gespeicherte Asset-Pack-Speicherorte zwischen App-Starts. 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

Verwenden Sie AssetPackManager_cancelDownload(), um eine aktive Asset-Pack-Anfrage abzubrechen. Beachten Sie, dass diese Anfrage ein Best-Effort-Vorgang ist.

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