條件模組裝置指定

什麼是條件模組裝置指定?

裝置指定功能可讓您根據裝置硬體,為裝置提供條件式功能模組。舉例來說,您可以選擇將某項功能提供給高階裝置,但不提供給無法使用該功能的裝置 (以便節省這類裝置的儲存空間)。這項功能是以 Play Feature Delivery 中的功能模組概念為基礎。您可以定義指定條件 (目前根據 RAM、特定裝置型號或可用的系統功能),並為特定裝置群組指定模組,如下所示。

開發人員旅程

整體而言,如要在現有應用程式中整合裝置指定功能,您必須按照下列步驟操作:

  1. 開發僅供特定裝置硬體使用的功能。
    • 功能模組的形式導入這項功能。
    • 在 AndroidManifest.xml 的模組條件部分中指定要將這項功能提供給哪些裝置群組。
  2. 建立裝置指定設定,讓 Play 瞭解如何為使用者裝置提供功能模組。
    • 設定 Google Play Developer API (如果尚未完成設定的話)。您會使用這個 API 將 DT 設定傳送至 Play。
    • 按照步驟建立 DT 設定。
  3. 將 AAB 上傳至 Play 並進行測試,確認所有設定皆正確無誤。

歡迎參閱這份文件,瞭解如何使用 Android Gradle 外掛程式為條件式供應程序新增裝置指定設定。

使用裝置指定功能建立條件式功能模組

在應用程式中新增功能模組

Play Feature Delivery 可讓您依特定條件提供應用程式的特定功能,或讓使用者視需要下載功能,詳情請參閱這篇簡介文章。您可以使用裝置指定功能,依特定條件將功能提供給指派至指定群組的裝置。

如要使用 DT 進行條件式供應,您必須使用 bundletool 1.7.0 以上版本。因此,您必須明確指定 Android Gradle 外掛程式的 bundletool 版本。您可以在 build.gradle 根檔案建構指令碼部分完成這項操作:

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)。

本機測試

建議您先在本機測試應用程式套件,確認所有設定皆正確無誤後,再繼續進行後續步驟。使用 bundletool 即可在本機建構及測試應用程式,並明確指定正確的裝置群組。首先,您將使用 build-apks 產生一組 .apks 檔案,然後使用 install-apks 將應用程式部署至已連結的裝置。您也可以透過 device-groups 標記指定要安裝的群組。如要進一步瞭解本機測試的方法,請參閱這篇文章。請注意,這個頁面尚未更新 DT 的資訊,因此不含「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 擷取特定裝置的一組 APK (使用 get-device-spec 並指定該裝置的裝置群組)。

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,請點選上述連結。另外,請按照這篇文章的幾個步驟操作,包括:

  1. 視需要建立 API 專案,並將該專案連結至 Google Play 管理中心
  2. 設定 API 存取用戶端

您可以按這裡查看 API 參考資料。如果您之後選擇透過 API 上傳建構項目,就會使用 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」)。

    裝置目錄中的 Pixel 4a 頁面

    裝置目錄中的 Pixel 4a 頁面

  • 下載支援裝置的 CSV 檔案,並將「製造商」和「型號代碼」資訊分別用於「build_brand」和「build_device」欄位。

舉例來說,下列群組符合 RAM 超過 4 GB 的所有裝置,除了 Pixel 5 (Google redfin) 和 RAM 小於 4 GB 的 Pixel 3 (Google Blueline) 以外。

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」查詢參數,以最適當的方式指定十個裝置指定設定:

HTTP 要求 GEThttps://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
路徑參數
查詢參數 page_token (選用):指定 10 個 DTC 的特定群組。如果您已建立超過 10 個 DTC,而且您要查看的 DTC 較舊 (建立時間早於最近的 10 個 DTC),這個參數就非常實用。
要求主體
回應主體 裝置指定設定清單

page_token

驗證裝置指定設定

bundletool 包含兩個指令,可協助您確認裝置指定設定能否正常運作,再上傳到 Google 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,然後將特定的裝置指定設定連結至您建構的 AAB。

歡迎參閱 Edits 方法的概要簡介。您也可以參閱這篇文章,透過更深入的範例瞭解如何在 Google Play 管理中心的不同測試群組中進行發布 (如果您參閱最後一個連結的文章,建議您使用支援 AAB 的 API,而不是該頁面上所列支援 APK 的 API)。如要指定您建構的 AAB 裝置層級設定,您必須在呼叫 edits.bundle.upload 方法時,將設定 ID 新增至「deviceTierConfigId」查詢參數,例如:

https://androidpublisher.googleapis.com/upload/androidpublisher/v3/applications/{packageName}/edits/{editId}/bundles?deviceTierConfigId="{deviceTierConfigId}"

透過 Google Play 管理中心

請按照這篇文章的操作說明上傳 Android App Bundle。您的 App Bundle 會套用最新的 DTC 設定。

輔助工具

可讓您快速建立設定的輔助工具: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) 指定為查詢參數:如果呼叫成功,系統會顯示您建構的 AAB 版本代碼、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,建議您以草稿版本的形式建立 AAB,然後在 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