bundletool

bundletool là công cụ cơ bản mà Android Studio, trình bổ trợ Android cho Gradle và Google Play sử dụng để tạo Android App Bundle và chuyển đổi một gói ứng dụng thành các nhiều tệp APK được triển khai đến các thiết bị. Cũng có thể dùng bundletool dưới dạng một công cụ dòng lệnh để tự xây dựng các gói ứng dụng và tạo lại các bản dựng APK phía máy chủ của Google Play.

Tải bundletool

Nếu chưa có bundletool, hãy tải xuống qua Kho lưu trữ GitHub.

Tạo gói ứng dụng (app bundle)

Bạn nên sử dụng Android Studio và Trình bổ trợ Android cho Gradle để tạo và ký một Android App Bundle. Tuy nhiên, nếu không thể sử dụng IDE (chẳng hạn do đang sử dụng máy chủ bản dựng liên tục), bạn cũng có thể tạo gói ứng dụng từ dòng lệnh và ký gói ứng dụng đó bằng cách sử dụng jarsigner.

Để biết thêm thông tin về việc tạo gói ứng dụng bằng bundletool, hãy xem bài viết Tạo gói ứng dụng bằng bundletool.

Tạo một tập hợp APK từ gói ứng dụng của bạn

Sau khi tạo Android App Bundle, bạn nên kiểm thử cách Google Play sử dụng định dạng này để tạo các tệp APK và cách các tệp APK đó hoạt động khi triển khai đến thiết bị. Có hai cách mà bạn nên cân nhắc khi kiểm thử gói ứng dụng: sử dụng công cụ dòng lệnh bundletool và thông qua Google Play bằng cách tải gói lên Play Console rồi sử dụng kênh thử nghiệm. Phần này giải thích cách sử dụng bundletool để kiểm thử cục bộ gói ứng dụng.

Khi bundletool tạo các tệp APK qua gói ứng dụng, công cụ này sẽ đưa các tệp APK này vào trong một vùng chứa có tên là APK set archive (Kho lưu trữ tập hợp APK) với đuôi tệp .apks. Để tạo một tập hợp APK cho tất cả cấu hình thiết bị mà ứng dụng của bạn hỗ trợ từ gói ứng dụng, hãy sử dụng lệnh bundletool build-apks như minh hoạ dưới đây.

bundletool build-apks --bundle=/MyApp/my_app.aab --output=/MyApp/my_app.apks

Nếu muốn triển khai các tệp APK đến một thiết bị, bạn cũng cần đưa vào đó thông tin ký của ứng dụng, như được trình bày trong lệnh bên dưới. Nếu bạn không chỉ định thông tin ký, bundletool sẽ tìm cách ký tệp APK của bạn bằng một khoá gỡ lỗi.

bundletool build-apks --bundle=/MyApp/my_app.aab --output=/MyApp/my_app.apks
--ks=/MyApp/keystore.jks
--ks-pass=file:/MyApp/keystore.pwd
--ks-key-alias=MyKeyAlias
--key-pass=file:/MyApp/key.pwd

Bảng bên dưới mô tả chi tiết hơn về các cờ và tuỳ chọn mà bạn có thể thiết lập khi sử dụng lệnh bundletool build-apks. Chỉ có --bundle--output là bắt buộc — tất cả cờ khác đều không bắt buộc.

Gắn cờ Mô tả
--bundle=path (Bắt buộc) Chỉ định đường dẫn đến gói ứng dụng mà bạn đã tạo bằng Android Studio. Để tìm hiểu thêm, hãy đọc phần Xây dựng dự án của bạn.
--output=path (Bắt buộc) Chỉ định tên của tệp `.apks` đầu ra, chứa tất cả cấu phần phần mềm APK dành cho ứng dụng của bạn. Để kiểm tra các cấu phần phần mềm trong tệp này trên một thiết bị, hãy vào phần liên quan đến cách triển khai APK đến thiết bị đã kết nối.
--overwrite Hãy đưa vào cờ này nếu bạn muốn ghi đè mọi tệp đầu ra hiện có với đường dẫn mà bạn chỉ định bằng cách sử dụng tuỳ chọn --output. Nếu không đưa cờ này vào và tệp đầu ra đã tồn tại, sẽ xảy ra lỗi bản dựng.
--aapt2=path Chỉ định một đường dẫn tuỳ chỉnh đến AAPT2. Theo mặc định, bundletool bao gồm phiên bản riêng của AAPT2.
--ks=path Chỉ định đường dẫn đến kho khoá triển khai dùng để ký các APK. Cờ này là không bắt buộc. Nếu bạn không đưa khoá vào, bundletool sẽ tìm cách ký các APK của bạn bằng khoá ký gỡ lỗi.
--ks-pass=pass:password
hoặc
--ks-pass=file:/path/to/file
Chỉ định mật khẩu của kho khoá. Nếu bạn đang chỉ định mật khẩu ở dạng văn bản thuần tuý, hãy hạn định mật khẩu đó bằng pass:. Nếu bạn đang chuyển đường dẫn đến một tệp chứa mật khẩu, hãy hạn định tệp đó bằng file:. Nếu bạn chỉ định một kho khoá bằng cờ --ks mà không chỉ định --ks-pass, thì bundletool sẽ nhắc bạn nhập mật khẩu từ dòng lệnh.
--ks-key-alias=alias Chỉ định bí danh của khoá ký mà bạn muốn sử dụng.
--key-pass=pass:password
hoặc
--key-pass=file:/path/to/file
Chỉ định mật khẩu cho khoá ký. Nếu bạn đang chỉ định mật khẩu ở dạng văn bản thuần tuý, hãy hạn định mật khẩu đó bằng pass:. Nếu bạn đang chuyển đường dẫn đến một tệp chứa mật khẩu, hãy hạn định tệp đó bằng file:.

Nếu mật khẩu này giống với mật khẩu kho khoá, bạn có thể bỏ qua cờ này.

--connected-device Hướng dẫn bundletool tạo các tệp APK nhắm đến cấu hình của một thiết bị đã kết nối. Nếu bạn không đưa cờ này vào, bundletool sẽ tạo các tệp APK cho tất cả cấu hình thiết bị mà ứng dụng của bạn hỗ trợ.
--device-id=serial-number Nếu bạn có nhiều thiết bị được kết nối, hãy sử dụng cờ này để chỉ định mã sê-ri của thiết bị mà bạn muốn triển khai ứng dụng.
--device-spec=spec_json Sử dụng cờ này để cung cấp đường dẫn tới tệp .json chỉ định cấu hình thiết bị mà bạn muốn nhắm đến. Để tìm hiểu thêm, hãy chuyển đến phần liên quan đến cách Tạo và sử dụng tệp JSON chứa thông số kỹ thuật của thiết bị.
--mode=universal Thiết lập chế độ này thành universal nếu bạn muốn bundletool chỉ tạo một APK duy nhất chứa tất cả mã và tài nguyên của ứng dụng và APK đó cũng tương thích với mọi cấu hình thiết bị mà ứng dụng của bạn hỗ trợ.

Lưu ý: bundletool chỉ bao gồm các mô-đun tính năng có chỉ định <dist:fusing dist:include="true"/> trong tệp kê khai trong một APK chung. Để tìm hiểu thêm, hãy đọc về Tệp kê khai mô-đun tính năng.

Xin lưu ý rằng các tệp APK này có kích thước lớn hơn các tệp APK được tối ưu hoá cho một cấu hình thiết bị cụ thể. Tuy nhiên, bạn có thể chia sẻ các tệp APK này một cách dễ dàng với những người thử nghiệm nội bộ, để thử nghiệm ứng dụng của bạn trên nhiều cấu hình thiết bị.

--local-testing Sử dụng cờ này để bật gói ứng dụng của bạn khi kiểm thử cục bộ. Việc kiểm thử nghiệm cho phép các chu kỳ kiểm thử được lặp lại nhanh chóng mà không cần phải tải lên máy chủ Google Play.

Để biết ví dụ về cách kiểm thử việc cài đặt mô-đun bằng cờ --local-testing, hãy xem Cài đặt các mô-đun kiểm thử cục bộ.

Triển khai tệp APK đến thiết bị đã kết nối

Sau khi bạn tạo một tập hợp APK, bundletool có thể triển khai một tổ hợp các APK phù hợp từ tập hợp đó đến thiết bị được kết nối.

Ví dụ: nếu bạn có một thiết bị đã kết nối chạy Android 5.0 (API cấp 21) trở lên, thì bundletool sẽ đẩy tệp APK cơ sở, APK mô-đun tính năng và các tệp APK cấu hình cần có để chạy ứng dụng của bạn đến thiết bị đó. Ngoài ra, nếu thiết bị được kết nối của bạn đang chạy Android 4.4 (API cấp 20) trở xuống, bundletool sẽ tìm kiếm một tập hợpk APK tương thích và triển khai đến thiết bị của bạn.

Để triển khai ứng dụng từ tập hợp APK, hãy sử dụng lệnh install-apks và chỉ định đường dẫn của tập hợp APK bằng cách sử dụng cờ --apks=/path/to/apks, như được minh hoạ dưới đây. (Nếu bạn có nhiều thiết bị đã kết nối, hãy chỉ định một thiết bị mục tiêu bằng cách thêm cờ --device-id=serial-id.)

bundletool install-apks --apks=/MyApp/my_app.apks

Tạo một tập hợp APK dành riêng cho thiết bị

Nếu không muốn tạo một tập hợp APK cho tất cả các cấu hình thiết bị mà ứng dụng của bạn hỗ trợ, bạn có thể tạo các APK chỉ nhắm đến cấu hình của một thiết bị được kết nối bằng cách sử dụng tuỳ chọn --connected-device, như phần dưới đây. (Nếu bạn có nhiều thiết bị đã kết nối, hãy chỉ định một thiết bị mục tiêu bằng cách thêm cờ --device-id=serial-id).

bundletool build-apks --connected-device
--bundle=/MyApp/my_app.aab --output=/MyApp/my_app.apks

Tạo và sử dụng tệp JSON chứa thông số kỹ thuật của thiết bị

bundletool có thể tạo một tập hợp APK nhắm đến cấu hình thiết bị do tệp JSON chỉ định. Ở lần đầu tiên tạo một tệp JSON cho thiết bị được kết nối, hãy chạy lệnh sau:

bundletool get-device-spec --output=/tmp/device-spec.json

bundletool tạo một tệp JSON cho thiết bị của bạn trong thư mục có chứa công cụ đó. Sau đó, bạn có thể chuyển tệp này đến bundletool để tạo một tập hợp APK chỉ nhắm đến cấu hình được mô tả trong tệp JSON đó như sau:

bundletool build-apks --device-spec=/MyApp/pixel2.json
--bundle=/MyApp/my_app.aab --output=/MyApp/my_app.apks

Tạo tệp JSON chứa thông số kỹ thuật của thiết bị theo cách thủ công

Nếu bạn không có quyền truy cập vào thiết bị mà bạn muốn tạo tập hợp APK nhắm đến (chẳng hạn, một người bạn muốn thử ứng dụng của bạn bằng một thiết bị mà bạn không có sẵn), bạn có thể tạo tệp JSON theo cách thủ công bằng cách sử dụng định dạng sau:

{
  "supportedAbis": ["arm64-v8a", "armeabi-v7a"],
  "supportedLocales": ["en", "fr"],
  "screenDensity": 640,
  "sdkVersion": 27
}

Sau đó, bạn có thể chuyển JSON này đến lệnh bundle extract-apks, như được mô tả trong mục trước.

Trích xuất các APK dành riêng cho thiết bị từ một tập hợp APK hiện có

Nếu bạn hiện có một tập hợp APK và muốn trích xuất từ đó một tập hợp con APK nhắm đến một cấu hình thiết bị cụ thể, bạn có thể sử dụng lệnh extract-apks và chỉ định một tệp thông số kỹ thuật JSON của thiết bị, như sau:

bundletool extract-apks
--apks=/MyApp/my_existing_APK_set.apks
--output-dir=/MyApp/my_pixel2_APK_set.apks
--device-spec=/MyApp/bundletool/pixel2.json

Đo lường kích thước ước tính khi tải xuống của các tệp APK trong một tập hợp APK

Để đo lường kích thước ước tính khi tải xuống của các tệp APK trong một tập hợp APK như việc các tệp APK này sẽ được phân phối nén trong định mức, hãy sử dụng lệnh get-size total:

bundletool get-size total --apks=/MyApp/my_app.apks

Bạn có thể sửa đổi hành vi của lệnh get-size total bằng cách sử dụng các cờ sau:

Gắn cờ Mô tả
--apks=path (Bắt buộc) Chỉ định đường dẫn tới tệp tập hợp APK hiện có (được đo lường kích thước khi tải xuống).
--device-spec=path Chỉ định đường dẫn đến tệp thông số kỹ thuật của thiết bị (từ get-device-spec hoặc được tạo thủ công) để dùng cho việc so khớp. Bạn có thể chỉ định một đường dẫn một phần để đánh giá một tập hợp cấu hình.
--dimensions=dimensions Chỉ định các thứ nguyên được sử dụng khi tính toán ước tính kích thước. Chấp nhận danh sách được phân tách bằng dấu phẩy gồm: SDK, ABI, SCREEN_DENSITYLANGUAGE. Để đo lường trên tất cả các thứ nguyên, hãy chỉ định ALL.
--instant Đo lường kích thước khi tải xuống của các tệp APK hỗ trợ phiên bản tức thì (instant-enabled) thay vì tệp APK có thể cài đặt. Theo mặc định, bundletool sẽ đo lường kích thước khi được tải xuống của tệp APK có thể cài đặt.
--modules=modules Chỉ định danh sách được phân tách bằng dấu phẩy gồm các mô-đun trong tập hợp APK để xem xét trong hoạt động đo lường. Lệnh bundletool tự động đưa mọi mô-đun phụ thuộc vào tập hợp đã chỉ định. Theo mặc định, lệnh này sẽ đo kích thước khi được tải xuống của tất cả các mô-đun được cài đặt trong lần tải xuống đầu tiên.

Tài nguyên khác

Để tìm hiểu thêm về cách sử dụng bundletool, hãy thử dùng tài nguyên sau.

Lớp học lập trình

  • Android App Bundle đầu tiên của bạn, một lớp học lập trình khám phá các nguyên tắc cơ bản của Android App Bundle và cho bạn biết cách nhanh chóng bắt đầu xây dựng ứng dụng của riêng mình bằng Android Studio. Lớp học lập trình này cũng giúp khám phá cách kiểm thử các gói ứng dụng của bạn bằng cách sử dụng bundletool.