Интеграция доставки наборов объектов (нативные игры)

Чтобы получить доступ к пакетам объектов приложения из кода C и C++, следуйте инструкциям в этом руководстве.

Пример кода интеграции доступен на GitHub.

Как создавать нативные объявления

Чтобы встроить Play Asset Delivery в набор Android App Bundle, выполните следующие действия: Для выполнения этих действий не требуется Android Studio.

1. Обновите версию плагина Android Gradle в файле build.gradle проекта до 4.0.0 или более поздней.

2. В каталоге верхнего уровня проекта создайте каталог для пакета объектов. Название каталога используется в качестве названия пакета объектов. Название пакета объектов должно начинаться с буквы и может содержать только буквы, цифры и символы подчеркивания.

3. В каталоге пакета объектов создайте файл build.gradle и добавьте в него следующий код: Укажите название пакета объектов и только один тип доставки:

   // 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. В файле build.gradle приложения добавьте название каждого пакета объектов в проекте, как показано ниже.

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

5. В файле settings.gradle проекта укажите все пакеты объектов, как показано ниже:

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

6. В каталоге пакета объектов создайте подкаталог src/main/assets.

7. Поместите объекты в каталог src/main/assets. Вы также можете создавать здесь подкаталоги. Структура каталогов приложения должна выглядеть следующим образом:

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

8. Как создать набор Android App Bundle с помощью Gradle В сгенерированном наборе App Bundle корневой каталог теперь содержит следующее:

   • asset-pack-name/manifest/AndroidManifest.xml – настраивает идентификатор и режим доставки пакета объектов.
   • asset-pack-name/assets/your-asset-directories – каталог, содержащий все объекты, которые поставляются в составе пакета объектов.

   Gradle генерирует манифест для каждого пакета объектов и создает каталог assets/.

9. При необходимости настройте поддержку разных форматов сжатия текстур в наборе App Bundle.

Интеграция с библиотекой Play Asset Delivery

Реализация API зависит от типа доставки пакета объектов, к которому вы хотите получить доступ. Эти шаги показаны на следующей блок-схеме.

Нативный SDK Play Core предоставляет заголовочный файл C play/asset_pack.h для запроса пакетов объектов, управления скачиваниями и доступа к объектам.

Как настроить среду разработки для Play Core Native SDK

1. Выполните одно из следующих действий:

   • Установите Android Studio версии 4.0 или более поздней. Установите Android SDK Platform версии 10.0 (уровень API 29) с помощью SDK Manager.
   • Установите инструменты командной строки Android SDK и используйте sdkmanager, чтобы установить Android SDK Platform версии 10.0 (уровень API 29).

2. Подготовьте Android Studio к нативной разработке. Для этого установите последние версии CMake и Android Native Development Kit (NDK) с помощью SDK Manager. Подробную информацию о создании и импорте нативных проектов можно найти в статье Начало работы с NDK.

3. Скачайте ZIP-файл и распакуйте его в папку проекта.

   Ссылка для скачивания	Размер	Контрольная сумма SHA-256
   play-core-native-sdk-1.16.0.zip	54,8 МиБ	008b8fedc6179a6dc6ccc21af75591afc7036f78f3d5559d844f1b923934fef0

4. Обновите файл build.gradle приложения, как показано ниже.

   Яркий

       // 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. Обновите файлы CMakeLists.txt приложения, как показано ниже.

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

Сбор данных

Play Core Native SDK может собирать данные о версии, чтобы мы могли улучшать продукт. К таким данным относятся:

• Название пакета приложения
• Версия пакета приложения.
• Версия Play Core Native SDK

Эти данные будут собраны, когда вы загрузите пакет приложения в Play Console. Чтобы отказаться от сбора данных, удалите импорт $playcoreDir/playcore-native-metadata.jar из файла build.gradle.

Обратите внимание, что сбор данных, связанный с использованием Play Core Native SDK, и использование компанией Google собранных данных не зависят от сбора данных о зависимостях библиотек, объявленных в Gradle, который выполняется, когда вы загружаете пакет приложения в Play Console.

Доставка при установке

Пакеты объектов, для которых задан режим install-time, доступны сразу после запуска приложения. Для доступа к объектам, которые передаются в этом режиме, используйте 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);

Быстрая доставка и доставка по запросу

В следующих разделах показано, как инициализировать API, получить информацию о пакетах объектов перед их скачиванием, вызвать API для начала скачивания и получить доступ к скачанным пакетам. Эти разделы относятся к пакетам объектов fast-follow и on-demand.

Запуск приложения

Чтобы инициализировать API пакета объектов, всегда вызывайте AssetPackManager_init() перед вызовом любой другой функции. Проверьте, нет ли кодов ошибок пакета объектов.

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

Также не забудьте вызвать следующие функции в onPause() и onResume() класса ANativeActivityCallbacks:

• AssetPackErrorCode AssetPackManager_onPause()
• AssetPackErrorCode AssetPackManager_onResume()

Как получить информацию о скачивании пакетов объектов

Перед скачиванием пакета объектов приложение должно сообщить пользователю размер файла. Используйте функцию AssetPackManager_requestInfo(), чтобы запустить асинхронный запрос для определения размера скачиваемого файла и того, скачивается ли уже пакет. Затем используйте AssetPackManager_getDownloadState(), чтобы запросить статус скачивания (например, вызывайте эту функцию один раз за кадр в игровом цикле). Если запрос не выполняется, проверьте коды ошибок пакета объектов.

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

Функция AssetPackManager_getDownloadState() возвращает непрозрачный тип AssetPackDownloadState в качестве указателя вывода. Используйте этот указатель для вызова следующих функций:

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

Установить

Используйте AssetPackManager_requestDownload(), чтобы начать скачивание пакета объектов или запросить завершение его обновления.

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

Функция AssetPackManager_getDownloadState() возвращает непрозрачный тип AssetPackDownloadState. Информацию о том, как использовать этот тип, можно найти в разделе Получение информации о скачивании.

Скачивание больших файлов

Если размер скачиваемого файла превышает 200 МБ и пользователь не подключен к сети Wi-Fi, скачивание не начнется, пока пользователь не даст явное согласие на скачивание с использованием мобильного интернета. Если скачивается большой файл и пользователь теряет подключение к Wi-Fi, скачивание приостанавливается и для его продолжения с использованием мобильного интернета требуется явное согласие. Приостановленный набор имеет статус WAITING_FOR_WIFI. Чтобы запустить процесс получения согласия пользователя, используйте следующий код:

• AssetPackManager_showConfirmationDialog()
• AssetPackManager_getShowConfirmationDialogStatus()

Требуется подтверждение пользователя

Если у пакета статус REQUIRES_USER_CONFIRMATION, скачивание не начнется, пока пользователь не примет диалоговое окно, показанное с помощью AssetPackManager_showConfirmationDialog(). Этот статус может появиться, если приложение не распознано Google Play. Обратите внимание, что вызов AssetPackManager_showConfirmationDialog() в этом случае приведет к обновлению приложения. После обновления запросите объекты снова.

Как получить доступ к пакетам объектов

Вы можете получить доступ к пакету объектов, используя вызовы файловой системы, после того как запрос на скачивание достигнет состояния COMPLETED. Каждый пакет объектов хранится в отдельном каталоге во внутренней памяти приложения. Используйте AssetPackManager_getAssetPackLocation(), чтобы получить AssetPackLocation для указанного пакета объектов. Используйте метод AssetPackLocation_getStorageMethod(), чтобы определить способ хранения:

• ASSET_PACK_STORAGE_APK – пакет объектов устанавливается как APK-файл. Чтобы получить доступ к этим объектам, ознакомьтесь с разделом Доставка при установке.
• ASSET_PACK_STORAGE_FILES. Используйте AssetPackLocation_getAssetsPath(), чтобы получить путь к каталогу, содержащему объекты, или null, если объекты не были скачаны. Не изменяйте скачанные файлы по этому пути.

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

Найдя объекты, используйте функции fopen или ifstream, чтобы получить доступ к файлам.

Другие методы Play Core API

Ниже приведены дополнительные методы API, которые вы можете использовать в своем приложении.

Отменить запрос

Чтобы отменить активный запрос пакета объектов, используйте AssetPackManager_cancelDownload(). Обратите внимание, что этот запрос выполняется по мере возможности.

Отправьте запрос на удаление

Чтобы запланировать удаление пакета объектов, используйте AssetPackManager_requestRemoval().

Дальнейшие действия

Протестируйте Play Asset Delivery локально и в Google Play.