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

В этом руководстве рассказывается, как получить доступ к пакетам объектов приложения из кода 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 зависит от типа доставки пакета объектов, к которому вы хотите получить доступ. Эти шаги показаны на следующей блок-схеме.

Схема работы с пакетами объектов для нативного кода

Рисунок 1. Блок-схема доступа к пакетам объектов

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

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

Скачать Play Core Native SDK

Перед загрузкой вы должны согласиться со следующими условиями.

Условия и положения

Last modified: September 24, 2020
  1. By using the Play Core Software Development Kit, you agree to these terms in addition to the Google APIs Terms of Service ("API ToS"). If these terms are ever in conflict, these terms will take precedence over the API ToS. Please read these terms and the API ToS carefully.
  2. For purposes of these terms, "APIs" means Google's APIs, other developer services, and associated software, including any Redistributable Code.
  3. “Redistributable Code” means Google-provided object code or header files that call the APIs.
  4. Subject to these terms and the terms of the API ToS, you may copy and distribute Redistributable Code solely for inclusion as part of your API Client. Google and its licensors own all right, title and interest, including any and all intellectual property and other proprietary rights, in and to Redistributable Code. You will not modify, translate, or create derivative works of Redistributable Code.
  5. Google may make changes to these terms at any time with notice and the opportunity to decline further use of the Play Core Software Development Kit. Google will post notice of modifications to the terms at https://developer.android.com/guide/playcore/license. Changes will not be retroactive.
Скачать Play Core Native SDK

play-core-native-sdk-1.16.0.zip

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

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

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

    Ссылка для скачивания Размер Контрольная сумма SHA-256
    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:

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

Перед скачиванием пакета объектов приложение должно сообщить пользователю размер файла. Используйте функцию 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. Чтобы запустить процесс получения согласия пользователя, используйте следующий код:

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

Если у пакета статус 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.