Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

bundletool

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

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

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

기본적으로 IDE는 테스트용 로컬 기기에 앱을 배포하기 위해 App Bundle을 사용하지 않습니다. 그러나 실행/디버그 구성을 수정하고 앱 실행에 미치는 영향을 확인하기 위해 App Bundle의 APK를 배포하는 옵션을 선택할 수 있습니다.

bundletool 다운로드

아직 하지 않았으면 GitHub 저장소에서 bundletool을 다운로드합니다.

App Bundle에서 APK 집합 생성

bundletool은 App Bundle에서 APK를 생성한 후 .apks라는 파일 확장자를 사용하여 APK set archive라는 컨테이너에 포함합니다. 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 APK가 앱이 지원하는 모든 기기 구성과 호환되도록 앱의 모든 코드와 리소스를 포함하는 단일 APK를 bundletool에서 빌드하도록 하려면 모드를 universal로 설정합니다.

참고: bundletool은 보편적 APK의 manifest에 <dist:fusing dist:include="true"/>를 지정하는 동적 기능 모듈만 포함합니다. 자세히 알아보려면 동적 기능 모듈 manifest를 참조하세요.

이러한 APK는 특정 기기 구성에 맞게 최적화된 것보다 더 큽니다. 그러나 여러 기기 구성에서 앱을 테스트하려는 내부 테스터와 더 쉽게 공유할 수 있습니다.

연결된 기기에 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_DENSITYLANGUAGE). 모든 측정기준으로 계산하려면 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을 테스트하는 방법도 알아봅니다.