Integracja dostawy zasobów (format natywny)

Aby uzyskać dostęp do pakietów zasobów aplikacji z poziomu kodu C i C++, wykonaj czynności opisane w tym przewodniku.

Przykładowy kod integracji jest dostępny na GitHubie.

Tworzenie reklam natywnych

Aby wbudować Play Asset Delivery w pakiet aplikacji na Androida w projekcie, wykonaj te czynności. Aby wykonać te czynności, nie musisz używać Androida Studio.

1. Zaktualizuj wersję wtyczki Androida do obsługi Gradle w pliku build.gradle projektu do wersji 4.0.0 lub nowszej.

2. W katalogu najwyższego poziomu projektu utwórz katalog pakietu zasobów. Nazwa tego katalogu jest używana jako nazwa pakietu zasobów. Nazwy pakietów zasobów muszą zaczynać się od litery i mogą zawierać tylko litery, cyfry i podkreślenia.

3. W katalogu pakietu zasobów utwórz plik build.gradle i dodaj ten kod: Podaj nazwę pakietu komponentów i tylko jeden typ dostawy:

   // 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. W pliku build.gradle aplikacji projektu dodaj nazwy wszystkich pakietów zasobów w projekcie, jak pokazano poniżej:

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

5. W pliku settings.gradle projektu umieść wszystkie pakiety zasobów w projekcie, jak pokazano poniżej:

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

6. W katalogu pakietu komponentów utwórz ten podkatalog:src/main/assets

7. Umieść zasoby w katalogu src/main/assets. Możesz tu też tworzyć podkatalogi. Struktura katalogów aplikacji powinna teraz wyglądać tak:

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

8. Utwórz pakiet Android App Bundle za pomocą Gradle W wygenerowanym pakiecie aplikacji katalog najwyższego poziomu zawiera teraz te elementy:

   • asset-pack-name/manifest/AndroidManifest.xml: Konfiguruje identyfikator pakietu zasobów i tryb dostawy.
   • asset-pack-name/assets/your-asset-directories: Katalog zawierający wszystkie komponenty dostarczone w ramach pakietu komponentów

   Gradle generuje plik manifestu dla każdego pakietu zasobów i tworzy dla Ciebie katalog assets/.

9. (Opcjonalnie) Skonfiguruj pakiet aplikacji tak, aby obsługiwał różne formaty kompresji tekstur.

Integracja z biblioteką Play Asset Delivery

Ten interfejs API wdrażasz zgodnie z rodzajem przesyłania pakietu zasobów, do którego chcesz uzyskać dostęp. Te kroki są przedstawione na poniższym schemacie blokowym.

Rysunek 1. Schemat blokowy dostępu do pakietów komponentów

Pakiet SDK podstawowej biblioteki Play do aplikacji natywnych zawiera plik nagłówkowy C play/asset_pack.h, który umożliwia wysyłanie żądań dotyczących pakietów zasobów, zarządzanie pobieraniem i uzyskiwanie dostępu do zasobów.

Konfigurowanie środowiska programistycznego na potrzeby pakietu SDK podstawowej biblioteki Play do aplikacji natywnych

1. Wykonaj jedną z tych czynności:

   • Zainstaluj Android Studio w wersji 4.0 lub nowszej. Użyj interfejsu SDK Manager, aby zainstalować pakiet SDK do Androida w wersji 10.0 (API na poziomie 29).
   • Zainstaluj narzędzia wiersza poleceń pakietu Android SDK i użyj polecenia sdkmanager, aby zainstalować pakiet Android SDK Platform w wersji 10.0 (API na poziomie 29).

2. Przygotuj Android Studio do tworzenia aplikacji natywnych, używając Menedżera SDK do zainstalowania najnowszych wersji CMake i pakietu Android Native Development Kit (NDK). Więcej informacji o tworzeniu i importowaniu projektów natywnych znajdziesz w artykule Pierwsze kroki z NDK.

3. Pobierz plik ZIP i rozpakuj go w tym samym folderze co projekt.

   Link do pobrania	Rozmiar	Suma kontrolna SHA-256
   play-core-native-sdk-1.15.3.zip	37,8 MiB	9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

4. Zaktualizuj plik build.gradle aplikacji w sposób pokazany poniżej:

   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. Zaktualizuj pliki CMakeLists.txt aplikacji w sposób pokazany poniżej:

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

Zbieranie danych

Pakiet SDK podstawowej biblioteki Play do aplikacji natywnych może zbierać dane związane z wersją, aby umożliwić Google ulepszanie usługi. Dane te mogą obejmować:

• Nazwa pakietu aplikacji
• Wersja pakietu aplikacji
• Wersja pakietu SDK podstawowej biblioteki Play do aplikacji natywnych

Te dane będą zbierane, gdy prześlesz pakiet aplikacji do Konsoli Play. Aby zrezygnować z tego procesu zbierania danych, usuń import w pliku build.gradle.$playcoreDir/playcore-native-metadata.jar

Pamiętaj, że zbieranie danych związanych z korzystaniem przez Ciebie z natywnego pakietu SDK Play Core i wykorzystywanie tych danych przez Google to proces odrębny i niezależny od zbierania przez Google zależności bibliotek zadeklarowanych w Gradle podczas przesyłania pakietu aplikacji do Konsoli Play.

Przesyłanie podczas instalacji

Pakiety zasobów skonfigurowane jako install-time są dostępne natychmiast po uruchomieniu aplikacji. Aby uzyskać dostęp do zasobów udostępnianych w tym trybie, użyj interfejsu NDK AAssetManager API:

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

Szybkie i na żądanie przesyłanie

W kolejnych sekcjach dowiesz się, jak zainicjować interfejs API, jak uzyskać informacje o pakietach zasobów przed ich pobraniem, jak wywołać interfejs API, aby rozpocząć pobieranie, i jak uzyskać dostęp do pobranych pakietów. Te sekcje dotyczą pakietów zasobów fast-follow i on-demand.

Uruchamianie aplikacji

Zawsze wywołuj funkcję AssetPackManager_init(), aby zainicjować interfejs Asset Pack API przed wywołaniem jakiejkolwiek innej funkcji. Sprawdź, czy nie ma kodów błędów pakietu zasobów.

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

Pamiętaj też, aby wywołać te funkcje w przypadku onPause() i onResume() ANativeActivityCallbacks:

• AssetPackErrorCode AssetPackManager_onPause()
• AssetPackErrorCode AssetPackManager_onResume()

Pobieranie informacji o pobranych pakietach zasobów

Aplikacje muszą podać rozmiar pobieranego pakietu zasobów przed jego pobraniem. Użyj funkcji AssetPackManager_requestInfo(), aby rozpocząć asynchroniczne żądanie rozmiaru pobieranego pliku i sprawdzić, czy pakiet jest już pobierany. Następnie użyj funkcji AssetPackManager_getDownloadState(), aby sprawdzić stan pobierania (na przykład wywołuj tę funkcję raz na klatkę w pętli gry). Jeśli żądanie się nie powiedzie, sprawdź kody błędów pakietu zasobów.

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

Funkcja AssetPackManager_getDownloadState() zwraca nieprzezroczysty typ AssetPackDownloadState jako wskaźnik wyjściowy. Użyj tego wskaźnika, aby wywołać te funkcje:

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

Zainstaluj

Użyj AssetPackManager_requestDownload() aby rozpocząć pobieranie pakietu zasobów po raz pierwszy lub poprosić o aktualizację pakietu zasobów w celu ukończenia:

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

Funkcja AssetPackManager_getDownloadState() zwraca nieprzezroczysty typ AssetPackDownloadState. Informacje o tym, jak używać tego typu, znajdziesz w artykule Pobieranie informacji o pobranych plikach.

Pobieranie dużych plików

Jeśli pobieranie przekracza 200 MB, a użytkownik nie korzysta z Wi-Fi, pobieranie nie rozpocznie się, dopóki użytkownik nie wyrazi wyraźnej zgody na pobieranie przy użyciu komórkowego połączenia transmisji danych. Podobnie jeśli pobierany plik jest duży, a użytkownik utraci połączenie Wi-Fi, pobieranie zostanie wstrzymane i do kontynuowania pobierania przy użyciu mobilnej transmisji danych wymagana będzie wyraźna zgoda. Wstrzymany pakiet ma stanWAITING_FOR_WIFI. Aby wywołać interfejs, który poprosi użytkownika o zgodę, użyj tego kodu:

• AssetPackManager_showConfirmationDialog()
• AssetPackManager_getShowConfirmationDialogStatus()

Wymagane potwierdzenie użytkownika

Jeśli pakiet ma stan REQUIRES_USER_CONFIRMATION, pobieranie nie będzie kontynuowane, dopóki użytkownik nie zaakceptuje okna dialogowego wyświetlanego z AssetPackManager_showConfirmationDialog(). Ten stan może wystąpić, jeśli aplikacja nie jest rozpoznawana przez Google Play. Pamiętaj, że wywołanie funkcjiAssetPackManager_showConfirmationDialog() w tym przypadku spowoduje zaktualizowanie aplikacji. Po aktualizacji ponownie poproś o zasoby.

Dostęp do pakietów zasobów

Po osiągnięciu przez żądanie pobierania stanu COMPLETED możesz uzyskać dostęp do pakietu komponentów za pomocą wywołań systemu plików. Każdy pakiet zasobów jest przechowywany w osobnym katalogu w pamięci wewnętrznej aplikacji. Użyj AssetPackManager_getAssetPackLocation() aby uzyskać AssetPackLocation dla określonego pakietu komponentów. Użyj AssetPackLocation_getStorageMethod() w tej lokalizacji, aby określić metodę przechowywania:

• ASSET_PACK_STORAGE_APK: pakiet zasobów jest instalowany jako plik APK. Aby uzyskać dostęp do tych zasobów, zapoznaj się z sekcją Dostarczanie w momencie instalacji.
• ASSET_PACK_STORAGE_FILES: użyj AssetPackLocation_getAssetsPath() aby uzyskać ścieżkę pliku do katalogu zawierającego komponenty lub wartość null, jeśli komponenty nie zostały pobrane. Nie modyfikuj pobranych plików w tej ścieżce.

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

Gdy znajdziesz zasoby, użyj funkcji takich jak fopen lub ifstream, aby uzyskać dostęp do plików.

Inne metody interfejsu Play Core API

Oto dodatkowe metody interfejsu API, których możesz używać w aplikacji.

Anuluj prośbę

Użyj AssetPackManager_cancelDownload() aby anulować aktywną prośbę o pakiet komponentów. Pamiętaj, że ta prośba jest operacją wykonywaną w miarę możliwości.

Poproś o usunięcie

Użyj AssetPackManager_requestRemoval() do zaplanowania usunięcia pakietu zasobów.

Dalsze kroki

Testuj Play Asset Delivery lokalnie i w Google Play.