Intégrer Asset Delivery (code natif)

Suivez les étapes de ce guide pour accéder aux packs d'éléments de votre application à partir de votre code C ou C++.

Un exemple de code d'intégration est disponible sur GitHub.

Compiler pour du code natif

Procédez comme suit pour intégrer Play Asset Delivery dans le fichier Android App Bundle de votre projet. Vous n'avez pas besoin d'utiliser Android Studio pour effectuer cette procédure.

1. Mettez à jour le plug-in Android Gradle dans le fichier build.gradle de votre projet vers la version 4.0.0 ou ultérieure.

2. Dans le répertoire racine de votre projet, créez un répertoire pour le pack d'éléments. Ce nom de répertoire est utilisé comme nom du pack d'éléments. Les noms des packs d'éléments doivent commencer par une lettre et ne peuvent contenir que des lettres, des chiffres et des traits de soulignement.

3. Dans le répertoire du pack d'éléments, créez un fichier build.gradle et ajoutez-y le code suivant. Veillez à spécifier le nom du pack d'éléments et un seul type de distribution :

   // 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. Dans le fichier build.gradle de l'application du projet, ajoutez le nom de chaque pack d'éléments de votre projet comme indiqué ci-dessous :

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

5. Dans le fichier settings.gradle du projet, incluez tous les packs d'éléments de votre projet comme indiqué ci-dessous :

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

6. Dans le répertoire du pack d'éléments, créez le sous-répertoire suivant : src/main/assets.

7. Placez des éléments dans le répertoire src/main/assets. Vous pouvez aussi créer des sous-répertoires dans ce répertoire. La structure de répertoire de votre application devrait maintenant se présenter comme suit :

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

8. Compilez le package Android App Bundle avec Gradle. Dans l'app bundle généré, le répertoire racine inclut désormais les éléments suivants :

   • asset-pack-name/manifest/AndroidManifest.xml : configure l'identifiant et le mode de distribution du pack d'éléments.
   • asset-pack-name/assets/your-asset-directories : répertoire contenant tous les éléments distribués dans le pack d'éléments

   Gradle génère le fichier manifeste pour chaque pack d'éléments et fournit le répertoire assets/ pour vous.

9. (Facultatif) Configurez votre app bundle pour qu'il soit compatible avec différents formats de compression de texture.

Intégrer à la bibliothèque Play Asset Delivery

Vous implémentez cette API en fonction du type de distribution du pack d'éléments auquel vous souhaitez accéder. Ces étapes sont présentées dans l'organigramme suivant.

Figure 1. Organigramme illustrant l'accès aux packs d'éléments

Le SDK Play Core natif fournit le fichier d'en-tête C play/asset_pack.h pour demander des packs d'éléments, gérer les téléchargements et accéder aux éléments.

Configurer votre environnement de développement pour le SDK Play Core natif

1. Effectuez l'une des opérations suivantes :

   • Installez Android Studio version 4.0 ou ultérieure. À l'aide de l'interface utilisateur SDK Manager, installez la version 10.0 d'Android SDK Platform (niveau d'API 29).
   • Installez les outils de ligne de commande du SDK Android et utilisez sdkmanager pour installer la version 10.0 d'Android SDK Platform (niveau d'API 29).

2. Préparez Android Studio pour le développement natif en installant la dernière version de CMake et du kit de développement natif Android (NDK) à l'aide de SDK Manager. Pour en savoir plus sur la création ou l'importation de projets natifs, consultez Premiers pas avec le kit NDK.

3. Téléchargez le fichier ZIP et extrayez-le avec votre projet.

   Lien de téléchargement	Taille	Somme de contrôle SHA256
   play-core-native-sdk-1.15.3.zip	37,8 Mo	9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

4. Mettez à jour le fichier build.gradle de votre application comme indiqué ci-dessous :

   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. Mettez à jour les fichiers CMakeLists.txt de votre application comme indiqué ci-dessous :

   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
           ...)
   

Collecte des données

Le SDK natif Play Core peut collecter des données liées à la version pour permettre à Google d'améliorer le produit, y compris :

• Nom du package de l'application
• Version du package de l'application
• Version du SDK natif Play Core

Ces données seront collectées lorsque vous importerez votre package d'application dans la Play Console. Pour désactiver ce processus de collecte des données, supprimez l'importation $playcoreDir/playcore-native-metadata.jar dans le fichier build.gradle.

Notez que cette collecte de données liée à votre utilisation du SDK natif Play Core et l'utilisation par Google des données collectées sont des opérations distinctes et indépendantes de la collecte de dépendances de bibliothèque que Google déclare dans Gradle lorsque vous importez votre package d'application dans la Play Console.

Distribution au moment de l'installation

Les packs d'éléments configurés en tant que install-time sont disponibles immédiatement au lancement de l'application. À l'aide de l'API NDK AAssetManager, accédez aux éléments distribués dans ce mode :

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

Distribution rapide et à la demande

Les sections suivantes expliquent comment initialiser l'API, obtenir des informations sur les packs d'éléments avant de les télécharger, appeler l'API pour lancer le téléchargement et accéder aux packs téléchargés. Ces sections s'appliquent aux packs d'éléments fast-follow et on-demand.

Lancement de l'application

Appelez toujours AssetPackManager_init() pour initialiser l'API du pack d'éléments avant d'appeler une autre fonction. Recherchez les éventuels codes d'erreur du pack d'éléments.

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

Veillez également à appeler les fonctions suivantes dans les champs onPause() et onResume() de ANativeActivityCallbacks :

• AssetPackErrorCode AssetPackManager_onPause()
• AssetPackErrorCode AssetPackManager_onResume()

Obtenir des informations de téléchargement sur les packs d'éléments

Les applications doivent indiquer la taille du téléchargement avant la récupération du pack d'éléments. Utilisez la fonction AssetPackManager_requestInfo() pour lancer une requête asynchrone afin d'obtenir la taille du téléchargement et de déterminer si le package est déjà en cours de téléchargement ou non. Utilisez ensuite AssetPackManager_getDownloadState() pour interroger l'état de téléchargement (par exemple, appelez cette fonction une fois par frame dans votre boucle de jeu). Si une requête échoue, vérifiez les codes d'erreur du pack d'éléments.

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

La fonction AssetPackManager_getDownloadState() renvoie le type opaque AssetPackDownloadState en tant que pointeur de sortie. Servez-vous de ce pointeur pour appeler les fonctions suivantes :

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

Installer

Servez-vous de AssetPackManager_requestDownload() pour commencer à télécharger un pack d'éléments pour la première fois ou pour demander la mise à jour d'un pack d'éléments :

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

La fonction AssetPackManager_getDownloadState() renvoie le type opaque AssetPackDownloadState. Pour en savoir plus sur l'utilisation de ce type, consultez la section Obtenir des informations de téléchargement.

Téléchargements volumineux

Si le téléchargement fait plus de 200 Mo et que l'utilisateur n'est pas connecté à un réseau Wi-Fi, le téléchargement ne démarre pas tant que l'utilisateur n'a pas explicitement accepté de poursuivre le téléchargement via une connexion de données mobiles. De même, si le téléchargement est volumineux et que l'utilisateur perd la connexion au réseau Wi-Fi, le téléchargement est suspendu et l'utilisateur doit explicitement accepter de poursuivre le téléchargement à l'aide d'une connexion de données mobiles. Un pack mis en pause possède l'état WAITING_FOR_WIFI. Pour déclencher le flux de l'interface utilisateur invitant l'utilisateur à donner son consentement, utilisez le code suivant :

• AssetPackManager_showConfirmationDialog()
• AssetPackManager_getShowConfirmationDialogStatus()

Confirmation de l'utilisateur requise

Si un package affiche l'état REQUIRES_USER_CONFIRMATION, le téléchargement ne se poursuit pas tant que l'utilisateur n'a pas accepté la boîte de dialogue affichée avec AssetPackManager_showConfirmationDialog(). Cet état peut se produire si l'application n'est pas reconnue par Play. Notez que l'appel de AssetPackManager_showConfirmationDialog() dans ce cas entraîne la mise à jour de l'application. Une fois la mise à jour effectuée, demandez à nouveau les composants.

Accéder aux packs d'éléments

Vous pouvez accéder à un pack d'éléments à l'aide d'appels au système de fichiers, une fois que la requête de téléchargement a atteint l'état COMPLETED. Chaque pack d'éléments est stocké dans un répertoire distinct, dans la mémoire de stockage interne de l'application. Utilisez AssetPackManager_getAssetPackLocation() pour obtenir un AssetPackLocation pour le pack d'éléments spécifié. Utilisez AssetPackLocation_getStorageMethod() sur cet emplacement pour déterminer la méthode de stockage :

• ASSET_PACK_STORAGE_APK : le pack d'éléments est installé sous forme d'APK. Consultez la section Distribution au moment de l'installation pour accéder à ces éléments.
• ASSET_PACK_STORAGE_FILES : utilisez AssetPackLocation_getAssetsPath() pour obtenir un chemin d'accès au fichier contenant les éléments, ou la valeur "null" si les éléments n'ont pas été téléchargés. Ne modifiez pas les fichiers téléchargés dans ce chemin de fichier.

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

Une fois que vous avez trouvé les éléments, utilisez des fonctions telles que fopen ou ifstream pour accéder aux fichiers.

Autres méthodes de l'API Play Core

Voici quelques méthodes d'API supplémentaires que vous pouvez utiliser dans votre application.

Annuler la requête

Utilisez AssetPackManager_cancelDownload() pour annuler une requête active relative au pack d'éléments. Notez que cette requête est effectuée dans la mesure du possible.

Demander la suppression

Utilisez AssetPackManager_requestRemoval() pour planifier la suppression d'un pack d'éléments.

Étapes suivantes

Testez Play Asset Delivery en local et à partir de Google Play.