bundletool

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

bundletool は、Android Studio、Android Gradle プラグイン、Google Play が Android App Bundle をビルドしたり、App Bundle を各種 APK に変換してデバイスにデプロイしたりする際に基盤となるツールです。Android SDK Bundle とその APK も、bundletool を使用してビルドされます。bundletool はコマンドライン ツールとしても利用できるため、App Bundle と SDK Bundle を自分でビルドして、アプリの APK またはランタイム対応の SDK の APK に対する Google Play のサーバー側のビルドを再作成することが可能です。

bundletool をダウンロードする

まだダウンロードしていない場合は、GitHub リポジトリから bundletool をダウンロードしてください。

App Bundle をビルドしてテストする

Android Studio または bundletool コマンドライン ツールを使用して Android App Bundle をビルドし、この App Bundle から APK を生成するテストを行えます。

App Bundle をビルドする

Android App Bundle をビルドして署名するには、Android Studio と Android Plugin for Gradle を使用する必要があります。ただし、IDE を使用しない場合(継続的なビルドサーバーを使用しているなどの理由で)、コマンドラインから App Bundle をビルドして、jarsigner を使って署名することもできます。

bundletool を使用して App Bundle をビルドする方法についての詳細は、bundletool を使用して App Bundle をビルドするをご覧ください。

App Bundle から APK のセットを生成する

Android App Bundle をビルドした後、Google Play で App Bundle から生成される APK と、デバイスにデプロイされたときの APK の動作をテストする必要があります。App Bundle をテストするには、2 つの方法が考えられます。bundletool コマンドライン ツールをローカルに使用する方法と Google Play でテストする方法です。Google Play でテストする場合、Play Console に App Bundle をアップロードしてテストトラックを使用します。このセクションでは、bundletool を使用して App Bundle をローカルにテストする方法について説明します。

bundletool が App Bundle から生成する APK は、APK セット アーカイブと呼ばれるコンテナに格納されます。このアーカイブは .apks ファイル拡張子を使用します。アプリがサポートするすべてのデバイス設定に対する APK セットを App Bundle から生成するには、下記のように bundletool build-apks コマンドを使用します。

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

APK をデバイスにデプロイする場合、下記のコマンドのように、アプリの署名情報も含める必要があります。署名情報を指定しない場合、bundletool はデバッグ鍵を使用して APK の署名を試みます。

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

下記の表で、bundletool build-apks コマンドを使用する際に設定できるさまざまなフラグとオプションについて詳しく説明します。

フラグ 説明
--bundle=path (必須)Android Studio を使ってビルドした App Bundle へのパスを指定します。詳細については、プロジェクトのビルドをご覧ください。
--output=path (必須)出力する .apks ファイルの名前を指定します。これには、そのアプリのすべての APK アーティファクトが含まれます。このファイル内のアーティファクトをデバイス上でテストするには、接続されているデバイスに APK をデプロイする方法をご覧ください。
--overwrite --output オプションを使って指定したパスにある既存の出力ファイルを上書きする場合に、このフラグを指定します。このフラグを指定せず、出力ファイルがすでにある場合、ビルドエラーが発生します。
--aapt2=path AAPT2 へのカスタムパスを指定します。デフォルトで、bundletool には独自のバージョンの AAPT2 が含まれます。
--ks=path APK の署名に使用するデプロイ キーストアへのパスを指定します。このフラグは省略可能です。指定しない場合、bundletool はデバッグ署名鍵を使用して APK の署名を試みます。
--ks-pass=pass:password
または
--ks-pass=file:/path/to/file
キーストアのパスワードを指定します。パスワードを書式なしテキストで指定する場合は、pass: を付けます。パスワードが記載されているファイルへのパスを渡す場合は、file: を付けます。--ks-pass を指定せずに --ks フラグを使用してキーストアを指定する場合、コマンドラインからパスワードを入力するように bundletool から求められます。
--ks-key-alias=alias 使用する署名鍵のエイリアスを指定します。
--key-pass=pass:password
または
--key-pass=file:/path/to/file
署名鍵のパスワードを指定します。パスワードを書式なしテキストで指定する場合は、pass: を付けます。パスワードが記載されているファイルへのパスを渡す場合は、file: を付けます。

このパスワードがキーストアのパスワードと同じであれば、このフラグを省略できます。

--connected-device 接続されているデバイスの設定を対象とする APK をビルドするように bundletool に指示します。このフラグを指定しない場合、bundletool はアプリがサポートするすべてのデバイス設定を対象に APK を生成します。
--device-id=serial-number 接続されているデバイスが複数ある場合、アプリをデプロイするデバイスのシリアル ID をこのフラグで指定します。
--device-spec=spec_json 対象とするデバイス設定を指定する .json ファイルへのパスをこのフラグで指定します。詳しくは、デバイス仕様の JSON ファイルを生成して使用する方法についての記事をご覧ください。
--mode=universal モードを universal に設定して、アプリのコードとリソースをすべて含む単一の APK のみ、bundletool でビルドします。これにより、アプリでサポートするすべてのデバイス設定と互換性のある APK となります。

注: bundletool は、マニフェストに <dist:fusing dist:include="true"/> の指定がある機能モジュールのみをユニバーサル APK に含めます。詳細については、機能モジュールのマニフェストをご覧ください。

こうした APK は、特定のデバイス設定用に最適化された APK よりもサイズが大きくなるのでご注意ください。ただし、複数のデバイス設定でアプリをテストする社内テスターとの共有などは簡単になります。

--local-testing ローカルテスト用の App Bundle を有効にするには、このフラグを使用します。ローカルテストでは、Google Play サーバーへのアップロードが不要で、テストサイクルをすぐに繰り返し実行できます。

--local-testing フラグを使用してモジュール インストールをテストする方法の例については、モジュール インストールをローカルでテストするをご覧ください。

接続されているデバイスに APK をデプロイする

APK のセットを生成した後、bundletool は、そのセットから APK の適切な組み合わせを、接続されているデバイスにデプロイできます。

たとえば Android 5.0(API レベル 21)以上を搭載するデバイスが接続されている場合、bundletool はそのデバイスでアプリを実行するのに必要なベース APK、機能モジュール APK、設定 APK をプッシュします。または、Android 4.4(API レベル 20)以下を搭載するデバイスが接続されている場合、bundletool は互換性のあるマルチ APK を探して、そのデバイスにデプロイします。

APK セットからアプリをデプロイするには、下記のように install-apks コマンドを使用して、--apks=/path/to/apks フラグで APK セットのパスを指定します(複数のデバイスが接続されている場合、--device-id=serial-id フラグを追加して、対象デバイスを指定します)。

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

デバイス固有の APK セットを生成する

アプリがサポートするすべてのデバイス設定に対する APK セットをビルドする代わりに、下記のように --connected-device オプションを使用して、接続されているデバイスの設定のみを対象とする APK をビルドできます(複数のデバイスが接続されている場合、--device-id=serial-id フラグを追加して、対象デバイスを指定します)。

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

デバイス仕様の JSON ファイルを生成して使用する

bundletool は JSON ファイルに指定されたデバイス設定を対象とする APK セットを生成できます。まず、接続されているデバイスについて JSON ファイルを生成するために、次のコマンドを実行します。

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

bundletool はデバイスの JSON ファイルを、自身が置かれているディレクトリに作成します。次に下記のように、そのファイルを bundletool に渡して、その JSON ファイルに記載されている設定のみを対象とする APK セットを生成できます。

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

デバイス仕様の JSON を手動で作成する

APK セットをビルドする対象のデバイスにアクセスできない場合(たとえば、デベロッパーの手元にないデバイスで友だちがアプリを試そうとする場合)、次の形式に沿って JSON ファイルを手動で作成できます。

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

その後、前述のように、この JSON を bundle extract-apks コマンドに渡すことができます。

既存の APK セットからデバイス固有の APK を抽出する

既存の APK セットから、特定のデバイス設定を対象とする APK のサブセットを抽出する場合、次のように extract-apks コマンドを使用して、デバイス仕様の JSON を指定します。

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

APK セット内の APK の推定ダウンロード サイズを見積もる

圧縮されて有線で配信される APK セット内の APK の推定ダウンロード サイズを見積もるには、get-size total コマンドを使用します。

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

以下のフラグを使用して get-size total コマンドの動作を変更できます。

フラグ 説明
--apks=path (必須)ダウンロード サイズを見積もる既存の APK セットのファイルへのパスを指定します。
--device-spec=path 照合に使用するデバイス仕様のファイル(get-device-spec からまたは手動で構成)へのパスを指定します。部分的なパスを指定して、設定のセットについて見積もることもできます。
--dimensions=dimensions 推定サイズを見積もるのに使用するディメンションを指定します。SDKABISCREEN_DENSITYLANGUAGE のカンマ区切りのリストを指定できます。すべてのディメンションにわたって見積もるには、ALL を指定します。
--instant インストール可能な APK ではなく、Instant を有効にした APK のダウンロード サイズを見積もります。デフォルトで、bundletool はインストール版 APK のダウンロード サイズを見積もります。
--modules=modules 見積もりで考慮する APK セットのモジュールをカンマ区切りのリストで指定します。bundletool コマンドを使用すると、指定したセットの依存関係モジュールが自動的にすべて含まれます。デフォルトで、このコマンドは初回ダウンロードでインストールされるすべてのモジュールのダウンロード サイズを見積もります。

SDK Bundle の依存関係を持つ App Bundle をビルドしてテストする(試験運用版)

bundletool を使用すると、Android SDK Bundle の依存関係を持つ Android App Bundle をビルドし、そこから APK の生成をテストできます。

SDK Bundle の依存関係を持つ App Bundle をビルドする

コマンドラインから Android SDK Bundle の依存関係を持つ Android App Bundle をビルドし、jarsigner を使用して署名できます。

各 App Bundle モジュールには、runtime_enabled_sdk_config.pb というモジュール プロトコル バッファ(.pb)ファイルが含まれています。このファイルには、App Bundle モジュールが依存する SDK のリストが含まれています。このファイルの定義の全文については、runtime_enabled_sdk_config.proto ファイルをご覧ください。

SDK Bundle の依存関係を持つ App Bundle をビルドするには、同じガイドに従い、bundletool を使用して App Bundle をビルドします。ただし、今回はコンパイル済みコードとリソースを含む各アプリ モジュールの ZIP ファイルに runtime_enabled_sdk_config.pb ファイルを追加します。

runtime_enabled_sdk_config.pb ファイルにある注目すべきフィールドについて説明します。

  • 証明書ダイジェスト: SDK の APK の署名に使用される鍵の証明書の SHA-256 ダイジェスト。これは、Android SDK Archive フォーマットSdkMetadata.pb ファイル内の証明書に対応します。

  • リソース パッケージ ID: SDK をアプリに埋め込むための APK を生成するときに、この SDK 内のすべてのリソースが再マッピングされるパッケージ ID。これにより、下位互換性が確保されます。

SDK は 1 つのモジュールにのみ表示できます。複数のモジュールが同じ SDK に依存している場合は、この依存関係の重複を除去してベース モジュールに移動させる必要があります。各モジュールがそれぞれ異なるバージョンの SDK に依存することはできません。

SDK Bundle の依存関係を持つ App Bundle から APK を生成する

App Bundle から APK を生成するには、App Bundle から APK のセットを生成する、またはデバイス固有の APK セットを生成すると同じ手順を実施します。ただし、今回はアプリが依存する SDK を bundletool build-apks コマンドに指定する必要があります。この SDK は、SDK Bundle フォーマットまたは SDK Archive フォーマットで指定できます。

次のように --sdk-bundles フラグを追加すると、SDK を SDK Bundle として指定できます。

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

次のように --sdk-archives フラグを追加することで、SDK を SDK Archive として指定できます。

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

SDK Bundle をビルドしてテストする(試験運用版)

bundletool を使用して Android SDK Bundle をビルドし、インストールと配信に必要なファイルの生成をテストできます。

SDK Bundle をビルドする

コマンドラインから Android SDK Bundle(ASB)をビルドし、jarsigner を使用して署名できます。

SDK Bundle をビルドする手順は次のとおりです。

  1. App Bundle と同じ手順に沿って、SDK Bundle のマニフェストとリソースを proto 形式で生成します。

  2. アプリ モジュールの場合と同様に、SDK のコンパイル済みコードとリソースをベース ZIP ファイルにパッケージ化します。

  3. Android SDK Bundle 仕様で説明されている形式に一致する SdkModulesConfig.pb.json ファイルと SdkBundleConfig.pb.json ファイルを生成します。

  4. 次のように bundletool build-sdk-bundle コマンドを使用して、SDK Bundle をビルドします。

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

下記の表で、bundletool build-sdk-bundle コマンドを使用する際に設定できるさまざまなフラグとオプションについて詳しく説明します。

フラグ 説明
--modules (必須)最終的な Android SDK Bundle のビルド元となるモジュール ファイル。
--output (必須)Android SDK Bundle をビルドする場所へのパス。
--sdk-modules-config (必須)SDK モジュールの構成を記述する JSON ファイルへのパス。JSON ファイルの形式については、Android SDK Bundle の仕様をご覧ください。
--sdk-bundle-config SDK Bundle の構成を記述する JSON ファイルへのパス。JSON ファイルの形式については、Android SDK Bundle の仕様をご覧ください。
--metadata-file Android SDK Bundle にメタデータとして含めるファイルを指定します。フラグ値の形式は <bundle-path>:<physical-file> です。ここで、<bundle-path> は SDK Bundle のメタデータ ディレクトリ内のファイルの場所、<physical-file> は元データが格納される既存ファイルを表します。このフラグは繰り返し指定できます。
--overwrite 設定すると、以前の出力は上書きされます。

SDK Bundle から APK を生成する

Android SDK Bundle をビルドした後、以下のコードに示すように、bundletool build-sdk-apks コマンドを使用して APK を生成することで、SDK Bundle をローカルでテストできるようになります。

bundletool が SDK Bundle から生成する APK は、APK セット アーカイブと呼ばれるコンテナに格納されます。このアーカイブは .apks ファイル拡張子を使用します。bundletool は、すべてのデバイス設定を対象とする SDK Bundle からスタンドアロン APK を生成します。

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

ASB をデバイスにデプロイする場合、下記のコマンドのように、アプリの署名情報も含める必要があります。署名情報を指定しない場合、bundletool はデバッグ鍵を使用して APK の署名を試みます。

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

下記の表で、bundletool build-sdk-apks コマンドを使用する際に設定できるさまざまなフラグとオプションについて詳しく説明します。

フラグ 説明
--sdk-bundle (必須)SDK Bundle へのパス。拡張子は .asb にする必要があります。
--output (必須)デフォルトでの、APK セット アーカイブを作成する場所へのパス。または、--output-format=DIRECTORY を使用する場合、生成済み APK が格納されるディレクトリへのパスになります。
--ks 生成された APK の署名に使用するキーストアへのパス。
--ks-key-alias 生成された APK に署名するためにキーストアで使用する鍵のエイリアス。
--key-pass 生成された APK の署名に使用するキーストアの鍵のパスワード。クリアテキストでパスワードを渡す場合は、値の先頭に pass: を付ける必要があります(例: pass:qwerty)。パスワードがファイルの先頭行の場合は、値の先頭に file: を付ける必要があります(例: file:/tmp/myPassword.txt)。このフラグが設定されていない場合、キーストアのパスワードが試みられます。失敗した場合、コマンドライン ターミナルからパスワードの入力を求められます。
--ks-pass 生成された APK の署名に使用するキーストアのパスワード。クリアテキストでパスワードを渡す場合は、値の先頭に pass: を付ける必要があります(例: pass:qwerty)。パスワードがファイルの先頭行の場合は、値の先頭に file: を付ける必要があります(例: file:/tmp/myPassword.txt)。このフラグが設定されていない場合、コマンドライン ターミナルからパスワードの入力を求められます。
--aapt2 使用する AAPT2 バイナリへのパス。
--output-format 生成される APK の出力形式を指定します。デフォルトでは、APK_SET に設定されています。これにより、生成される APK セット アーカイブに APK が出力されます。DIRECTORY に設定すると、--output で指定されたディレクトリに APK が出力されます。
--verbose 設定すると、コマンドの実行に関する追加情報が標準出力に出力されます。
--version-code SDK バージョン コード。これは、SDK バージョンではなく、Android プラットフォームが APK のインストールに使用するバージョン コードです。任意の値に設定できます。設定しなかった場合は、デフォルトの 0 が使用されます。
--overwrite 設定すると、以前の出力は上書きされます。

SDK Bundle から SDK Archive を生成する

Android SDK Bundle を配布チャネル(Google Play など)にアップロードすると、Android SDK Bundle は Android SDK Archive(.asar)に変換され、Maven を介してアプリ デベロッパーに配布されます。フォーマットの詳細については、SDK Archive フォーマットの仕様をご覧ください。

Android SDK Bundle をビルドした後、以下のコードに示すように、bundletool build-sdk-asar コマンドを使用して Android SDK Archive の生成をローカルでテストできるようになります。

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

下記の表で、bundletool build-sdk-asar コマンドを使用する際に設定できるさまざまなフラグとオプションについて詳しく説明します。

フラグ 説明
--apk-signing-key-certificate (必須)SDK APK 署名証明書へのパス。これは、build-sdk-apks コマンドで APK の署名に使用した鍵に対応する証明書です。
--output (必須).asar ファイルを作成する場所へのパス。
--sdk-bundle (必須)SDK Bundle へのパス。拡張子は .asb にする必要があります。
--overwrite 設定すると、以前の出力は上書きされます。

ランタイム対応 SDK のフォーマット(試験運用版)

ランタイム対応 SDK には、2 つの Android ファイル形式が導入されています。Android SDK Bundle.asb)は、ランタイム対応の SDK をアプリストアに公開するために使用され、Android SDK Archive.asar)は、Maven 上でランタイム対応の SDK を配布するために使用されます。

Android SDK Bundle フォーマット

SDK Bundle は、ランタイム対応 SDK の公開フォーマットです。これには、SDK が依存するライブラリのコードも含め、SDK のコードとリソースがすべて含まれています。SDK が依存する他のランタイム対応 SDK のコードとリソースは含まれません。

Android SDK Bundle は、拡張子が .asb の署名付き ZIP ファイルです。SDK のコードとリソースは APK に含まれるものと同様に構成されています。ASB には、インストール可能な APK の生成に役立つ複数の構成ファイルも含まれています。

図 1. Android SDK Bundle のコンテンツ

以下に、Android SDK Bundle ファイルの一部について詳細を説明します。

  • SdkBundleConfig.pb: SDK が依存するランタイム対応 SDK のリストを含む proto 形式の構成ファイル。定義の全文については、sdk_bundle_config.proto ファイルをご覧ください。

  • modules.resm: SDK から APK を生成するために必要なすべてのデータを含む ZIP ファイル。

  • SdkModulesConfig.pb: proto 形式の構成ファイル。このファイルには、フレームワーク(SandboxedSdkProvider)の SDK エントリ ポイントの SDK 名、バージョン、クラス名が含まれています。定義の全文については、sdk_modules_config.proto ファイルをご覧ください。

  • base/: SDK のコードとリソースを含む単一のモジュール。

    • manifest/: SDK のマニフェスト(proto 形式)。
    • dex/: コンパイル済みコード(DEX 形式)。複数の DEX ファイルを指定できます。
    • res/lib/assets/: これらのディレクトリは、一般的な APK でのディレクトリと同じです。このディレクトリ パスは、SDK の APK の生成時に保持されます。
    • root/: このディレクトリには、後で SDK APK のルートに再配置されるファイルが保存されます。たとえば、SDK で Class.getResource() メソッドを使用して読み込む Java ベースのリソースなどが該当します。このディレクトリ内のパスも保持されます。
    • BUNDLE-METADATA: このディレクトリにはメタデータ ファイルが含まれます。このファイルには、ツールやアプリストアで利用できる情報が含まれます。このようなメタデータ ファイルに、ProGuard マッピングや SDK の DEX ファイルの全リストが含まれることもあります。このディレクトリ内のファイルは、SDK の APK にパッケージ化されません。

Android SDK Archive フォーマット

Android SDK Archive は、Maven 上のランタイム対応 SDK の配信フォーマットです。これは、.asar というファイル拡張子を含む ZIP ファイルです。アプリビルド ツールで、ランタイム対応 SDK に依存する Android App Bundle を生成するために必要なすべての情報が含まれています。

図 2. Android SDK Archive Bundle のコンテンツ

以下に、Android SDK Bundle ファイルの一部について詳細を説明します。

  • SdkMetadata.pb: 構成ファイル(proto 形式)。この SDK 用に生成される APK の署名に使用される鍵の SDK 名、バージョン、証明書ダイジェストが含まれます。定義の全文については、sdk_metadata.proto ファイルをご覧ください。

  • modules.resm: SDK から APK を生成するために必要なすべてのデータを含む ZIP ファイル。これは、Android SDK Bundle.resm ファイルと同じです。

  • AndroidManifest.xml: SDK のマニフェスト ファイル(XML 形式)。

参考情報

bundletool の使用方法について詳しくは、下記のリソースをご覧ください。

Codelab

  • 初めての Android App Bundle: Android App Bundle の基本原則を探り、Android Studio を使用して独自のビルドをすぐに始める方法を示すコードラボです。この CodeLab は、bundletool を使用して App Bundle をテストする方法についても紹介します。