пакетный инструмент

bundletool — это базовый инструмент, который Android Studio, плагин Android Gradle и Google Play используют для создания пакета приложений Android. bundletool может конвертировать пакет приложений в различные APK-файлы, которые развертываются на устройствах.

Пакеты Android SDK (ASB) и их APK создаются с помощью bundletool . Он также доступен в виде инструмента командной строки, поэтому вы можете самостоятельно создавать пакеты приложений и пакеты SDK, а также заново создавать серверную сборку Google Play APK-файлов вашего приложения или APK-файлов SDK с поддержкой среды выполнения .

Скачать bundletool

Если вы еще этого не сделали, скачайте bundletool из репозитория GitHub .

Создайте и протестируйте пакет приложений

Вы можете использовать Android Studio или инструмент командной строки bundletool для создания пакета приложений Android, а затем протестировать создание APK-файлов из этого пакета приложений.

Создайте пакет приложений

Используйте Android Studio и плагин Android Gradle для создания и подписания пакета приложений Android . Однако если использование IDE невозможно (например, если вы используете сервер непрерывной сборки), вы также можете собрать пакет приложений из командной строки и подписать его с помощью jarsigner .

Дополнительные сведения о создании пакетов приложений с помощью bundletool см. в разделе Создание пакета приложений с помощью Bundletool .

Создайте набор APK-файлов из пакета приложений.

После создания пакета Android App Bundle проверьте, как Google Play использует его для создания APK и как эти APK ведут себя при развертывании на устройстве.

Есть два способа протестировать пакет приложений:

• Используйте инструмент командной строки bundletool локально.
• Загрузите свой пакет в Play Console через Google Play, используя тестовую версию.

В этом разделе объясняется, как использовать bundletool для локального тестирования вашего пакета приложений.

Когда bundletool создает APK-файлы из вашего пакета приложений, он включает сгенерированные APK-файлы в контейнер, называемый архивом набора APK , который использует расширение файла .apks . Чтобы создать набор 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 :

Таблица 1. Параметры команды bundletool build-apks

Развертывание APK-файлов на подключенном устройстве

После того как вы создадите набор APK, bundletool может развернуть нужную комбинацию APK из этого набора на подключенное устройство.

Например, если у вас есть подключенное устройство под управлением Android 5.0 (уровень API 21) или выше, bundletool передает базовый APK, APK функциональных модулей и APK конфигурации, необходимые для запуска вашего приложения на этом устройстве. Альтернативно, если ваше подключенное устройство работает под управлением Android 4.4 (уровень API 20) или ниже, bundletool ищет совместимый мульти-APK для развертывания на вашем устройстве.

Чтобы развернуть приложение из набора APK, используйте команду install-apks и укажите путь к набору APK с помощью флага --apks= /path/to/apks , как показано в следующей команде. Если у вас подключено несколько устройств, укажите целевое устройство, добавив флаг --device-id= serial-id .

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

Создайте набор APK для конкретного устройства.

Если вы не хотите создавать набор APK для всех конфигураций устройств, которые поддерживает ваше приложение, вы можете создать APK, предназначенные только для конфигурации подключенного устройства, с помощью параметра --connected-device , как показано в следующей команде. Если у вас подключено несколько устройств, укажите целевое устройство, включив флаг --device-id= serial-id .

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

Создание и использование файлов JSON со спецификациями устройств.

bundletool может создать набор APK, ориентированный на конфигурацию устройства, указанную в файле JSON. Чтобы сначала создать файл JSON для подключенного устройства, выполните следующую команду:

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

bundletool создает файл JSON для вашего устройства в каталоге инструмента. Затем вы можете передать файл в bundletool чтобы сгенерировать набор APK, предназначенных только для конфигурации, описанной в этом файле JSON, следующим образом:

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 используя следующие флаги:

Таблица 2. Параметры команды get-size total

Создайте пакет приложений с зависимостью пакета SDK (экспериментально).

Вы можете создать свой Android App Bundle с помощью зависимости Android SDK Bundle (ASB) из командной строки и подписать его с помощью jarsigner .

Каждый модуль пакета приложения включает файл буфера протокола модуля ( .pb ): runtime_enabled_sdk_config.pb . Этот файл содержит список SDK, от которых зависит модуль пакета приложения. Полное определение этого файла см. в файле runtime_enabled_sdk_config.proto .

Чтобы создать пакет приложения с зависимостью пакета SDK, выполните действия, описанные в разделе о создании пакета приложения с помощью Bundletool , и добавьте файл runtime_enabled_sdk_config.pb в ZIP-файл каждого модуля приложения со скомпилированным кодом и ресурсами.

Некоторые примечательные поля в файле runtime_enabled_sdk_config.pb :

• Дайджест сертификата: дайджест SHA-256 сертификата для ключа, используемого для подписи APK SDK. Это соответствует сертификату в файле SdkMetadata.pb в формате архива Android SDK .

• Идентификатор пакета ресурсов: идентификатор пакета, с которым переназначаются все ресурсы в этом SDK при создании APK для встраивания SDK в приложение. Это обеспечивает обратную совместимость.

SDK может присутствовать только в одном модуле. Если несколько модулей зависят от одного и того же SDK, эту зависимость следует дедуплицировать и перенести в базовый модуль. Разные модули не могут зависеть от разных версий SDK.

Создание APK-файлов из пакета приложений с зависимостью пакета SDK (экспериментально)

Чтобы создать APK-файлы из пакета приложений, выполните действия, описанные в разделе о создании набора APK-файлов из пакета приложений или в разделе о создании набора APK-файлов для конкретного устройства и предоставьте команде bundletool build-apks SDK, которые приложение зависит от. Эти SDK могут быть предоставлены в формате пакета SDK или в формате архива SDK.

Вы можете предоставить SDK в виде пакетов SDK, добавив флаг --sdk-bundles следующим образом:

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

Вы можете предоставить SDK в виде архивов SDK, добавив флаг --sdk-archives следующим образом:

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

Создание APK-файлов из пакета приложений с зависимостью пакета SDK для устройств без поддержки библиотеки SDK.

Устройства до Android 13 не поддерживают установку библиотек SDK или их запуск во время выполнения SDK. Bundletool скрывает сложность обратной совместимости и генерирует несколько вариантов вашего набора APK из одного и того же пакета приложений, когда вы запускаете bundletool build-apks с параметром --sdk-bundles или --sdk-archives . Несколько вариантов предназначены для устройств с разными возможностями:

• Существует вариант для более новых устройств, в котором SDK устанавливается как отдельный пакет от приложения, а APK-файлы приложения не содержат содержимого SDK.
• Существует один или несколько вариантов для старых устройств, в которых APK-файлы SDK добавляются в набор APK-файлов приложения в качестве дополнительных разделений APK. APK-файлы SDK принадлежат пакету приложения. В этом случае среда выполнения SDK эмулируется в среде выполнения приложения на устройстве.

Подобно тому, как вы создаете APK для пакетов приложений без зависимостей SDK, bundletool extract-apks и bundletool install-apks возвращают отфильтрованный набор APK из лучшего варианта для подключенного устройства или для предоставленной конфигурации устройства.

Для расширенных случаев использования, когда вас интересует только создание фрагментов APK из архива SDK для конкретного приложения для старых устройств, используйте команду bundletool build-sdk-apks-for-app следующим образом:

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

Файл app-properties должен содержать поля, описанные в файле runtime_enabled_sdk_config.proto . Вот как выглядит файл app-properties :

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

Команда bundletool build-sdk-apks-for-app создает подмножество APK-файлов приложения, соответствующее содержимому SDK под именем пакета приложения. Вы можете комбинировать эти APK-файлы с другими APK-файлами, содержащими контент приложения. Например, если вы собираете их отдельно и постепенно и устанавливаете вместе на устройстве, которое не поддерживает среду выполнения SDK.

Сборка и тестирование пакета SDK (экспериментальный)

Вы можете использовать bundletool для создания ASB и тестирования создания файлов, необходимых для установки и распространения.

Создайте пакет SDK

Вы можете создать свой ASB из командной строки и подписать его с помощью jarsigner .

Чтобы создать пакет SDK, выполните следующие действия:

1. Создайте манифест и ресурсы пакета SDK в формате прототипа, выполнив те же действия, что и для пакета приложения.

2. Упакуйте скомпилированный код и ресурсы вашего SDK в базовый ZIP-файл , как если бы вы использовали модуль приложения.

3. Создайте файл SdkModulesConfig.pb.json и файл SdkBundleConfig.pb.json , соответствующий формату, описанному в спецификации Android SDK Bundle .

4. Создайте свой ASB с помощью команды bundletool build-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 .

Табл. 3. Параметры команды bundletool build-sdk-bundle

Создание APK-файлов из пакета SDK

После сборки ASB вы можете протестировать пакет SDK локально, создав его APK-файлы с помощью команды bundletool build-sdk-apks , как показано в следующем коде:

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

Когда bundletool создает APK-файлы из вашего пакета SDK, инструмент включает APKS в контейнер, называемый архивом набора APK , который использует расширение файла .apks . bundletool генерирует один автономный APK из пакета SDK, предназначенный для всех конфигураций устройств.

Если вы хотите развернуть ASB на устройстве, вам также необходимо включить информацию о подписи вашего приложения, как показано в следующей команде:

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 .

Табл. 4. Параметры команды bundletool build-sdk-apks

Развертывание, извлечение и измерение размера APK-файлов SDK.

Вы можете выполнить те же действия, что и для приложений, для развертывания APK-файлов на подключенном устройстве , извлечения APK-файлов для конкретного устройства из существующего набора APK и измерения предполагаемого размера загрузки APK-файлов в наборе APK .

Создайте архив SDK из пакета SDK.

После загрузки ASB в канал распространения, например в Google Play, ASB преобразуется в архив Android SDK ( .asar ) для распространения разработчикам приложений через Maven. Подробнее о формате см. в разделе «Спецификация формата архива SDK» .

После сборки ASB вы можете протестировать создание архива Android SDK локально с помощью команды bundletool build-sdk-asar , как показано в следующем коде:

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

В следующей таблице более подробно описаны различные флаги и параметры, которые вы можете установить при использовании команды bundletool build-sdk-asar .

Табл. 5. Параметры команды bundletool build-sdk-asar

Форматы SDK с поддержкой среды выполнения (экспериментальные)

SDK с поддержкой среды выполнения представляют два формата файлов Android:

• Пакет Android SDK ( .asb ​​), используемый для публикации SDK с поддержкой среды выполнения в магазинах приложений.
• Архив Android SDK ( .asar ), используемый для распространения SDK с поддержкой среды выполнения на Maven.

Формат пакета Android SDK

Пакет SDK — это формат публикации для SDK с поддержкой среды выполнения. Он содержит весь код и ресурсы SDK, включая код всех библиотек, от которых зависит SDK. Он не включает код и ресурсы других SDK с поддержкой среды выполнения, от которых зависит этот SDK.

Пакет Android SDK (ASB) — это подписанный zip-файл с расширением .asb . Код и ресурсы SDK организованы в нем так же, как в APK. ASB также содержит несколько файлов конфигурации, которые помогают создавать устанавливаемые APK.

В следующем списке более подробно описаны некоторые файлы ASB:

• SdkBundleConfig.pb : файл конфигурации в формате прототипа, содержащий список SDK с поддержкой среды выполнения, от которых зависит ваш SDK. Полное определение см. в файле sdk_bundle_config.proto .

• modules.resm : ZIP-файл, содержащий все данные, необходимые для создания APK из SDK.

• SdkModulesConfig.pb : файл конфигурации в формате прототипа. Этот файл содержит имя SDK, версию и имя класса точки входа SDK для платформы ( SandboxedSdkProvider ). Полное определение см. в файле sdk_modules_config.proto .

• base/ : отдельный модуль, содержащий код и ресурсы SDK.

  • manifest/ : манифест SDK в формате прототипа.
  • dex/ : скомпилированный код в формате DEX. Можно предоставить несколько файлов DEX.
  • res/ , lib/ , assets/ : эти каталоги идентичны папкам в типичном APK. Пути в этих каталогах сохраняются при создании APK-файлов SDK.
  • root/ : в этом каталоге хранятся файлы, которые позже перемещаются в корень APK-файлов SDK. Например, он может включать ресурсы на основе Java, которые ваш SDK загружает с помощью метода Class.getResource() . Пути внутри этого каталога также сохраняются.

• BUNDLE-METADATA : этот каталог содержит файлы метаданных, содержащие информацию, полезную для инструментов или магазинов приложений. Такие файлы метаданных могут включать сопоставления ProGuard и полный список файлов DEX вашего SDK. Файлы в этом каталоге не входят в APK-файлы вашего SDK.

Формат архива Android SDK

Архив Android SDK — это формат распространения SDK с поддержкой среды выполнения на Maven. Это zip-файл с расширением .asar . Файл содержит всю информацию, необходимую инструментам сборки приложений для создания пакета Android App Bundle, который зависит от вашего SDK с поддержкой среды выполнения.

В следующем списке более подробно описаны некоторые файлы архива Android SDK:

• SdkMetadata.pb : файл конфигурации в формате прототипа, содержащий имя SDK, версию и дайджест сертификата для ключа, используемого для подписи APK-файлов, созданных для этого SDK. Полное определение см. в файле sdk_metadata.proto .

• modules.resm : ZIP-файл, содержащий все данные, необходимые для создания APK из SDK. Это то же самое, что и файл .resm в Android SDK Bundle .

• AndroidManifest.xml : файл манифеста SDK в текстовом формате XML.

Дополнительные ресурсы

Чтобы узнать больше об использовании bundletool , посмотрите App Bundles: тестирование пакетов с помощью Bundletool и Play Console .