bundletool

bundletool은 Android 스튜디오, Android Gradle 플러그인 및 Google Play에서 Android App Bundle을 빌드하고 App Bundle을 기기에 배포되는 다양한 APK로 변환하는 데 사용하는 기본 도구입니다. bundletool은 명령줄 도구로도 사용할 수 있으므로 App Bundle을 직접 빌드하고 앱 APK의 Google Play 서버 측 빌드를 다시 만들 수 있습니다.

bundletool 다운로드

아직 bundletool을 다운로드하지 않은 경우 GitHub 저장소에서 다운로드하세요.

App Bundle 빌드

Android App Bundle을 빌드하고 서명하려면 Android 스튜디오 및 Gradle용 Android 플러그인을 사용해야 합니다. 그러나 IDE 사용 옵션이 없다면(예: 연속 빌드 서버를 사용하는 경우) 명령줄에서 App Bundle을 빌드하고 jarsigner를 사용하여 App Bundle에 서명할 수도 있습니다.

bundletool로 App Bundle을 빌드하는 방법에 관한 자세한 내용은 bundletool을 사용하여 App Bundle 빌드를 참고하세요.

App Bundle에서 APK 집합 생성

Android App Bundle을 빌드한 후에는 Google Play에서 어떻게 Android App Bundle을 사용하여 APK를 생성하는지, APK가 기기에 배포되었을 때 어떻게 작동하는지 테스트해야 합니다. App Bundle을 두 가지 방식으로 테스트할 수 있습니다. 하나는 bundletool 명령줄 도구를 사용하여 로컬에서 테스트하는 것이고 다른 하나는 App Bundle을 Play Console에 업로드하고 테스트 트랙을 사용하여 Google Play를 통해 테스트하는 것입니다. 이 섹션에서는 bundletool을 사용하여 App Bundle을 로컬에서 테스트하는 방법을 설명합니다.

bundletool이 App Bundle에서 APK를 생성하면 .apks 파일 확장자를 사용하여 APK 집합 자료실이라는 컨테이너에 포함합니다. App Bundle에서 앱이 지원하는 모든 기기 설정에 APK 집합을 생성하려면 아래와 같이 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 및 --output만 필수이고 다른 플래그는 모두 선택사항입니다.

플래그	설명
`--bundle=path`	(필수) Android 스튜디오를 사용하여 빌드한 App Bundle의 경로를 지정합니다. 자세한 내용은 프로젝트 빌드를 참고하세요.
`--output=path`	(필수) 앱의 APK 아티팩트를 모두 포함하는 출력 '.apks' 파일의 이름을 지정합니다. 기기에서 이 파일의 아티팩트를 테스트하려면 연결된 기기에 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`	`bundletool`이 앱의 코드와 리소스가 모두 포함된 단일 APK만 빌드하여 APK가 앱에서 지원하는 모든 기기 설정과 호환되도록 하려면 모드를 `universal`로 설정합니다. 참고: `bundletool`에는 범용 APK의 매니페스트에서 `<dist:fusing dist:include="true"/>`를 지정하는 기능 모듈만 포함됩니다. 자세한 내용은 기능 모듈 매니페스트를 참조하세요. 이러한 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`	크기 예상값을 계산할 때 사용되는 측정기준을 지정합니다. 쉼표로 구분된 `SDK`, `ABI`, `SCREEN_DENSITY`, `LANGUAGE` 목록을 허용합니다. 모든 측정기준을 평가하려면 `ALL`을 지정합니다.
`--instant`	설치 가능한 APK 대신 인스턴트 지원 APK의 다운로드 크기를 측정합니다. 기본적으로 `bundletool`은 설치 가능한 APK 다운로드 크기를 측정합니다.
`--modules=modules`	측정 시 고려해야 할 APK 집합에서 쉼표로 구분된 모듈 목록을 지정합니다. `bundletool` 명령어는 지정된 집합의 모든 종속 모듈을 자동으로 포함합니다. 기본적으로 이 명령어는 첫 번째 다운로드 중에 설치된 모든 모듈의 다운로드 크기를 측정합니다.

추가 리소스

bundletool 사용에 관한 자세한 내용은 다음 리소스를 참조하세요.

Codelab

첫 번째 Android App Bundle: Android App Bundle의 기본 원리를 살펴보고 Android 스튜디오를 사용하여 자신만의 고유한 App Bundle 구성을 빠르게 시작하는 방법을 보여주는 Codelab입니다. 이 Codelab에서는 bundletool을 사용해 App Bundle을 테스트하는 방법도 알아봅니다.