Trang này được dịch bởi Cloud Translation API.

Nhắm mục tiêu thành phần theo quốc gia

Nhắm mục tiêu thành phần theo quốc gia là gì?

Tính năng nhắm mục tiêu thành phần theo quốc gia cho phép bạn phân phối nhiều phiên bản (chẳng hạn như độ phân giải) của cùng một thành phần cho các thiết bị dựa trên quốc gia nơi người dùng sinh sống. Ví dụ: bạn có thể chọn phân phối các thành phần tuỳ chỉnh cho nhiều quốc gia nơi có ứng dụng của bạn – tất cả đều không làm tăng kích thước tổng thể của trò chơi bằng cách chỉ phân phối các thành phần cần thiết cho thiết bị của người dùng. Phương pháp này dựa trên khái niệm về gói thành phần trong Play Asset Delivery. Như bạn thấy ở bên dưới, bạn có thể xác định tiêu chí nhắm mục tiêu lên đến tối đa 20 nhóm quốc gia. Trong trường hợp này, quốc gia của thiết bị thường được xác định theo địa chỉ thanh toán mà người dùng đã đăng ký trên tài khoản Google Play của họ.

Giống như Play Asset Delivery, tính năng nhắm mục tiêu theo quốc gia hỗ trợ Android 4.1 (API cấp 16) trở lên. Tuy nhiên, trên các thiết bị chạy Android 4.4 (API cấp 19) trở xuống, nhóm quốc gia mặc định sẽ được phân phối bất kể vị trí của người dùng.

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

Nhìn chung, để tích hợp tính năng nhắm mục tiêu theo quốc gia vào trò chơi hiện có của bạn, hãy làm theo các bước sau:

Tích hợp tính năng nhắm mục tiêu theo quốc gia (và theo tiện ích, Play Asset Delivery) trong trò chơi
- Tích hợp Play Asset Delivery vào trò chơi (nếu bạn chưa làm vậy)
- Chia tài sản thành các gói tài sản
- Tập hợp mã và tài sản lại để tạo cấu phần phần mềm Android App Bundle (AAB) cuối cùng mà bạn sẽ tải lên Play.
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 tài sản của bạn tới 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 nhắm mục tiêu cho Play.
- Làm theo các bước để tạo cấu hình nhắm mục tiêu.
Tải AAB lên Play rồi kiểm thử để đảm bảo mọi thứ được định cấu hình chính xác

Gradle là hệ thống xây dựng được đề xuất cho các trò chơi gốc và Java. Đối với trò chơi được tạo bản dựng bằng Gradle, hãy làm theo các bước sau đây để định cấu hình hệ thống bản dựng nhằm tạo AAB có hỗ trợ tính năng nhắm mục tiêu theo quốc gia.

Nếu xuất trò chơi sang Gradle rồi hoàn thành bản dựng, bạn nên làm theo những hướng dẫn sau (ví dụ: Các trò chơi của Unity được xuất sang Gradle).

Thiết lập tính năng nhắm mục tiêu tài sản theo quốc gia trong ứng dụng

Tích hợp Play Asset Delivery vào trò chơi (nếu chưa hoàn tất)

Play Asset Delivery (PAD) cho phép bạn linh động phân phối tài sản trong trò chơi tại thời điểm cài đặt hoặc trong thời gian chạy. Bạn có thể đọc hướng dẫn tổng quan về Play Asset Delivery tại đây. Với tính năng nhắm mục tiêu theo quốc gia, Play sẽ phân phối nội dung của gói tài sản dựa trên các cấu hình nhóm quốc gia mà bạn quy định cho các vị trí khác nhau của người dùng. Bạn nên làm theo hướng dẫn dưới đây và tích hợp PAD vào trò chơi (tức là tạo gói tài sản, triển khai tính năng truy xuất trong trò chơi), sau đó sửa đổi mã dự án để bật tính năng nhắm mục tiêu theo quốc gia.

Gradle

Đối với các trò chơi được tạo bằng Gradle, hãy sử dụng các hướng dẫn sau để tạo gói tài sản bằng Gradle, sau đó làm theo hướng dẫn để tích hợp hoạt động truy xuất gói tài sản trong trò chơi của bạn:

Java
Gốc
Trò chơi của Unity đã xuất sang Gradle
- Sử dụng thư viện Java thông qua JNI (chẳng hạn như thư viện đã tích hợp vào Unity).

Tạo thư mục cụ thể cho nhóm quốc gia

Nếu sử dụng Gradle

Bây giờ, bạn sẽ chia tài sản của mình theo các nhóm quốc gia (tối đa là 20) mà bạn sẽ xác định sau đó. Tạo các thư mục được nhắm mục tiêu bằng cách lấy các thư mục gói tài sản hiện có được tạo ở bước trước đó, rồi thêm hậu tố #countries_latam, #countries_na, v.v vào thư mục phù hợp (như mô tả bên dưới). Khi sử dụng gói tài sản trong trò chơi, bạn không cần xác định thư mục bằng hậu tố (nói cách khác, hệ thống sẽ tự động gỡ bỏ hậu tố trong quy trình xây dựng).

Sau bước trước, bước này có thể hiển thị như sau:

...
.../level1/src/main/assets/character-textures#countries_latam/
.../level1/src/main/assets/character-textures#countries_na/
.../level1/src/main/assets/character-textures/
...

Khi truy cập vào các tệp trong thư mục đó, bạn có thể sử dụng cùng một đường dẫn mà không cần thêm hậu tố (trong ví dụ này, tôi sẽ dùng đường dẫn là level1/assets/character-textures/ mà không thêm bất kỳ hậu tố nào).

Xây dựng tệp Android App Bundle

Gradle

Trong tệp build.gradle của dự án, hãy định cấu hình các phần phụ thuộc để có các phiên bản thấp hơn (hoặc cao hơn) cho trình bổ trợ Android cho Gradle và bundletool:

buildscript {
  dependencies {
    classpath 'com.android.tools.build:gradle:8.1.0-alpha01'
    classpath "com.android.tools.build:bundletool:1.14.0"
    ...
  }
  ...
}

Bạn cũng cần cập nhật Gradle lên phiên bản 8.0 trở lên. Bạn có thể cập nhật Gradle trong gradle/wrapper/gradle-wrapper.properties trong dự án của mình.

distributionUrl=https://services.gradle.org/distributions/gradle-8.0-rc-1-all.zip

Cuối cùng, bạn cần sử dụng Thư viện Play Asset Delivery. Nếu bạn vẫn đang dùng Thư viện Play Core một khối (monolithic), hãy cập nhật lên phiên bản 1.8.3 trở lên. Bạn nên chuyển sang Thư viện Play Asset Delivery và cập nhật lên phiên bản mới nhất nếu có thể.

dependencies {
  implementation 'com.google.android.play:asset-delivery:2.0.1'
  ...
}

Trong tệp build.gradle của mô-đun ứng dụng chính, hãy bật tính năng phân tách nhắm mục tiêu theo quốc gia:

android {
  bundle {
    countrySet {
      enableSplit true
    }
    ...
  }
  ...
}

Cuối cùng, bạn có thể tạo Android App Bundle (AAB).

Bundletool

Tạo gói bằng bundletool và trong khi ở bước tuỳ chỉnh AAB, hãy thêm đoạn mã sau vào tệp BundleConfig.pb.

{
  ...
  "optimizations": {
    "splitsConfig": {
      "splitDimension": [
      ...
      {
        "value": "COUNTRY_SET",
        "negate": false,
        "suffixStripping": {
          "enabled": true,
        }
      }],
    }
  }
}

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 (1.14.0 trở lên) để tạo và kiểm thử cục bộ ứng dụng, chỉ định rõ ràng chính xác quốc gia. Trước tiên, bạn sẽ dùng build-apks để tạo nhóm tệp .apks, sau đó triển khai ứng dụng trên một thiết bị đã kết nối bằng install-apks. Bạn cũng có thể chỉ định nhóm quốc gia mà bạn muốn cài đặt thông qua cờ country-set. Bạn có thể tìm thêm thông tin về phương pháp kiểm thử cục bộ này tại đây (xin lưu ý rằng trang này chưa được cập nhật cho tính năng nhắm mục tiêu theo quốc gia nên thiếu cờ country-set).

bundletool build-apks --bundle=/path/to/app.aab --output=/path/to/app.apks --local-testing
bundletool install-apks --apks=/path/to/app.apks --country-set=latam

Cách khác: Bạn cũng có thể sử dụng extract-apks để trích xuất nhóm tệp APK cho một thiết bị cụ thể. Tuy nhiên, việc sử dụng get-device-spec đồng thời với việc chỉ định quốc gia cho thiết bị này sẽ không hoạt động được cùng với cờ --local-testing, nghĩa là bạn sẽ không thể kiểm thử các gói tài sản theo dõi nhanh hoặc theo yêu cầu.

bundletool get-device-spec --output=/path/to/device-spec.json --country-set=latam
bundletool 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 quốc gia (tức là xác định các nhóm quốc gia), bạn cần sử dụng Android Publisher API (API Nhà xuất bản Android) để tải cấu hình của mì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:

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 của bạn 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 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ị:

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ị

{
  "user_country_sets": [
    {
      "name": "latam",
      "country_codes": [
        "AR",
        "BR",
        ...
      ]
    },
    {
      "name": "sea",
      "country_codes": [
        "VN",
        "TW",
        ...
      ]
    }
  ]
}

Trường:

device_confid_id (integer): ID tương ứng với cấu hình nhắm mục tiêu theo thiết bị này.
user_country_sets (đối tượng): Định nghĩa nhóm quốc gia
- name (string): Tên của nhóm quốc gia (mã nhận dạng chuỗi mà bạn xác định).
- country_codes (string): Các quốc gia thuộc nhóm quốc gia này (định dạng: ISO 3166-1 alpha-2).

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.

Truy xuất cấu hình nhắm mục tiêu theo thiết bị theo ID

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

Yêu cầu HTTP	`GET https://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ị

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

Bạn có thể lấy 10 cấu hình gần đây nhất về nhắm mục tiêu theo thiết bị 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	`GET https://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ác 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.

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

Với bundletool evaluate-device-targeting-config, bạn có thể đánh giá nhóm quốc gia nào sẽ phù hợp với một thiết bị cụ thể. Bạn có thể cung cấp thông tin về quốc gia của người dùng thông qua cờ --country-code.

bundletool evaluate-device-targeting-config --config=mydtc.json --connected-device --country-code=AR

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 (Chỉnh sửa) 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.

Xác minh đúng tài sản đang được phân phối

Hãy sử dụng phương thức sau đây để đảm bảo chỉ phân phối đúng tài sản cho thiết bị

adb shell pm path {packageName}

Bạn sẽ thấy một số dòng mã như:

package:{...}/base.apk
package:{...}/split_config.en.apk
package:{...}/split_config.xxhdpi.apk
package:{...}/split_main_asset.apk
package:{...}/split_main_asset.config.countries_latam.apk

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ề cách tạo cấu hình mới cho tính năng nhắm mục tiêu theo thiết bị và sử dụng Edits API (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 AAB này với một cấu hình nhắm mục tiêu theo thiết bị cụ thể), thiết lập cấu hình theo dõi/phát hành và thực hiện chỉnh sửa. (từ đó sẽ công khai nội dung thay đổi). Hãy đảm bảo bạn có vị trí của:

Khoá tương ứng với ứng dụng API
Tên gói của ứng dụng

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 "{ "user_country_sets": [ { "name": "latam", "country_codes": [ "AR", "BR" ] }, { "name": "sea", "country_codes": [ "VN", "TW" ] } ] }" 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 thiết bị 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="{deviceTargetingConfigID}"

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 Publisher API (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}'</code>, <code><strong>versionCodes</strong></code>: <code>['{versionCode}']</code> <code><strong>}]}</strong></code>" <code>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