集成资产交付 (原生)

使用本指南中的步骤从您的 C 和 C++ 代码访问应用的资产包。

示例 集成代码 在 GitHub 上可用。

构建原生应用

按照以下步骤将 Play Asset Delivery 构建到项目的 Android 应用包中。您无需使用 Android Studio 执行这些步骤。

1. 将项目 build.gradle 文件中的 Android 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. 在项目的 app 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. 使用 Gradle 构建 Android 应用包。在生成的应用包中，根级目录现在包含以下内容

   • asset-pack-name/manifest/AndroidManifest.xml：配置资产包的标识符和交付模式
   • asset-pack-name/assets/your-asset-directories：包含作为资产包一部分交付的所有资产的目录

   Gradle 为每个资产包生成清单，并为您输出 assets/ 目录。

9. （可选）配置应用包以支持不同的 纹理压缩格式。

与 Play Asset Delivery 库集成

您根据要访问的资产包的交付类型实现此 API。以下流程图显示了这些步骤。

图 1. 访问资产包的流程图

Play Core Native SDK 提供 C 头文件 play/asset_pack.h 用于请求资产包、管理下载和访问资产。

为 Play Core Native SDK 设置开发环境

1. 执行以下任一操作

   • 安装Android Studio 4.0 或更高版本。使用 SDK 管理器 UI 安装 Android SDK 平台版本 10.0（API 级别 29）。
   • 安装Android SDK 命令行工具并使用sdkmanager安装 Android SDK 平台版本 10.0（API 级别 29）。

2. 通过使用SDK 管理器安装最新的 CMake 和 Android 原生开发工具包 (NDK) 来准备 Android Studio 以进行原生开发。有关创建或导入原生项目的更多信息，请参阅NDK 入门指南。

3. 下载 zip 文件并将其解压缩到您的项目旁边。

   下载链接	大小	SHA-256 校验和
   play-core-native-sdk-1.15.3.zip	37.8 MiB	9db60185185342f28d2c278b60222333608c67bc022e458a25224eaea8c4c4b7

4. 更新应用程序的build.gradle 文件，如下所示

   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. 更新应用程序的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 原生 SDK 可能会收集与版本相关的数据，以允许 Google 改善产品，包括

• 应用的包名称
• 应用的包版本
• Play Core 原生 SDK 的版本

当您将应用包上传到 Play 控制台时，将收集这些数据。要选择退出此数据收集过程，请删除 build.gradle 文件中的$playcoreDir/playcore-native-metadata.jar 导入。

请注意，与您使用 Play Core 原生 SDK 相关的数据收集以及 Google 对收集到的数据的使用独立于 Google 在您将应用包上传到 Play 控制台时在 Gradle 中声明的库依赖项的收集。

安装时交付

配置为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 资源包。

应用启动

在调用任何其他函数之前，始终调用AssetPackManager_init() 来初始化资源包 API。检查任何资源包错误代码。

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

还要确保在ANativeActivityCallbacks的onPause() 和onResume() 中调用以下函数

• 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。有关如何使用此类型的说明，请参阅获取下载信息。

大型下载

如果下载大于 200MB 且用户未连接 Wi-Fi，则下载不会开始，直到用户明确同意使用移动数据连接继续下载。同样，如果下载量很大且用户断开 Wi-Fi 连接，则下载将暂停，并且需要明确同意才能使用移动数据连接继续下载。已暂停的包的状态为WAITING_FOR_WIFI。要触发 UI 流程以提示用户确认，请使用以下命令

• AssetPackManager_showConfirmationDialog()
• AssetPackManager_getShowConfirmationDialogStatus()

需要用户确认

如果包具有REQUIRES_USER_CONFIRMATION 状态，则在用户接受使用AssetPackManager_showConfirmationDialog() 显示的对话框之前，下载不会继续。如果 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() 计划删除资源包。

后续步骤

在本地和 Google Play 上测试 Play 资源交付。