Integrare la pubblicazione degli asset (nativa)

Segui i passaggi in questa guida per accedere ai pacchetti di asset dell'app dal codice C e C++.

Il codice di integrazione di esempio è disponibile su GitHub.

Sviluppa per gli annunci nativi

Segui questi passaggi per creare Play Asset Delivery nell'Android App Bundle del tuo progetto. Non è necessario utilizzare Android Studio per eseguire questi passaggi.

1. Aggiorna la versione del plug-in Android per Gradle nel file build.gradle del progetto a 4.0.0 o versioni successive.

2. Nella directory di primo livello del tuo progetto, crea una directory per il pacchetto di asset. Il nome della directory viene utilizzato come nome del pacchetto di asset. I nomi dei pacchetti di asset devono iniziare con una lettera e possono contenere solo lettere, numeri e trattini bassi.

3. Nella directory del pacchetto di asset, crea un file build.gradle e aggiungi il codice seguente. Assicurati di specificare il nome del pacchetto di asset e un solo tipo di pubblicazione:

   // 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. Nel file build.gradle dell'app del progetto, aggiungi il nome di ogni pacchetto di asset nel progetto, come mostrato di seguito:

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

5. Nel file settings.gradle del progetto, includi tutti i pacchetti di asset nel progetto come mostrato di seguito:

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

6. Nella directory del pacchetto di asset, crea la seguente sottodirectory: src/main/assets.

7. Posiziona gli asset nella directory src/main/assets. Qui puoi creare anche subdirectory. La struttura della directory per l'app dovrebbe essere simile alla seguente:

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

8. Crea l'Android App Bundle con Gradle. Nell'app bundle generato, la directory a livello di directory principale ora include quanto segue:

   • asset-pack-name/manifest/AndroidManifest.xml: configura l'identificatore e la modalità di invio del pacchetto di asset
   • asset-pack-name/assets/your-asset-directories: directory contenente tutti gli asset pubblicati nell'ambito del pacchetto di asset

   Gradle genera il manifest per ogni pacchetto di asset e restituisce la directory assets/ per te.

9. (Facoltativo) Configura l'app bundle in modo che supporti diversi formati di compressione delle texture.

Integrazione con Play Asset Delivery Library

Implementi questa API in base al tipo di pubblicazione del pacchetto di asset a cui vuoi accedere. Questi passaggi sono mostrati nel diagramma di flusso seguente.

Figura 1. Diagramma di flusso per l'accesso ai pacchetti di asset

L'SDK nativo di base di Play fornisce il file di intestazione C play/asset_pack.h per richiedere i pacchetti di asset, gestire i download e accedere agli asset.

Configura l'ambiente di sviluppo per l'SDK nativo principale di Play

1. Esegui una delle seguenti operazioni:

   • Installa Android Studio versione 4.0 o successive. Utilizza l'interfaccia utente di SDK Manager per installare Android SDK Platform versione 10.0 (livello API 29).
   • Installa gli strumenti a riga di comando dell'SDK per Android e utilizza sdkmanager per installare Android SDK Platform versione 10.0 (livello API 29).

2. Prepara Android Studio per lo sviluppo nativo utilizzando SDK Manager per installare il più recente CMake e Android Native Development Kit (NDK). Per ulteriori informazioni sulla creazione o sull'importazione di progetti nativi, consulta la guida introduttiva all'NDK.

3. Scarica il file ZIP ed estrailo insieme al tuo progetto.

   Link di download	Dimensioni	Checksum SHA-256
   play-core-native-sdk-1.14.0.zip	36 MiB	782a8522d937848c83a715c9a258b95a3ff2879a7cd71855d137b41c00786a5e

4. Aggiorna il file build.gradle dell'app come mostrato di seguito:

   Alla moda

       // 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. Aggiorna i file CMakeLists.txt dell'app come mostrato di seguito:

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

Raccolta dei dati

L'SDK nativo principale di Play potrebbe raccogliere dati relativi alla versione per consentire a Google di migliorare il prodotto, tra cui:

• Nome pacchetto dell'app
• Versione pacchetto dell'app
• Versione di Core Native SDK di Play

Questi dati verranno raccolti quando caricherai il pacchetto dell'app in Play Console. Per disattivare questo processo di raccolta dei dati, rimuovi l'importazione $playcoreDir/playcore-native-metadata.jar nel file build.gradle.

Tieni presente che questa raccolta di dati relativa al tuo utilizzo dell'SDK nativo di base Play e all'utilizzo da parte di Google dei dati raccolti è separata e indipendente dalla raccolta da parte di Google delle dipendenze di libreria dichiarate in Gradle quando carichi il pacchetto di app in Play Console.

Consegna al momento dell'installazione

I pacchetti di asset configurati come install-time sono immediatamente disponibili al momento del lancio dell'app. Utilizza l'API NDK AAssetManager per accedere agli asset pubblicati in questa modalità:

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

Consegna rapida successiva e on demand

Le sezioni seguenti mostrano come inizializzare l'API, ottenere informazioni sui pacchetti di asset prima di scaricarli, come chiamare l'API per avviare il download e come accedere ai pacchetti scaricati. Queste sezioni si applicano ai pacchetti di asset fast-follow e on-demand.

Lancio dell'app

Chiama sempre AssetPackManager_init() per inizializzare l'API asset pack prima di chiamare qualsiasi altra funzione. Verifica la presenza di eventuali codici di errore del pacchetto di asset.

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

Assicurati inoltre di chiamare le seguenti funzioni in onPause() e onResume() di ANativeActivityCallbacks:

• AssetPackErrorCode AssetPackManager_onPause()
• AssetPackErrorCode AssetPackManager_onResume()

Ricevere informazioni per il download sui pacchetti di asset

Le app devono indicare le dimensioni del download prima di recuperare il pacchetto di asset. Utilizza la funzione AssetPackManager_requestInfo() per avviare una richiesta asincrona per la dimensione del download e se il pacchetto è già in fase di download. Quindi utilizza AssetPackManager_getDownloadState() per eseguire il polling per lo stato di download (ad esempio, chiama questa funzione una volta per frame nel ciclo di gioco). Se una richiesta non va a buon fine, controlla i codici di errore del pacchetto di asset.

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

La funzione AssetPackManager_getDownloadState() restituisce il tipo opaco AssetPackDownloadState come puntatore di output. Utilizza questo puntatore per richiamare le seguenti funzioni:

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

Installa

Utilizza AssetPackManager_requestDownload() per iniziare a scaricare un pacchetto di asset per la prima volta o per richiedere il completamento di un aggiornamento del pacchetto:

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

La funzione AssetPackManager_getDownloadState() restituisce il tipo opaco AssetPackDownloadState. Per informazioni su come utilizzare questo tipo, consulta Ottenere informazioni di download.

Download di grandi dimensioni

Se il download supera i 200 MB e l'utente non è connesso a una rete Wi-Fi, il download non inizierà finché l'utente non acconsente esplicitamente a procedere utilizzando una connessione dati mobili. Analogamente, se il download è di grandi dimensioni e l'utente perde la connessione Wi-Fi, il download viene messo in pausa e occorre il consenso esplicito per continuare utilizzando una connessione dati mobili. Un pacchetto in pausa ha lo stato WAITING_FOR_WIFI. Per attivare il flusso dell'interfaccia utente per richiedere il consenso all'utente, utilizza il seguente codice:

• AssetPackManager_showConfirmationDialog()
• AssetPackManager_getShowConfirmationDialogStatus()

Conferma utente richiesta

Se un pacchetto è nello stato REQUIRES_USER_CONFIRMATION, il download non procede finché l'utente non accetta la finestra di dialogo mostrata con AssetPackManager_showConfirmationDialog(). Questo stato può apparire se l'app non viene riconosciuta da Google Play. Tieni presente che, se chiami AssetPackManager_showConfirmationDialog() in questo caso, l'app viene aggiornata. Dopo l'aggiornamento, richiedi nuovamente gli asset.

Accedi ai pacchetti di asset

Puoi accedere a un pacchetto di asset utilizzando le chiamate al file system dopo che la richiesta di download raggiunge lo stato COMPLETED. Ogni pacchetto di asset è archiviato in una directory separata nella memoria interna dell'app. Utilizza AssetPackManager_getAssetPackLocation() per ottenere un AssetPackLocation per il pacchetto di asset specificato. Utilizza AssetPackLocation_getStorageMethod() in quella posizione per determinare il metodo di archiviazione:

• ASSET_PACK_STORAGE_APK: il pacchetto di asset è installato come APK. Per accedere a questi asset, consulta Pubblicazione al momento dell'installazione.
• ASSET_PACK_STORAGE_FILES: utilizza AssetPackLocation_getAssetsPath() per ottenere il percorso del file della directory contenente gli asset o null se gli asset non sono stati scaricati. Non modificare i file scaricati in questo percorso.

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

Una volta individuati gli asset, utilizza funzioni come fopen o ifstream per accedere ai file.

Altri metodi dell'API Play Core

Di seguito sono riportati alcuni metodi dell'API aggiuntivi che puoi utilizzare nella tua app.

Annulla richiesta

Utilizza AssetPackManager_cancelDownload() per annullare una richiesta di pacchetto di asset attiva. Questa richiesta è un'operazione best effort.

Richiedi rimozione

Utilizza AssetPackManager_requestRemoval() per pianificare la rimozione di un pacchetto di asset.

Passaggi successivi

Testa Play Asset Delivery in locale e da Google Play.