設定條件式提供功能

條件式提供功能可讓您設定特定裝置設定需求,讓系統在符合條件的情況下,於安裝應用程式時自動下載功能模組。舉例來說,您可以設定提供擴增實境 (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. 指定「Module title」,長度上限為 50 個半形字元。例如,平台會在確認使用者是否要下載該模組時,利用這個標題方便使用者識別該模組。因此,應用程式的基礎模組必須加入模組標題做為字串資源,以供翻譯。使用 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 版本」:您可以指定裝置在安裝期間下載模組所需的 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 級別。

與其他模組下載選項的相容性

由於功能模組提供多個選項來設定各項功能提供給使用者裝置的方式,因此請務必瞭解其他設定對條件式提供功能選項的影響。下表匯總條件式提供功能與其他模組下載選項的相容性。

模組下載選項 與條件式提供功能的相容性
Fusing (<dist:fusing dist:include="true"/>) 如果模組將這個選項設為「true」,Google Play 在將您的應用程式部署到搭載 API 級別 19 以下的裝置時,就不會遵循您所指定的條件式提供功能選項。也就是說,如果裝置搭載 API 19 以下版本,安裝時一律會納入啟用融合功能的功能模組。
Instant-enabled (<dist:module dist:instant="true"/>) 免安裝即用功能模組不支援條件式提供功能選項。
On demand (<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>