設定條件式提供功能

條件式提供功能可讓您設定特定裝置設定需求條件,讓系統在符合這些條件的情況下,於安裝應用程式時自動下載功能模組。舉例來說,您可以設定包含擴增實境 (AR) 功能的功能模組,並讓系統只在裝置支援 AR 的情況下,於安裝應用程式時下載該功能模組。

這項提供機制目前可讓您根據下列裝置設定,控制應用程式安裝時的模組下載行為:

如果裝置不符合您指定的所有需求條件,系統就不會在安裝應用程式時下載該模組。不過,應用程式之後可能會使用 Play Core 程式庫要求隨選下載模組

開始之前,請先確認您使用的是 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_* 常數的功能相同。如果您選取這個選項,請先在下拉式選單旁邊的欄位中輸入功能常數值的任何部分 (例如「藍牙」),然後選取畫面上顯示的其中一個建議。
      • 「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 以下版本,安裝時一律會納入啟用融合功能的功能模組。
免安裝即用 (<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>