Nhắm mục tiêu theo thiết bị cho các mô-đun có điều kiện

Nhắm mục tiêu theo thiết bị cho mô-đun có điều kiện là gì?

Tính năng Nhắm mục tiêu theo thiết bị (DT) cho phép bạn phân phối các mô-đun tính năng có điều kiện cho các thiết bị dựa trên phần cứng của những thiết bị đó. Ví dụ: bạn có thể chọn chỉ phân phối một số tính năng cho các thiết bị cao cấp chứ không phân phối cho những thiết bị không thể sử dụng tính năng này (tức là tiết kiệm dung lượng trên những thiết bị này). Điều này dựa trên khái niệm về các mô-đun tính năng trong Play Feature Delivery. Như sẽ thấy dưới đây, bạn có thể xác định tiêu chí nhắm mục tiêu (hiện là dựa trên RAM, các kiểu thiết bị cụ thể hoặc các tính năng hệ thống có sẵn) và nhắm mục tiêu mô-đun đến các nhóm thiết bị cụ thể.

Hành trình của nhà phát triển

Ở cấp độ cao, để tích hợp tính năng nhắm mục tiêu theo thiết bị vào ứng dụng hiện có, bạn sẽ cần thực hiện các bước sau:

  1. Phát triển một tính năng mà bạn chỉ muốn phân phối trên một bộ thiết bị dựa trên phần cứng của những thiết bị đó.
    • Triển khai tính năng này dưới dạng mô-đun tính năng.
    • Chỉ định trong phần điều kiện mô-đun của AndroidManifest.xml cho các nhóm thiết bị mà tính năng sẽ được phân phối.
  2. Tạo cấu hình Nhắm mục tiêu theo thiết bị để Play biết cách phân phối các mô-đun tính năng cho thiết bị của người dùng
    • Thiết lập API Nhà phát triển Google Play (nếu chưa hoàn tất) mà bạn sẽ sử dụng để gửi các cấu hình DT cho Play
    • Làm theo các bước này để tạo cấu hình DT
  3. Tải AAB lên Play rồi thử nghiệm để đảm bảo mọi thứ được định cấu hình một cách chính xác

Tài liệu này mô tả cách thêm tính năng Nhắm mục tiêu theo thiết bị để phân phối có điều kiện bằng cách sử dụng Trình bổ trợ Android cho Gradle.

Tạo mô-đun tính năng có điều kiện bằng tính năng Nhắm mục tiêu theo thiết bị

Thêm mô-đun tính năng vào ứng dụng

Play Feature Delivery cho phép bạn phân phối một số tính năng cho ứng dụng theo cách có điều kiện hoặc tải xuống theo yêu cầu. Bạn có thể đọc hướng dẫn tổng quan về Play Feature Delivery tại đây. Với tính năng Nhắm mục tiêu theo thiết bị, bạn có thể phân phối tính năng có điều kiện cho các thiết bị được chỉ định cho các nhóm đã cung cấp.

Để dùng DT cho phân phối có điều kiện, bạn phải sử dụng bundletool phiên bản 1.7.0 trở lên. Để làm được việc này, bạn cần chỉ định rõ phiên bản bundletool cho Trình bổ trợ Android cho Gradle. Bạn có thể thực hiện việc này trong phần bản dựng của tệp build.gradle gốc:

buildscript {
  dependencies {
    classpath "com.android.tools.build:bundletool:1.7.0"
    ...
  }
  ...
}

Để tạo mô-đun tính năng, hãy làm theo các hướng dẫn sau để mô-đun hoá ứng dụng Android.

Sau khi quá trình phát triển tính năng hoàn tất, bạn có thể chỉ định điều kiện phân phối dựa trên tính năng Nhắm mục tiêu theo thiết bị trong AndroidManifest.xml của tính năng. Bạn cần cung cấp điều kiện về nhóm thiết bị bên trong phần tử dist:conditions của dist:module. Bạn có thể xem thông tin chung về các điều kiện tại đây. Đối với các nhóm thiết bị, bạn có thể sử dụng các điều kiện mới để chỉ định mọi nhóm mà bạn sẽ phân phối tính năng này:

<dist:device-groups>
  <dist:device-group dist:name="..." />
  <dist:device-group dist:name="..." />
  ...
</dist:device-groups>

Ví dụ: giả sử bạn đã xác định một nhóm thiết bị có tên là _my_group1 (bạn sẽ tìm hiểu cách xác định trong phần Tạo Cấu hình nhắm mục tiêu theo thiết bị bên dưới). Nếu mô-đun tính năng chỉ được phân phối đến các thiết bị thuộc nhóm _my_group1, thì AndroidManifest.xml của mô-đun đó phải có dạng như sau:

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

Đối với một tính năng nhắm mục tiêu cả _my_group1 và _my_group2, AndroidManifest.xml sẽ hiển thị như sau:

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

Sau khi hoàn tất, bạn có thể phát triển Android App Bundle (AAB).

Thử nghiệm cục bộ

Trước khi tiếp tục, bạn nên thử nghiệm cục bộ gói ứng dụng của mình để đảm bảo mọi thứ được thiết lập chính xác. Bạn có thể sử dụng bundletool để tạo và thử nghiệm cục bộ ứng dụng, chỉ định rõ đúng nhóm thiết bị. Trước tiên, bạn sẽ dùng build-apks để tạo một tập hợp các tệp .apks rồi triển khai ứng dụng của mình cho một thiết bị được kết nối bằng cách sử dụng install-apks Bạn cũng có thể chỉ định nhóm mà mình muốn cài đặt qua cờ device-groups. Bạn có thể tìm thêm thông tin về phương thức thử nghiệm cục bộ này tại đây. Xin lưu ý rằng trang này chưa được cập nhật cho DT nên thiếu cờ 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

Cách khác: Bạn cũng có thể dùng extract-apks để trích xuất tập hợp APK cho một thiết bị cụ thể (bằng cách sử dụng get-device-spec cùng với việc chỉ định nhóm thiết bị cho thiết bị này).

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

Tạo Cấu hình nhắm mục tiêu theo thiết bị qua API Nhà phát triển Google Play

Bắt đầu sử dụng API Nhà phát triển Google Play (nếu chưa hoàn tất)

Để định cấu hình Nhắm mục tiêu theo thiết bị (xác định các nhóm thiết bị), bạn cần sử dụng Android Publisher API để tải cấu hình lên Google Play. Bạn có thể đọc thêm về API này tại đường liên kết ở trên – bạn cần thực hiện một số bước để bắt đầu:

  1. Tạo (nếu cần) và liên kết dự án API với Google Play Console
  2. Thiết lập một ứng dụng truy cập API

Bạn có thể tìm thấy tài liệu tham khảo API tại đây. Sau này, nếu chọn tải bản dựng lên thông qua API, bạn sẽ sử dụng phương thức Edits. Ngoài ra, bạn nên xem lại trang này trước khi sử dụng API.

Sử dụng Device Targeting Configuration API (API Cấu hình nhắm mục tiêu theo thiết bị)

Bạn có thể dùng lệnh gọi API sau đây để tạo cấu hình nhắm mục tiêu theo thiết bị của mình:

Tạo cấu hình nhắm mục tiêu theo thiết bị

Yêu cầu HTTP POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
Tham số đường dẫn Không áp dụng
Nội dung yêu cầu Cấu hình nhắm mục tiêu theo thiết bị
Nội dung phản hồi Cấu hình nhắm mục tiêu theo thiết bị
Đối tượng cấu hình nhắm mục tiêu theo thiết bị
{
  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
            }
          ]
        }
      ]
    }
  ]
}

Trường:

  • device_tier_config_id (số nguyên): Mã nhận dạng tương ứng với cấu hình nhắm mục tiêu theo thiết bị này

  • device_groups (đối tượng): Định nghĩa nhóm

    • name (chuỗi): Tên của nhóm thiết bị (mã nhận dạng chuỗi mà bạn xác định)
    • device_selectors (đối tượng): Các yêu cầu đối với thiết bị để thuộc về nhóm này.
    • device_ram (đối tượng): Yêu cầu về RAM của thiết bị
      • min_bytes (số nguyên): Dung lượng RAM bắt buộc tối thiểu (tính bằng byte)
      • max_bytes (số nguyên): Dung lượng RAM bắt buộc tối đa (tính bằng byte)
    • included_device_ids (đối tượng): Các kiểu thiết bị cần đưa vào bộ chọn này (tối đa 10000 device_ids cho mỗi nhóm). Thiết bị cần có trong danh sách này để khớp với bộ chọn. Đây là điều kiện cần nhưng chưa đủ để khớp với bộ chọn đầy đủ (xem lưu ý bên dưới về cách kết hợp các yêu cầu trong một bộ chọn).
      • build_brand (chuỗi): Nhà sản xuất thiết bị
      • build_device (chuỗi): Mã kiểu thiết bị
    • excluded_device_ids (đối tượng): Các mẫu thiết bị cần loại trừ trong bộ chọn này (tối đa 10000 device_ids cho mỗi nhóm). Thiết bị trong danh sách này sẽ không khớp với bộ chọn ngay cả khi thiết bị khớp với mọi yêu cầu khác trong bộ chọn.
      • build_brand (chuỗi): Nhà sản xuất thiết bị
      • build_device (chuỗi): Mã kiểu thiết bị

    • required_system_features (đối tượng): Các tính năng mà thiết bị cần phải có để có mặt trong bộ chọn này (tối đa 100 tính năng cho mỗi nhóm). Thiết bị cần có tất cả các tính năng hệ thống trong danh sách này để khớp với bộ chọn. Đây là điều kiện cần nhưng chưa đủ để khớp với bộ chọn đầy đủ (xem lưu ý bên dưới về cách kết hợp các yêu cầu trong một bộ chọn).

      Tài liệu tham khảo về tính năng hệ thống

      • name (chuỗi): Một tính năng của hệ thống

    • forbidden_system_features (đối tượng): Các tính năng mà thiết bị không được có để có mặt trong bộ chọn này (tối đa 100 tính năng cho mỗi nhóm). Nếu có bất kỳ tính năng hệ thống nào trong danh sách này, thì thiết bị sẽ không khớp với bộ chọn, ngay cả khi thiết bị khớp với tất cả các yêu cầu khác trong bộ chọn.

      Tài liệu tham khảo về tính năng hệ thống

      • name (chuỗi): Một tính năng của hệ thống

Bạn có thể tìm định dạng đúng cho mã nhà sản xuất và mã kiểu thiết bị bằng cách sử dụng Danh mục thiết bị trên Google Play Console, bằng một trong hai cách sau:

  • Kiểm tra từng thiết bị bằng Danh mục thiết bị, đồng thời tìm nhà sản xuất và mã kiểu thiết bị ở những vị trí như trong ví dụ dưới đây (Đối với Google Pixel 4a, nhà sản xuất là “Google” và mã kiểu thiết bị là "sunfish")

    trang pixel 4a trong danh mục thiết bị

    trang pixel 4a trong danh mục thiết bị

  • Tải tệp CSV (chứa các thiết bị được hỗ trợ) xuống, sau đó nhập giá trị Nhà sản xuất vào trường build_brand và nhập giá trị Mã kiểu thiết bị vào trường build_device.

Ví dụ: nhóm sau đây phù hợp với tất cả các thiết bị có RAM trên 4 GB, ngoại trừ Pixel 5 (google redfin) và bao gồm Pixel 3 (Google Blueline, có RAM dưới 4 GB).

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"
          }
        ]
      }
    ]
  }
]

Bạn có thể đọc như sau:

[ (RAM > 4GB) AND NOT (google redfin) ] OR [ (google blueline) ]

Bạn có thể làm theo hướng dẫn bên dưới để xác thực Cấu hình nhắm mục tiêu theo thiết bị trước khi tải Cấu hình lên Google Play.

Nhận Cấu hình nhắm mục tiêu theo thiết bị theo mã nhận dạng

Bạn có thể truy xuất cấu hình nhắm mục tiêu theo thiết bị cụ thể theo mã nhận dạng bằng cách sử dụng lệnh gọi sau:

Yêu cầu HTTP GEThttps://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs/{deviceTierConfigId}
Tham số đường dẫn Không áp dụng
Nội dung yêu cầu Không áp dụng
Nội dung phản hồi Cấu hình nhắm mục tiêu theo thiết bị

Nhận danh sách Cấu hình nhắm mục tiêu theo thiết bị

Bạn có thể nhận 10 cấu hình nhắm mục tiêu theo thiết bị gần đây nhất bằng lệnh gọi sau đây (hoặc chỉ định tối ưu một tập hợp 10 cấu hình bằng tham số truy vấn page_token):

Yêu cầu HTTP GEThttps://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
Tham số đường dẫn Không áp dụng
Tham số truy vấn page_token (không bắt buộc) – Dùng để chỉ định một nhóm cụ thể gồm 10 DTC. Cách này hữu ích nếu bạn đã tạo hơn 10 DTC và muốn xem những DTC được tạo trước 10 DTC gần đây nhất.
Nội dung yêu cầu Không áp dụng
Nội dung phản hồi Danh sách Cấu hình nhắm mục tiêu theo thiết bị

page_token

Xác thực Cấu hình nhắm mục tiêu theo thiết bị

bundletool bao gồm 2 lệnh giúp bạn xác thực rằng Cấu hình nhắm mục tiêu theo thiết bị hoạt động như dự kiến trước khi tải Cấu hình lên Play.

Với bundletool print-device-targeting-config, bạn có thể xác thực rằng tệp JSON có cú pháp chính xác và trực quan hoá các nhóm thiết bị của bạn ở định dạng dễ đọc hơn.

bundletool print-device-targeting-config --config=mydtc.json

Với bundletool evaluate-device-targeting-config, bạn có thể đánh giá những nhóm nào sẽ khớp với một thiết bị cụ thể. Bạn kết nối thiết bị mục tiêu với máy trạm và sử dụng cờ --connected-device; hoặc bạn biên dịch thủ công một tệp JSON chứa thuộc tính thiết bị và cung cấp tệp đó thông qua cờ --device-properties.

bundletool evaluate-device-targeting-config --config=mydtc.json --connected-device
bundletool evaluate-device-targeting-config --config=mydtc.json --device-properties=deviceproperties.json

Tệp thuộc tính thiết bị phải là tệp JSON theo cấu trúc protobuf DeviceProperties. Ví dụ:

{
  "ram": 2057072640,
  "device_id": {
    "build_brand":"google",
    "build_device":"redfin"
  },
  "system_features": [
    {
      "name":"android.hardware.bluetooth"
    },
    {
      "name":"android.hardware.camera"
    }
  ]
}

Tải Android App Bundle lên Google Play

Qua API

Bạn có thể sử dụng API Nhà phát triển Google Play để tải Android App Bundle lên Google Play và liên kết một cấu hình Nhắm mục tiêu theo thiết bị với bản dựng của mình.

Bạn có thể xem phần tổng quan chung về các phương thức Edits tại đây, cùng với các ví dụ chi tiết hơn về cách phát hành lên nhiều kênh trong Google Play Console (đối với đường liên kết cuối cùng, bạn cần sử dụng API thân thiện với AAB thay vì API thân thiện với APK được liệt kê trong trang). Để chỉ định cấu hình nhắm mục tiêu theo thiết bị cho bản dựng, bạn sẽ thêm mã nhận dạng cấu hình vào tham số truy vấn deviceTierConfigId trong khi gọi phương thức edits.bundle.upload, như sau:

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

Qua Google Play Console

Bạn có thể làm theo hướng dẫn tại đây để tải Android App Bundle lên. Cấu hình DTC mới nhất sẽ áp dụng cho App Bundle của bạn.

Phụ trợ

Bắt đầu nhanh bằng Curl

Dưới đây là ví dụ (sử dụng curl công cụ dòng lệnh) về việc tạo cấu hình mới về nhắm mục tiêu theo thiết bị và sử dụng API Edits (API Chỉnh sửa) để tạo bản chỉnh sửa mới, tải AAB mới lên (liên kết với cấu hình cụ thể về nhắm mục tiêu theo thiết bị), đặt cấu hình theo dõi/phát hành và thực hiện chỉnh sửa (qua đó đặt thay đổi ở chế độ công khai). Hãy đảm bảo bạn có vị trí của:

Trước tiên, hãy tạo một cấu hình nhắm mục tiêu theo thiết bị rồi ghi lại deviceTierConfigId mà bạn nhận được khi có lệnh gọi thành công.

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

Bắt đầu chỉnh sửa – bạn sẽ nhận được mã nhận dạng và thời gian hết hạn chỉnh sửa. Lưu mã nhận dạng cho các lệnh gọi sau đây.

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits

Tải AAB lên, trong đó chỉ định cấu hình nhắm mục tiêu theo thiết bị (deviceTierConfigId) làm tham số truy vấn. Nếu lệnh gọi thành công, bạn sẽ thấy mã phiên bản, sha1 và sha256 của bản dựng. Lưu mã phiên bản cho lệnh gọi tiếp theo.

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}

Chỉ định AAB cho kênh thử nghiệm mong muốn (để thử nghiệm, bạn nên sử dụng kênh thử nghiệm nội bộ, nhưng có thể đọc thêm về các kênh thử nghiệm khác tại đây), tại đây, chúng tôi thực hiện một bản phát hành đơn giản mà không cần ghi chú phát hành, nhưng bạn có thể đọc trang này để tìm hiểu thêm về cách phát hành theo giai đoạn, bản phát hành nháp và ghi chú phát hành. Nếu đây là lần đầu tiên sử dụng API Nhà xuất bản, bạn nên tạo phiên bản này dưới dạng bản phát hành nháp và hoàn tất bản phát hành trên Google Play Console để đảm bảo mọi thứ được định cấu hình chính xác.

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}

Xác nhận các thay đổi (hãy thận trọng nếu tiếp tục vì thao tác này sẽ khiến mọi thay đổi có hiệu lực trên Play đối với kênh mong muốn)

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits/{editID}:commit