bundletool

bundletool adalah alat dasar yang digunakan Android Studio, plugin Android Gradle, dan Google Play untuk mem-build Android App Bundle. bundletool dapat mengonversi app bundle menjadi berbagai APK yang di-deploy ke perangkat.

Android SDK Bundle (ASB) dan APK-nya dibuat dengan bundletool. SDK ini juga tersedia sebagai alat command line, sehingga Anda dapat mem-build app bundle dan memaketkan SDK sendiri serta membuat kembali build sisi server Google Play untuk APK aplikasi atau APK SDK yang mendukung runtime.

Download bundletool

Jika belum, download bundletool dari repositori GitHub.

Mem-build dan menguji app bundle

Anda dapat menggunakan Android Studio atau alat command line bundletool untuk mem-build Android App Bundle, lalu menguji pembuatan APK dari app bundle ini.

Mem-build app bundle

Gunakan Android Studio dan plugin Android Gradle untuk mem-build dan menandatangani Android App Bundle. Namun, jika tidak dapat menggunakan IDE (misalnya, karena Anda menggunakan server build berkelanjutan), Anda juga dapat mem-build app bundle dari command line dan menandatanganinya menggunakan jarsigner.

Untuk mengetahui informasi selengkapnya tentang mem-build app bundle dengan bundletool, lihat Mem-build app bundle menggunakan bundletool.

Membuat satu rangkaian APK dari app bundle Anda

Setelah mem-build Android App Bundle, sebaiknya Anda menguji bagaimana Google Play menggunakannya untuk membuat APK dan bagaimana APK tersebut berperilaku saat di-deploy ke sebuah perangkat.

Ada dua cara untuk menguji app bundle:

• Gunakan alat command line bundletool secara lokal.
• Upload paket Anda ke Konsol Play melalui Google Play dengan menggunakan jalur pengujian.

Bagian ini menjelaskan cara menggunakan bundletool untuk menguji app bundle secara lokal.

Saat bundletool membuat APK dari app bundle Anda, alat tersebut akan menyertakan APK yang dihasilkan dalam penampung yang disebut arsip rangkaian APK, yang menggunakan ekstensi file .apks. Untuk membuat APK yang ditetapkan bagi semua konfigurasi perangkat yang didukung oleh aplikasi Anda dari app bundle, gunakan perintah bundletool build-apks, seperti yang ditunjukkan:

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

Jika ingin men-deploy APK ke perangkat, Anda juga harus menyertakan informasi penandatanganan aplikasi seperti yang ditunjukkan dalam perintah berikut. Jika Anda tidak menentukan informasi penandatanganan, bundletool akan mencoba menandatangani APK dengan kunci debug untuk Anda.

 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 

Tabel berikut menjelaskan berbagai flag dan opsi yang dapat ditetapkan saat menggunakan perintah bundletool build-apks secara lebih mendetail:

Tabel 1. Opsi untuk perintah bundletool build-apks

Men-deploy APK ke perangkat yang terhubung

Setelah Anda membuat satu rangkaian APK, bundletool dapat men-deploy kombinasi APK yang tepat dari rangkaian tersebut ke perangkat yang terhubung.

Misalnya, jika Anda memiliki perangkat terhubung yang menjalankan Android 5.0 (API level 21) atau yang lebih tinggi, bundletool akan mengirim APK dasar, APK modul fitur, dan APK konfigurasi yang diperlukan untuk menjalankan aplikasi Anda di perangkat tersebut. Atau, jika perangkat yang terhubung menjalankan Android 4.4 (API level 20) atau lebih rendah, bundletool akan menelusuri multi-APK yang kompatibel untuk di-deploy ke perangkat.

Untuk men-deploy aplikasi dari rangkaian APK, gunakan perintah install-apks dan tentukan jalur rangkaian APK menggunakan flag --apks=/path/to/apks, seperti yang ditunjukkan dalam perintah berikut. Jika ada beberapa perangkat yang terhubung, tentukan perangkat target dengan menambahkan flag --device-id=serial-id.

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

Membuat rangkaian APK khusus perangkat

Jika Anda tidak ingin mem-build rangkaian APK untuk semua konfigurasi perangkat yang didukung oleh aplikasi, Anda dapat mem-build APK yang hanya menargetkan konfigurasi perangkat terhubung menggunakan opsi --connected-device, seperti yang ditunjukkan dalam perintah berikut. Jika ada beberapa perangkat yang terhubung, tentukan perangkat target dengan menambahkan flag --device-id=serial-id.

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

Membuat dan menggunakan file JSON spesifikasi perangkat

bundletool dapat membuat rangkaian APK yang menargetkan konfigurasi perangkat yang ditentukan oleh file JSON. Untuk membuat file JSON terlebih dahulu bagi perangkat yang terhubung, jalankan perintah berikut:

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

bundletool membuat file JSON untuk perangkat Anda di direktori alat. Kemudian, Anda dapat meneruskan file ke bundletool untuk membuat rangkaian APK yang hanya menargetkan konfigurasi yang dijelaskan dalam file JSON tersebut seperti berikut:

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

Membuat JSON spesifikasi perangkat secara manual

Jika tidak memiliki akses ke perangkat yang ingin digunakan untuk mem-build rangkaian APK yang ditargetkan, misalnya jika Anda ingin mencoba aplikasi Anda dengan perangkat yang tidak Anda miliki, Anda dapat membuat file JSON secara manual menggunakan format berikut:

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

Kemudian, Anda dapat meneruskan file JSON ini ke perintah bundle extract-apks, seperti yang dijelaskan di bagian sebelumnya.

Mengekstrak APK khusus perangkat dari APK yang sudah ada

Jika Anda sudah memiliki rangkaian APK dan ingin mengekstraknya untuk subset APK yang menargetkan konfigurasi perangkat tertentu, Anda dapat menggunakan perintah extract-apks dan menentukan JSON spesifikasi perangkat, seperti berikut:

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

Memperkirakan ukuran download APK dalam rangkaian APK

Untuk memperkirakan ukuran download APK dalam rangkaian APK karena akan disalurkan secara terkompresi melalui jaringan, gunakan perintah get-size total:

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

Anda dapat mengubah perilaku perintah get-size total menggunakan tanda berikut:

Tabel 2. Opsi untuk perintah get-size total

Mem-build app bundle dengan dependensi SDK bundle (eksperimental)

Anda dapat mem-build Android App Bundle dengan dependensi Android SDK Bundle (ASB) dari command line dan menandatanganinya menggunakan jarsigner.

Setiap modul app bundle berisi file Module Protocol Buffer (.pb): runtime_enabled_sdk_config.pb. File ini berisi daftar SDK yang menjadi dependensi modul app bundle. Untuk definisi lengkap file ini, lihat file runtime_enabled_sdk_config.proto.

Untuk mem-build app bundle dengan dependensi SDK bundle, ikuti langkah-langkah di bagian tentang mem-build app bundle menggunakan bundletool dan tambahkan file runtime_enabled_sdk_config.pb ke setiap zip modul aplikasi file dengan kode dan sumber daya yang dikompilasi.

Beberapa kolom penting dalam file runtime_enabled_sdk_config.pb:

• Digest sertifikat: digest SHA-256 sertifikat untuk kunci yang digunakan untuk menandatangani APK SDK. Hal ini sesuai dengan sertifikat pada file SdkMetadata.pb dalam format Android SDK Archive.

• ID Paket Resource: ID paket yang menjadi tujuan pemetaan ulang semua resource dalam SDK ini saat membuat APK untuk menyematkan SDK ke dalam aplikasi. Hal ini memungkinkan kompatibilitas mundur.

SDK hanya dapat muncul dalam satu modul. Jika beberapa modul bergantung pada SDK yang sama, dependensi ini harus dihapus duplikatnya dan dipindahkan ke modul dasar. Modul yang berbeda tidak dapat bergantung pada versi SDK yang berbeda.

Membuat APK dari app bundle dengan dependensi SDK bundle (eksperimental)

Untuk membuat APK dari app bundle, ikuti langkah-langkah di bagian tentang membuat rangkaian APK dari app bundle atau bagian tentang membuat rangkaian APK khusus perangkat dan memberikan perintah bundletool build-apks dengan SDK yang diandalkan aplikasi. SDK ini dapat disediakan dalam format SDK bundle atau format SDK Archive.

Anda dapat menyediakan SDK sebagai SDK bundle dengan menambahkan tanda --sdk-bundles, seperti berikut:

 bundletool build-apks --bundle=app.aab --sdk-bundles=sdk1.asb,sdk2.asb \     --output=app.apks 

Anda dapat menyediakan SDK sebagai SDK archive dengan menambahkan tanda --sdk-archives, seperti berikut:

 bundletool build-apks --bundle=app.aab --sdk-archives=sdk1.asar,sdk2.asar \     --output=app.apks 

Membuat APK dari app bundle dengan dependensi SDK bundle untuk perangkat tanpa dukungan library SDK

Perangkat sebelum Android 13 tidak mendukung penginstalan library SDK atau menjalankannya dalam runtime SDK. Bundletool menyembunyikan kompleksitas kompatibilitas mundur dan membuat beberapa varian rangkaian APK dari app bundle yang sama saat Anda jalankan bundletool build-apks dengan opsi --sdk-bundles atau --sdk-archives. Beberapa varian menargetkan perangkat dengan kemampuan yang berbeda:

• Ada varian untuk perangkat yang lebih baru, di mana SDK diinstal sebagai dari aplikasi dan APK aplikasi tidak menyertakan konten SDK apa pun.
• Ada satu atau beberapa varian untuk perangkat lama, tempat APK SDK ditambahkan ke APK aplikasi yang disetel sebagai pemisahan APK tambahan. APK SDK adalah milik aplikasi paket. Dalam hal ini, runtime SDK diemulasikan di runtime aplikasi pada perangkat seluler.

Mirip dengan cara membuat APK untuk app bundle tanpa dependensi SDK, bundletool extract-apks dan bundletool install-apks menampilkan kumpulan APK dari varian terbaik untuk perangkat yang terhubung atau untuk perangkat yang disediakan konfigurasi.

Untuk kasus penggunaan lanjutan saat Anda hanya tertarik untuk membuat pemisahan APK dari arsip SDK untuk aplikasi tertentu untuk perangkat yang lebih lama, gunakan Perintah bundletool build-sdk-apks-for-app sebagai berikut:

 bundletool build-sdk-apks-for-app --app-properties=app-properties.json \     --sdk-archive=sdk.asar --output=sdk.apks 

File app-properties harus berisi kolom yang dijelaskan dalam File runtime_enabled_sdk_config.proto. Inilah yang app-properties file tersebut terlihat seperti ini:

{   "package_name": "com.my.app",   "version_code": 1234,   "min_sdk_version": 21,   "resources_package_id": 0x7e } 

Perintah bundletool build-sdk-apks-for-app menghasilkan subset aplikasi APK yang sesuai dengan konten SDK di bawah nama paket aplikasi. Anda dapat menggabungkan APK tersebut dengan APK lain yang berisi konten aplikasi. Misalnya, jika Anda membuatnya secara terpisah dan bertahap, serta diinstal bersama pada perangkat yang tidak mendukung runtime SDK.

Mem-build dan menguji SDK bundle (eksperimental)

Anda dapat menggunakan bundletool untuk mem-build ASB dan menguji pembuatan file yang diperlukan untuk penginstalan dan distribusi.

Mem-build SDK bundle

Anda dapat mem-build ASB dari command line dan menandatanganinya menggunakan jarsigner.

Untuk mem-build SDK bundle, ikuti langkah-langkah berikut:

1. Buat manifes dan resource SDK bundle dalam format proto dengan mengikuti langkah-langkah yang sama seperti saat mem-build app bundle.

2. Kemas kompilasi kode dan resource SDK ke dalam file ZIP dasar, seperti yang Anda lakukan dengan modul aplikasi.

3. Buat file SdkModulesConfig.pb.json dan SdkBundleConfig.pb.json, yang cocok dengan format yang dijelaskan dalam spesifikasi Android SDK Bundle.

4. Build ASB Anda menggunakan perintah bundletool build-sdk-bundle, seperti berikut:

 bundletool build-sdk-bundle --sdk-bundle-config=SdkBundleConfig.pb.json \     --sdk-modules-config=SdkModulesConfig.pb.json \     --modules=base.zip --output=sdk.asb 

Tabel berikut menjelaskan berbagai flag dan opsi yang dapat ditetapkan saat menggunakan perintah bundletool build-sdk-bundle secara lebih mendetail.

Tabel 3. Opsi untuk perintah bundletool build-sdk-bundle

Membuat APK dari SDK bundle

Setelah mem-build ASB, Anda dapat menguji SDK bundle secara lokal dengan membuat APK menggunakan perintah bundletool build-sdk-apks, seperti ditunjukkan dalam kode berikut:

 bundletool build-sdk-apks --sdk-bundle=sdk.asb --output=sdk.apks 

Saat bundletool membuat APK dari SDK bundle Anda, alat ini akan menyertakan APK dalam penampung yang disebut arsip rangkaian APK, yang menggunakan ekstensi file .apks. bundletool membuat satu APK mandiri dari SDK bundle yang menargetkan semua konfigurasi perangkat.

Jika ingin men-deploy ASB ke perangkat, Anda juga harus menyertakan informasi penandatanganan aplikasi, seperti yang ditunjukkan dalam perintah berikut.

 bundletool build-sdk-apks --sdk-bundle=sdk.asb --output=sdk.apks \     --ks=keystore.jks \     --ks-pass=file:/keystore.pwd \     --ks-key-alias=KeyAlias \     --key-pass=file:/key.pwd 

Tabel berikut menjelaskan berbagai flag dan opsi yang dapat ditetapkan saat menggunakan perintah bundletool build-sdk-apks secara lebih mendetail.

Tabel 4. Opsi untuk perintah bundletool build-sdk-apks

Men-deploy, mengekstrak, dan mengukur ukuran APK SDK

Anda dapat mengikuti langkah-langkah yang sama seperti yang digunakan untuk aplikasi guna men-deploy APK ke perangkat terhubung, mengekstrak APK khusus perangkat dari rangkaian APK yang ada, dan mengukur perkiraan ukuran download APK dalam rangkaian APK.

Membuat SDK Archive dari SDK bundle

Setelah mengupload ASB ke saluran distribusi, misalnya Google Play, ASB akan diubah menjadi Android SDK Archive (.asar) untuk didistribusikan kepada developer aplikasi melalui Maven. Untuk mengetahui detail selengkapnya tentang format yang digunakan, lihat bagian Spesifikasi pemformatan SDK Archive.

Setelah mem-build ASB, Anda dapat menguji pembuatan Android SDK Archive secara lokal menggunakan perintah bundletool build-sdk-asar, seperti yang ditunjukkan dalam kode berikut:

 bundletool build-sdk-asar --sdk-bundle=sdk.asb --output=sdk.asar \     --apk-signing-key-certificate=keycert.txt 

Tabel berikut menjelaskan berbagai flag dan opsi yang dapat ditetapkan saat menggunakan perintah bundletool build-sdk-asar secara lebih mendetail.

Tabel 5. Opsi untuk perintah bundletool build-sdk-asar

Format SDK yang mendukung runtime (eksperimental)

SDK yang mendukung runtime memperkenalkan dua format file Android:

• Android SDK Bundle (.asb) yang digunakan untuk memublikasikan SDK yang mendukung runtime ke app store.
• Android SDK Archive (.asar) yang digunakan untuk mendistribusikan SDK yang mendukung runtime di Maven.

Format Android SDK Bundle

SDK Bundle adalah format publikasi untuk SDK yang mendukung runtime. Format ini berisi semua resource dan kode SDK, termasuk kode dari library mana pun yang menjadi dependensi SDK. Format ini tidak menyertakan kode dan resource SDK lain yang mendukung runtime yang menjadi dependensi SDK.

Android SDK Bundle (ASB) adalah file zip yang ditandatangani dengan ekstensi .asb. Kode dan resource SDK diatur di dalamnya, mirip dengan yang akan Anda temukan di APK. ASB juga berisi beberapa file konfigurasi yang membantu menghasilkan APK yang dapat diinstal.

Daftar berikut menjelaskan beberapa file ASB secara lebih mendetail:

• SdkBundleConfig.pb: File konfigurasi dalam format proto yang berisi daftar SDK yang mendukung runtime yang menjadi dependensi SDK Anda. Untuk definisi lengkap, lihat file sdk_bundle_config.proto.

• modules.resm: File ZIP yang berisi semua data yang diperlukan untuk menghasilkan APK dari SDK.

• SdkModulesConfig.pb: File konfigurasi dalam format proto. File ini berisi nama dan versi SDK, serta nama class titik entri SDK untuk framework (SandboxedSdkProvider). Untuk mengetahui definisi lengkapnya, lihat file sdk_modules_config.proto.

• base/: Satu modul yang berisi kode dan resource SDK.

  • manifest/: Manifes SDK dalam format proto.
  • dex/: Kode yang dikompilasi dalam format DEX. Beberapa file DEX dapat disediakan.
  • res/, lib/, assets/: Direktori ini identik dengan direktori dalam APK standar. Jalur dalam direktori ini dipertahankan saat membuat APK SDK.
  • root/: Direktori ini menyimpan file yang nantinya dipindahkan ke root APK SDK. Misalnya, direktori mungkin menyertakan resource berbasis Java yang dimuat SDK Anda menggunakan metode Class.getResource(). Jalur dalam direktori ini juga dipertahankan.

• BUNDLE-METADATA: Direktori ini mencakup file metadata yang berisi informasi yang berguna untuk alat atau app store. File metadata tersebut dapat mencakup pemetaan ProGuard dan daftar lengkap file DEX SDK Anda. File dalam direktori ini tidak dipaketkan ke dalam APK SDK Anda.

Format Android SDK Archive

Android SDK Archive adalah format distribusi SDK yang mendukung runtime di Maven. Ini adalah file zip dengan ekstensi file .asar. File ini berisi semua informasi yang diperlukan oleh alat build aplikasi untuk membuat Android App Bundle yang bergantung pada SDK yang mendukung runtime.

Daftar berikut menjelaskan beberapa file Android SDK Archive secara lebih mendetail:

• SdkMetadata.pb: File konfigurasi dalam format proto, yang berisi nama, versi, dan digest sertifikat SDK untuk kunci yang digunakan untuk menandatangani APK yang dihasilkan untuk SDK ini. Untuk definisi lengkap, lihat file sdk_metadata.proto.

• modules.resm: File ZIP yang berisi semua data yang diperlukan untuk menghasilkan APK dari SDK. File ini sama dengan file .resm di Android SDK Bundle.

• AndroidManifest.xml: File manifes SDK dalam format XML teks.

Referensi lainnya

Untuk mempelajari penggunaan bundletool lebih lanjut, tonton App Bundle: Menguji paket dengan bundletool dan Konsol Play.