SDK对接文档

主题

华为 App Bundle 分包与发布 ​

官方文档 ​

  1. 发布应用（AppBundle）
  2. AAB 包测试指导
  3. Dynamic Ability 介绍
  4. Dynamic Ability SDK 集成
  5. 应用签名指南

与 Google Play 资源分包的区别 ​

重要

华为应用市场不支持 Play Asset Delivery，不能直接上传包含 com.android.asset-pack 模块的 AAB。华为分包应使用 Android App Bundle 的动态功能模块（Dynamic Feature Module）。

华为应用市场会根据设备的 CPU 架构、屏幕分辨率和资源配置拆分 AAB：

  • Android 7.0 以上的华为设备分发与设备匹配的 split APK。
  • Android 7.0 及以下的华为设备和非华为设备分发包含全部模块的 universal.apk。
  • 安装时分包使用 install-time，应用安装完成后即可读取模块资源。
  • 按需分包使用 on-demand，必须接入华为 Dynamic Ability SDK。本文只介绍安装时分包。

发布限制 ​

  • 当前仅支持在手机和大屏设备上发布 App Bundle 应用。
  • 所有动态功能模块必须设置 fusing=true，保证 universal.apk 包含全部模块。
  • AAB 中不能使用 Play Asset Delivery。
  • AGC 计算出的下载体积不能超过 150 MB。
  • 发布 AAB 前，应用必须加入华为应用签名计划并使用应用签名服务。

集成安装时分包 ​

以下示例将资源模块命名为 resource_pack。

1. 创建动态功能模块 ​

在项目根目录创建 resource_pack 模块，并在模块的 build.gradle 中使用动态功能插件：

groovy
plugins {
    id 'com.android.dynamic-feature'
}

android {
    namespace 'com.example.resource_pack'
}

dependencies {
    implementation project(':app')
}

2. 注册模块 ​

在应用模块 app/build.gradle 中添加动态功能模块：

groovy
android {
    // 其他配置省略
    dynamicFeatures = [':resource_pack']
}

在项目的 settings.gradle 中注册模块：

groovy
include ':app'
include ':resource_pack'

3. 配置安装时分发 ​

在 resource_pack/src/main/AndroidManifest.xml 中配置 install-time，并将 fusing 设置为 true：

xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:dist="http://schemas.android.com/apk/distribution">

    <dist:module
        dist:instant="false"
        dist:title="@string/resource_pack_name">
        <dist:delivery>
            <dist:install-time />
        </dist:delivery>
        <dist:fusing dist:include="true" />
    </dist:module>

</manifest>

TIP

如果旧版工程使用 dist:onDemand 属性，需要将其设置为 false，同时保留 <dist:fusing dist:include="true" />。

4. 放置资源 ​

将分包资源放入动态功能模块的 src/main/assets 目录：

text
app/
└── src/main/res/values/strings.xml
resource_pack/
├── build.gradle
└── src/main/
    ├── AndroidManifest.xml
    └── assets/
        └── your-resource-directories/

动态功能模块的标题资源必须定义在基础应用模块中。因此，app/src/main/res/values/strings.xml 至少需要包含 Manifest 中引用的模块名称：

xml
<resources>
    <string name="resource_pack_name">Resource Pack</string>
</resources>

安装时模块随应用一起安装，不需要调用 Play Asset Delivery API。应用启动后可通过 Android 的 AssetManager 读取 assets 中的资源。

构建与测试 ​

发布前必须同时验证 split APK 和 universal.apk，避免部分设备安装失败或资源缺失。

测试 split APK ​

使用 bundletool 将 AAB 生成设备拆分包：

bash
java -jar bundletool-all.jar build-apks \
  --bundle=app-release.aab \
  --output=app.apks \
  --ks=keystore.jks \
  --ks-key-alias=keystore

连接 Android 7.0 以上的华为设备后安装：

bash
adb devices
java -jar bundletool-all.jar install-apks --apks=app.apks

测试 universal APK ​

生成包含所有模块的通用包：

bash
java -jar bundletool-all.jar build-apks \
  --bundle=app-release.aab \
  --output=app-un.apks \
  --ks=keystore.jks \
  --ks-key-alias=keystore \
  --mode=universal

将 app-un.apks 后缀改为 .zip 并解压，获得 universal.apk。在 Android 7.0 及以下的华为设备或非华为设备上安装并验证：

bash
adb install universal.apk

两种包都需要检查应用能否正常启动、分包资源能否正常读取，以及资源路径是否与代码中的路径一致。

上传到 AppGallery Connect ​

  1. 登录 AppGallery Connect，进入“APP 与元服务”。
  2. 选择“Android”，点击需要发布的应用。
  3. 进入“分发 > 版本信息 > 准备提交”。
  4. 在“软件版本”中点击“软件包管理”，上传 AAB。
  5. 等待 AGC 完成重新签名、编译和校验，官方说明通常需要 2～5 分钟。
  6. 选择校验通过的软件包，完善发布信息后提交审核。

常见校验错误 ​

提示或现象处理方式
检测到模块设置为按需下载不需要按需下载时改为 install-time；确实需要按需下载时接入 Dynamic Ability SDK
fusing 未设置为 true为所有动态功能模块添加 <dist:fusing dist:include="true" />
检测到 Play Asset Delivery删除 com.android.asset-pack 模块，改用动态功能模块
软件包处理失败先使用 bundletool 验证 AAB 能否生成 split APK 和 universal APK，再重新上传
下载体积超过 150 MB缩减包内资源；需要按需下载时改用 Dynamic Ability 方案

WARNING

Google Play 与华为应用市场的 AAB 分包规则不能混用。如果同一 Android 工程需要同时发布两个市场，建议分别维护 Google PAD 构建配置和华为 Dynamic Feature 构建配置。