配置按条件分发

通过按条件分发,您可以针对将在应用安装过程中自动下载的功能模块设置特定的设备配置要求。例如,您可以配置包含增强现实 (AR) 功能的功能模块,其仅供支持 AR 功能的设备在安装应用时可用。

此分发机制目前支持根据以下设备配置控制模块在应用安装时的下载情况:

如果设备不满足您指定的所有要求,相应模块便不会在应用安装时下载。不过,您的应用以后可以使用 Play Core SDK 来请求按需下载此模块

开始前,请确保您使用的是 Android Studio 3.5 或更高版本。下面几部分将向您介绍如何向功能模块添加对按条件分发的支持。

添加采用按条件分发选项的新模块

如需创建采用按条件分发选项的新功能模块,最简单的方法是通过 New Module 向导创建,具体步骤如下:

  1. 如需打开 New Module 对话框,请从菜单栏中依次选择 File > New > New Module
  2. 在 New Module 对话框中,选择 Dynamic Feature Module,然后点击 Next
  3. 像往常一样配置模块,然后点击 Next
  4. Module Download Options 部分中,完成以下操作:

    1. 指定最多包含 50 个字符的 Module title。例如,平台会在确认用户是否要下载模块时,使用此标题向用户标识该模块。因此,应用的基本模块必须将模块标题作为您能读懂的字符串资源纳入其中。使用 Android Studio 创建模块时,IDE 会为您将字符串资源添加到基本模块中,并在功能模块的清单中注入以下条目:

      <dist:module
          ...
          dist:title="@string/feature_title">
      </dist:module>
      
    2. Install-time inclusion 下的下拉菜单中,选择 Only include module at app install for devices with specified features,这样会创建只有在特定设备上安装应用时才会下载的模块,这些设备需具有您可以指定的特定配置,如设备功能或国家/地区。Android Studio 会在该模块的清单中注入以下内容以反映您的选择:

      <dist:module ... >
        <dist:delivery>
            <dist:install-time>
                <dist:conditions>
                    <!-- If you specify conditions, as described in the steps
                         below, the IDE includes them here. -->
                </dist:conditions>
            </dist:install-time>
        </dist:delivery>
      </dist:module>
      
    3. 如果您想限定模块自动下载所适用的国家/地区或最低 API 级别,请点击 Finish 以完成模块创建,然后参阅介绍如何根据国家/地区指定条件根据最低 API 级别指定条件的部分。否则,请点击 + device feature 添加设备为在安装应用时下载模块所需具备的功能。

    4. device-feature 旁边,从下拉菜单中选择以下选项之一,然后为其指定值:

      • Name:用于指定设备为了在安装应用时下载模块所需具备的硬件或软件功能。按条件分发所支持的功能与被 PackageManager 列为 FEATURE_* 常量的功能相同。如果您选择此选项,请先在下拉菜单旁边的字段中输入相应功能的常量值的任意部分(例如“bluetooth”),然后在所显示的建议中选择一个。
      • OpenGL ES Version:用于指定设备为在安装应用时下载模块所需的 OpenGL ES 版本。如果您选择此选项,请先在下拉菜单旁边的字段中输入相应版本(例如“0x00030001”),然后在所显示的建议中选择一个。
    5. 如果您想根据可用的设备功能添加多个条件,请针对您想指定的每个设备功能条件点击 + device feature

    6. 如果您希望此模块可提供给搭载 Android 4.4(API 级别 20)及更低版本的设备并包含在多 APK 中,请选中 Fusing 旁边的复选框。这意味着,您可以为此模块启用按需行为,也可以停用融合功能,以便从不支持下载和安装拆分 APK 的设备上将其省略。Android Studio 会在该模块的清单中注入以下内容来反映您的选择:

      <dist:module ...>
          <dist:fusing dist:include="true | false" />
      </dist:module>
      
  5. 模块下载选项配置完成后,请点击 Finish

请注意,Android Gradle 插件不支持从动态功能模块运行 lint。从相应的应用模块运行 lint 将在其动态功能模块上运行 lint,并将所有问题都包含在应用的 lint 报告中。

向现有功能模块添加按条件分发选项

您可以通过现有功能模块的清单,轻松向现有功能模块添加按条件分发选项。不过,您应该先了解按条件分发选项与您可能已启用的其他分发选项之间的兼容性

首先,您需要将清单迁移到新的 <dist:delivery> 元素。以下代码段是旧版语法的示例:

<!-- This is the old syntax. -->
<dist:module
  dist:title="@string/feature_title" dist:onDemand="true">
  <dist:fusing dist:include="true"/>
</dist:module>

上述分发选项现在按以下方式指定:

<dist:module
  dist:title="@string/feature_title">
  <dist:delivery>
      <dist:on-demand/>
  </dist:delivery>
  <dist:fusing dist:include="true"/>
</dist:module>

然后,您就可以根据设备功能添加按条件分发选项,如下所示:

<dist:module
    dist:title="@string/feature_title">
    <dist:delivery>
      <dist:on-demand/>
      <dist:install-time>
        <dist:conditions>
          <!-- Requires that the device support AR to download the module at
          app install-time.  -->
          <dist:device-feature dist:name="android.hardware.camera.ar"/>
        </dist:conditions>
      </dist:install-time>
    </dist:delivery>
    <dist:fusing dist:include="true"/>
</dist:module>

下面几部分介绍了其他按条件分发的选项,如按国家/地区或最低 API 级别分发。

与其他模块下载选项的兼容性

由于功能模块提供了多个选项以配置如何将每个功能分发给用户设备,因此了解按条件分发选项如何受其他设置的影响非常重要。下表总结了按条件分发选项与其他模块下载选项之间的兼容性。

模块下载选项 与按条件分发选项之间的兼容性
融合 (<dist:fusing dist:include="true"/>) 如果某个模块将此选项设为 true,Google Play 在将您的应用部署到搭载 API 级别 19 或更低版本的设备时,不会遵循您指定的按条件分发选项。也就是说,对于搭载 API 级别 19 或更低版本的设备,启用了融合选项的功能模块始终会在安装应用时下载。
支持免安装体验 (<dist:module dist:instant="true"/>) 支持免安装体验的功能模块不支持按条件分发选项。
按需 (<dist:on-demand/>) 默认情况下,如果您指定按条件分发选项,则模块也可按需提供。

根据国家/地区指定条件

通过按条件分发,您还可以指定在哪些国家/地区可以在安装应用时下载模块。指定此条件可能会很有用,比如您的模块实现在某些地区无法使用的付款方式时。

在此情况下,设备所在的国家/地区通常由用户在其 Google Play 账号中注册的账单邮寄地址决定。

如需为您的功能模块指定国家/地区,请在该模块的清单中添加以下内容。

<dist:conditions>
   <!-- Set to "true" to specify countries to exclude from downloading
   this module at app install-time. By default, modules are available
   for download to all user countries. -->
  <dist:user-countries dist:exclude="true">
    <!-- Specifies the two-letter  CLDR country code for regions that should
    not download the module at app install-time. -->
    <dist:country dist:code="CN"/>
    <dist:country dist:code="HK"/>
  </dist:user-countries>
</dist:conditions>

根据 API 级别指定条件

如果某个功能模块依赖于仅在特定 Android 平台版本上提供的 API,那么根据设备的 API 级别指定条件可能会很有用。

如需根据设备的最低或最高 API 级别以设置条件,请在功能模块的清单中添加以下内容。

<dist:conditions>
    <!-- Specifies the minimum API level that the device must satisfy
         in order to download your module at app install-time. The API level you
         specify must be greater or equal to the module's own minSdkVersion. -->
   <dist:min-sdk dist:value="21"/>
    <!-- Specifies the maximum API level that the device cannot exceed
         in order to download your module at app install-time. The API level you
         specify must be less than or equal to the module's own maxSdkVersion. -->
   <dist:max-sdk dist:value="24"/>
</dist:conditions>