什么是用于按条件分发模块的设备定位?
借助设备定位,您可以根据设备的硬件向其分发按条件分发的功能模块。例如,您可以选择将某功能仅分发给高端设备,而不分发给无法使用该功能的设备,进而节省这些设备上的空间。这种做法基于 Play Feature Delivery 中的功能模块概念。正如下文所述,您可以定义定位条件(目前可基于 RAM、特定设备型号或可用系统功能来定义),并将模块定位到特定的设备组。
开发者流程
概括而言,如需将设备定位集成到现有应用中,您需要执行以下步骤:
- 开发一项您希望根据设备的硬件仅分发给一组设备的功能。
- 将此功能实现为功能模块。
- 在 AndroidManifest.xml 的模块条件部分,指定应将该模块分发给哪些设备组。
- 创建设备定位配置,告诉 Play 如何将您的功能模块分发给用户设备。
- 设置 Google Play Developer API(如果尚未完成此设置),您将使用该 API 将设备定位配置发送到 Play。
- 按步骤完成设备定位配置的创建。
- 将 AAB 文件上传到 Play,并进行测试以确保各项配置正确无误。
本文档将介绍如何使用 Android Gradle 插件添加设备定位,以便按条件分发模块。
创建通过设备定位按条件分发的功能模块
将功能模块添加到应用中
Play Feature Delivery 让您可以按条件分发或按需下载应用的某些功能,请阅读此处的相关概览。 将设备分配到提供的设备组,即可通过设备定位按条件将功能分发给组中的设备。
如需使用设备定位来按条件分发模块,您必须使用 bundletool
1.7.0 版及更高版本。为此,您需要为 Android Gradle 插件明确指定 bundletool 版本。可以在根 build.gradle
文件的 buildscript 部分进行此项指定:
buildscript {
dependencies {
classpath "com.android.tools.build:bundletool:1.7.0"
...
}
...
}
如需创建功能模块,请按照关于模块化 Android 应用的说明操作。
功能开发完成后,您可以在功能的 AndroidManifest.xml
中基于设备定位指定分发条件。您需要在 dist:module
元素的 dist:conditions
内提供设备组条件。点击此处可查看关于条件的一般信息。对于设备组,您可以使用新条件来指定应向其分发此功能的所有组:
<dist:device-groups>
<dist:device-group dist:name="..." />
<dist:device-group dist:name="..." />
...
</dist:device-groups>
例如,假设您已定义一个名为 _my_group1 的设备组(下文创建设备定位配置部分将介绍具体定义方式)。如果应将功能模块仅分发给属于 _my_group1 设备组的设备,其 AndroidManifest.xml
应如下所示:
<manifest ...>
...
<dist:module dist:title="...">
<dist:delivery>
<dist:install-time>
<dist:conditions>
<dist:device-groups>
<dist:device-group dist:name="my_group_1"/>
</dist:device-groups>
...
</dist:conditions>
</dist:install-time>
</dist:delivery>
</dist:module>
...
</manifest>
如果某个功能同时定位 _my_group1 和 _my_group2,其 AndroidManifest.xml
将如下所示:
<manifest ...>
...
<dist:module dist:title="...">
<dist:delivery>
<dist:install-time>
<dist:conditions>
<dist:device-groups>
<dist:device-group dist:name="my_group_1"/>
<dist:device-group dist:name="my_group_2"/>
</dist:device-groups>
...
</dist:conditions>
</dist:install-time>
</dist:delivery>
</dist:module>
...
</manifest>
完成后,您便可以构建 Android App Bundle (AAB) 文件了。
本地测试
在继续下一步之前,建议您在本地测试 app bundle,确保各项设置正确无误。使用 bundletool
,您可以在本地构建和测试应用,并明确指定正确的设备组。您需要先使用 build-apks
生成一组 .apks 文件,然后使用 install-apks
将应用部署到已连接的设备。此外,您还可以通过 device-groups
标志指定要进行安装的组。如需详细了解此本地测试方法,请点击此处。请注意,此页面尚未针对有关设备定位的内容进行更新,因此缺少 device-groups 标志。
bundletool build-apks --bundle=/path/to/app.aab --output=/path/to/app.apks --local-testingbundletool install-apks --apks=/path/to/app.apks --device-groups=my_group_1,my_group_2
替代方案:您也可以使用 extract-apks
为特定设备(使用 get-device-spec
并指定该设备的设备组)提取一组 APK。
bundletool get-device-spec --output=/path/to/device-spec.json --device-groups=my_group_1,my_group_2bundletool extract-apks --apks=/path/to/existing_APK_set.apks --output-dir=/path/to/device_specific_APK_set.apks --device-spec=/path/to/device-spec.json
通过 Google Play Developer API 创建设备定位配置
开始使用 Google Play Developer API(如果尚未开始使用)
如需配置设备定位(定义设备组),需要使用 Android Publisher API 将配置上传到 Google Play。您可以点击上面的链接详细了解该 API。若要开始使用该 API,需要按照以下几个步骤操作:
您可在此处找到 API 参考文档。稍后,如果您选择通过该 API 上传 build,需要使用 Edits
方法。此外,建议在使用该 API 之前先查看此页面。
使用 Device Targeting Configuration API
您可以使用以下 API 调用来创建设备定位配置:
创建设备定位配置
HTTP 请求 | POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs |
路径参数 | 不适用 |
请求正文 | 设备定位配置 |
响应正文 | 设备定位配置 |
设备定位配置对象
{
device_groups: [
{
name: string,
device_selectors: [
{
device_ram : {
min_bytes: integer
max_bytes: integer
},
included_device_ids: [
{
build_brand: string,
build_device: string
}
],
excluded_device_ids: [
{
build_brand: string,
build_device: string
}
],
required_system_features: [
{
name: string
}
],
forbidden_system_features: [
{
name: string
}
]
}
]
}
]
}
字段:
- device_tier_config_id(整数):与此设备定位配置对应的 ID
device_groups(对象):组定义
- name(字符串):设备组的名称(您定义的字符串 ID)
- device_selectors(对象):对属于该组的设备的设备要求。
- device_ram(对象):设备 RAM 要求
- min_bytes(整数):要求的最低 RAM(单位:字节)
- max_bytes(整数):要求的最高 RAM(单位:字节)
- included_device_ids(对象):此选择器中要包含的设备型号(每组最多 10000 个 device_ids)。设备需要在此列表中才能匹配该选择器。这是匹配整个选择器的必要但非充分条件(请参阅下文说明,了解如何在选择器中组合使用多项要求)。
- build_brand(字符串):设备制造商
- build_device(字符串):设备型号代码
- excluded_device_ids(对象):此选择器中要排除的设备型号(每组最多 10000 个 device_ids)。此列表中的设备即使符合该选择器中的所有其他要求,也不会匹配该选择器。
- build_brand(字符串):设备制造商
- build_device(字符串):设备型号代码
required_system_features(对象):设备想要包含在此选择器中所需要具备的功能。(每组最多 100 项功能)。设备需要具备此列表中的所有系统功能才能匹配该选择器。这是匹配整个选择器的必要但非充分条件(请参阅下文说明,了解如何在选择器中组合使用多项要求)。
系统功能参考
- name(字符串):系统功能
forbidden_system_features(对象):设备想要包含在此选择器中就不能具备的功能(每组最多 100 项功能)。设备如果具备此列表中的任何系统功能,即使符合该选择器中的所有其他要求,也不匹配该选择器。
系统功能参考
- name(字符串):系统功能
您可以通过以下任一种方式,使用 Google Play 管理中心的设备目录查找设备制造商和型号代码的正确格式:
使用设备目录检查各个设备,在下例中所示的位置找到制造商和型号代码(以 Google Pixel 4a 为例,制造商为“Google”,型号代码为“sunfish”)
下载受支持的设备的 CSV 文件,build_brand 和 build_device 字段分别表示制造商和型号代码。
例如,下面的组匹配 RAM 超过 4GB 的所有设备但排除 Pixel 5 (google redfin),另外还包括 Pixel 3(Google Blueline,其 RAM 不到 4GB)。
device_groups: [
{
name: "my_group_1",
device_selectors: [
{
device_ram: {
min_bytes: 4294967296
},
excluded_device_ids: [
{
build_brand: "google",
build_device: "redfin"
}
]
},
{
included_device_ids: [
{
build_brand: "google",
build_device: "blueline"
}
]
}
]
}
]
您可以将其理解为:
[ (RAM > 4GB) AND NOT (google redfin) ] OR [ (google blueline) ]
您可以先按照以下说明验证设备定位配置,然后再将其上传到 Google Play。
按 ID 获取设备定位配置
您可以使用以下调用按 ID 检索特定的设备定位配置:
HTTP 请求 | GEThttps://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs/{deviceTierConfigId} |
路径参数 | 不适用 |
请求正文 | 不适用 |
响应正文 | 设备定位配置 |
获取设备定位配置列表
您可以通过以下调用获取最近 10 个设备定位配置(或者,最好使用 page_token 查询参数指定一组 10 个设备定位配置):
HTTP 请求 | GEThttps://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs |
路径参数 | 不适用 |
查询参数 | page_token(可选)- 用于指定具体的一组 10 个 DTC。如果您创建的 DTC 超过 10 个,而您希望查看在最近 10 个 DTC 之前创建的 DTC,此参数就会非常有用。 |
请求正文 | 不适用 |
响应正文 | 设备定位配置列表
|
验证设备定位配置
bundletool
包含两个命令,可帮助您验证设备定位配置在上传到 Play 之前是否按预期运行。
使用 bundletool print-device-targeting-config
,您可以验证 JSON 文件的语法是否正确,并以更易于用户看懂的格式直观地呈现设备组。
bundletool print-device-targeting-config --config=mydtc.json
借助 bundletool evaluate-device-targeting-config
,您可以评估哪些组与特定设备匹配。将目标设备连接到工作站并使用 --connected-device
标志;或者,手动编译包含设备属性的 JSON 文件并通过 --device-properties
标志提供该文件。
bundletool evaluate-device-targeting-config --config=mydtc.json --connected-device
bundletool evaluate-device-targeting-config --config=mydtc.json --device-properties=deviceproperties.json
设备属性文件应该是遵循 DeviceProperties protobuf 结构的 JSON 文件。例如:
{
"ram": 2057072640,
"device_id": {
"build_brand":"google",
"build_device":"redfin"
},
"system_features": [
{
"name":"android.hardware.bluetooth"
},
{
"name":"android.hardware.camera"
}
]
}
将 Android App Bundle 文件上传到 Google Play
通过 API
您可以使用 Google Play Developer API 将 Android App Bundle 文件上传到 Google Play,并将特定的设备定位配置关联到您的 build。
此处简要介绍了 Edits 方法,还有关于如何发布到 Google Play 管理中心内不同轨道的深入示例(对于后一个链接,您需要使用适合 AAB 文件的 API,而非该页面中列出的适合 APK 的 API)。如需为 build 指定设备定位配置,需要在调用 edits.bundle.upload
方法时将配置 ID 添加到 deviceTierConfigId 查询参数中,如下所示:
https://androidpublisher.googleapis.com/upload/androidpublisher/v3/applications/{packageName}/edits/{editId}/bundles?deviceTierConfigId="{deviceTierConfigId}"
通过 Google Play 管理中心
您可以按照此处的说明上传 Android App Bundle 文件。系统会将最新 DTC 配置应用于您的 app bundle。
辅助示例
快速入门:使用 curl
以下示例(使用命令行工具 curl)首先创建新的设备定位配置,接着使用 Edits API 创建新修改,上传新 AAB 文件(将其与特定设备定位配置关联),设置轨道/发布配置,然后提交修改(从而公开更改内容)。确保您有以下内容的位置:
- 与您的 API 客户端相对应的密钥
- 您的应用的软件包名称
首先,创建一个设备定位配置,并记下调用成功后收到的 deviceTierConfigId。
curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST -H "Content-Type: application/json" -d "{ device_groups: [ { name: "my_group_1", device_selectors: [ { device_ram: { min_bytes: 4294967296 }, excluded_device_ids: [ { build_brand: "google", build_device: "redfin" } ] }, { included_device_ids: [ { build_brand: "google", build_device: "blueline" } ] } ] } ] }" https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
开始修改 - 您将获得该修改的 ID 和过期时间。请保存该 ID,用于接下来的调用。
curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits
上传 AAB 文件,将设备定位配置 (deviceTierConfigId) 指定为查询参数 - 如果调用成功,您将看到 build 的版本号、sha1 值和 sha256 值。请保存该版本号,用于下一个调用。
curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" --data-binary @$HOME/{aabFile} -H "Content-Type: application/octet-stream" -XPOST https://androidpublisher.googleapis.com/upload/androidpublisher/v3/applications/{packageName}/edits/{editID}/bundles?deviceTierConfigId="{deviceTierConfigId}
将 AAB 文件分配到所需轨道(出于测试目的,建议使用内部测试轨道,但您可以在此处详细了解不同的轨道),我们在这里只进行了简单发布,未提供版本说明,但您可以阅读此页面,详细了解何为分阶段发布、草稿版本和版本说明。如果这是您第一次使用 Publisher API,建议您将此创建为草稿版本,并在 Google Play 管理中心完成发布,以确保各项配置正确无误。
curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPUT -H "Content-Type: application/json" -d "{ releases: [{status: '{status}', versionCodes: ['{versionCode}'] }]}" https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits/{editID}/tracks/{track}
提交更改(请谨慎操作,因为此操作会将所有更改发布到 Play 中的所需轨道)
curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits/{editID}:commit