Integrowanie dostarczania zasobów (reklamy natywne)

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

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

Tworzenie reklam natywnych

Aby skompilować dostawę zasobów Play w pakiecie aplikacji na Androida, wykonaj te czynności. Aby wykonać te czynności, nie musisz używać Android Studio.

1. Zaktualizuj wersję wtyczki Androida do obsługi Gradle w pliku build.gradle projektu na 4.0.0 lub nowszą.

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

3. W katalogu pakietu zasobów utwórz plik build.gradle i dodaj do niego ten kod: Pamiętaj, aby podać nazwę pakietu zasobów i tylko jeden typ przesyłania:

   // 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 aplikacji build.gradle projektu dodaj nazwę każdego pakietu komponentó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 dodaj wszystkie pakiety komponentów, jak pokazano poniżej:

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

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

7. Umieść zasoby w katalogu src/main/assets. Możesz tu też tworzyć podkatalogi. Struktura katalogu 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. Wygeneruj pakiet Android App Bundle za pomocą Gradle. W wygenerowanym pakiecie aplikacji katalog na poziomie katalogu głównego zawiera teraz:

   • asset-pack-name/manifest/AndroidManifest.xml: skonfiguruj identyfikator i tryb przesyłania pakietu komponentów.
   • 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 komponentów i wyprowadza domyślnie assets/ Katalog.

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

Integracja z Biblioteką komponentów Play Asset Delivery

Interfejs API jest implementowany zgodnie z typem dostawy pakietu zasobów, do którego chcesz uzyskać dostęp. Te kroki są pokazane na poniższym schemacie.

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

Pakiet SDK podstawowej biblioteki Play do aplikacji natywnych udostępnia plik nagłówka play/asset_pack.h w języku C, który służy do wysyłania żądań pakietów zasobów, zarządzania pobieraniem i dostępu do zasobów.

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

1. Wykonaj jedną z tych czynności:

   • Zainstaluj Android Studio w wersji 4.0 lub nowszej. Za pomocą interfejsu menedżera pakietu SDK zainstaluj pakiet Android SDK w wersji 10.0 (poziom interfejsu API 29).
   • Zainstaluj narzędzia wiersza poleceń pakietu Android SDK i użyj polecenia sdkmanager, aby zainstalować platformę pakietu Android SDK w wersji 10.0 (poziom interfejsu API 29).

2. Przygotuj Android Studio do tworzenia aplikacji natywnych, instalując za pomocą Menedżera pakietu SDK najnowszą wersję CMake i pakietu Native Development Kit (NDK) na Androida. Więcej informacji o tworzeniu i importowaniu projektów natywnych znajdziesz w artykule Pierwsze kroki z NDK.

3. Pobierz plik ZIP i rozpakuj go obok projektu.

   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 ten sposób:

   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. Zaktualizuj pliki CMakeLists.txt aplikacji w ten sposób:

   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. Te dane obejmują:

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

Te dane zostaną zebrane, gdy prześlesz pakiet aplikacji do Konsoli Play. Aby zrezygnować z zbierania danych, usuń import $playcoreDir/playcore-native-metadata.jar z pliku build.gradle.

Pamiętaj, że zbieranie danych związanych z użyciem przez Ciebie natywnego pakietu SDK Play Core i wykorzystywaniem przez Google zebranych danych jest odrębne i niezależne od zbierania przez Google zależności bibliotek zadeklarowanych w Gradle podczas przesyłania pakietu aplikacji do Konsoli Play.

Przesyłanie podczas instalacji

Pakiety komponentów skonfigurowane jako install-time są dostępne od razu po uruchomieniu aplikacji. Aby uzyskać dostęp do zasobów obsługiwanych 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 śledzenie i dostawy na żądanie

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

Uruchamianie aplikacji

Przed wywołaniem dowolnej innej funkcji zawsze wywołuj funkcję AssetPackManager_init(), aby zainicjować interfejs API pakietu zasobów. Sprawdź, czy występują jakieś kody błędów pakietu zasobów.

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

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

• AssetPackErrorCode AssetPackManager_onPause()
• AssetPackErrorCode AssetPackManager_onResume()

Pobieranie informacji o pakietach zasobów

Aplikacje muszą podawać rozmiar pliku do pobrania przed pobraniem pakietu zasobów. Użyj funkcji AssetPackManager_requestInfo(), aby rozpocząć żądanie asynchroniczne dotyczące rozmiaru pliku do pobrania i tego, 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 każdy frame 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 typ nieprzezroczysty AssetPackDownloadState jako wskaźnik wyjściowy. Za pomocą tego wskaźnika możesz wywoływać 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

Aby pobrać pakiet komponentów po raz pierwszy lub poprosić o jego aktualizację:AssetPackManager_requestDownload()

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

Funkcja AssetPackManager_getDownloadState() zwraca typ nieprzezroczysty AssetPackDownloadState. Informacje o używaniu tego typu znajdziesz w artykule Pobieranie danych.

Pobieranie dużych plików

Jeśli pobieranie jest większe niż 200 MB, a użytkownik nie korzysta z Wi-Fi, pobieranie nie rozpocznie się, dopóki użytkownik nie wyrazi wyraźnej zgody na kontynuowanie pobierania za pomocą połączenia z komórkową transmisją danych. Podobnie, jeśli pobieranie jest duże, a użytkownik straci połączenie Wi-Fi, pobieranie zostanie wstrzymane i do dalszego pobierania za pomocą mobilnej transmisji danych będzie wymagana wyraźna zgoda. Wstrzymany pakiet ma stanWAITING_FOR_WIFI. Aby wywołać proces w interfejsie użytkownika, który poprosi użytkownika o zgodę, użyj:

• AssetPackManager_showConfirmationDialog()
• AssetPackManager_getShowConfirmationDialogStatus()

Wymagane potwierdzenie użytkownika

Jeśli pakiet ma stan REQUIRES_USER_CONFIRMATION, pobieranie nie rozpocznie się, dopóki użytkownik nie zaakceptuje wyświetlonego okna AssetPackManager_showConfirmationDialog(). Ten stan może wystąpić, jeśli aplikacja nie jest rozpoznawana przez Google Play. Pamiętaj, że wywołanie funkcji AssetPackManager_showConfirmationDialog() spowoduje zaktualizowanie aplikacji. Po aktualizacji ponownie poproś o zasoby.

Dostęp do pakietów zasobów

Po tym, jak prośba o pobieranie osiągnie stan COMPLETED, możesz uzyskać dostęp do pakietu zasobów za pomocą wywołań systemu plików. Każdy pakiet zasobów jest przechowywany w oddzielnym katalogu w pamięci wewnętrznej aplikacji. Użyj parametru AssetPackManager_getAssetPackLocation(), aby uzyskać AssetPackLocationdla określonego pakietu komponentów. Użyj AssetPackLocation_getStorageMethod()w tym miejscu, aby określić metodę przechowywania:

• ASSET_PACK_STORAGE_APK: pakiet komponentów jest instalowany jako plik APK. Aby uzyskać dostęp do tych komponentów, zapoznaj się z informacjami na temat dostawy w czasie instalacji.
• ASSET_PACK_STORAGE_FILES: użyj parametru AssetPackLocation_getAssetsPath(), aby uzyskać ścieżkę pliku do katalogu zawierającego zasoby, lub null, jeśli zasoby nie zostały pobrane. Nie zmieniaj pobranych plików w tym katalogu.

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

Po znalezieniu zasobów użyj funkcji takich jak fopen lub ifstream, aby uzyskać dostęp do plików.

Inne metody interfejsu Play Core API

Oto kilka dodatkowych metod interfejsu API, których możesz używać w aplikacji.

Anuluj prośbę

Użyj opcji AssetPackManager_cancelDownload(), aby anulować prośbę o aktywne pakiety komponentów. Pamiętaj, że ta prośba jest realizowana zgodnie z zasadą „dokładamy wszelkich starań”.

Poproś o usunięcie

Użyj opcji AssetPackManager_requestRemoval(), aby zaplanować usunięcie pakietu zasobów.

Dalsze kroki

Testuj Play Asset Delivery lokalnie i z Google Play.