bundletool

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

A bundletool é a ferramenta que o Android Studio, o Plug-in do Android para Gradle e o Google Play usam para criar um Android App Bundle e converter um pacote de app em vários APKs implantados em dispositivos. Os Android SDK Bundles e os APKs deles também são criados com a bundletool. A bundletool também está disponível como uma ferramenta de linha de comando. Assim, é possível criar pacotes de apps e SDKs por conta própria e recriar o build do lado do servidor do Google Play para APKs do seu app ou do SDK ativado pelo ambiente de execução.

Fazer o download da bundletool

Faça o download da bundletool no repositório do GitHub, caso ainda não tenha feito.

Criar e testar um pacote de app

Você pode usar o Android Studio ou a ferramenta de linha de comando bundletool para criar seu Android App Bundle e testar os APKs gerados por esse pacote de app.

Criar um pacote de app

Você precisa usar o Android Studio e o plug-in do Android para Gradle para criar e assinar um Android App Bundle. No entanto, se não for possível usar o ambiente de desenvolvimento integrado, porque, por exemplo, você está usando um servidor de compilação contínua, você vai poder criar seu pacote de app pela linha de comando e assiná-lo usando jarsigner.

Para ver mais informações sobre a criação de pacotes de app com a bundletool, consulte Criar um pacote de app usando a bundletool.

Gerar um conjunto de APKs no seu pacote de app

Depois de criar o Android App Bundle, é importante testar como ele é usado pelo Google Play para gerar APKs e como esses APKs se comportam quando implantados em um dispositivo. Há duas maneiras de testar o pacote de app: localmente, usando a ferramenta de linha de comando bundletool, e pelo Google Play, com o upload do pacote para o Play Console e usando uma faixa de teste. Esta seção explica como usar a bundletool para testar seu pacote de app localmente.

Quando a bundletool gera APKs no pacote de app, ela os inclui em um contêiner chamado arquivo de conjunto de APKs, que usa a extensão de arquivo .apks. Para gerar um conjunto de APKs para todas as configurações de dispositivo com que seu app é compatível usando seu pacote de app, aplique o comando bundletool build-apks, como mostrado abaixo.

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

Se você quer implantar os APKs em um dispositivo, inclua também as informações de assinatura do app, como mostrado no comando a seguir. Se você não especificar informações de assinatura, a bundletool vai tentar assinar seus APKs com uma chave de depuração.

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

A tabela abaixo descreve em mais detalhes as diversas sinalizações e opções que você pode configurar ao usar o comando bundletool build-apks.

Sinalização Descrição
--bundle=path (Obrigatória) Especifica o caminho para o pacote de apps criado usando o Android Studio. Para saber mais, leia Criar seu projeto.
--output=path (Obrigatória) Especifica o nome do arquivo ".apks" de saída, que contém todos os artefatos do APK para seu app. Para testar os artefatos desse arquivo em um dispositivo, acesse a seção sobre como implantar APKs em um dispositivo conectado.
--overwrite Inclua essa sinalização caso queira substituir algum arquivo de saída já existente com o mesmo caminho especificado usando a opção --output. Se você não incluir essa sinalização, e o arquivo de saída já existir, haverá um erro de compilação.
--aapt2=path Especifica um caminho personalizado para o AAPT2. Por padrão, o bundletool inclui a própria versão do AAPT2.
--ks=path Especifica o caminho para o keystore de implantação usado para assinar os APKs. Essa sinalização é opcional. Se você não incluí-la, o bundletool tentará assinar seus APKs com uma chave de assinatura de depuração.
--ks-pass=pass:password
ou
--ks-pass=file:/path/to/file
Especifica a senha do seu keystore. Se quiser especificar uma senha em texto simples, qualifique-a com pass:. Se você for transmitir o caminho a um arquivo que contém a senha, qualifique-a com file:. Se você especificar um keystore usando a sinalização --ks sem especificar --ks-pass, o bundletool solicitará uma senha na linha de comando.
--ks-key-alias=alias Especifica o alias da chave de assinatura que você quer usar.
--key-pass=pass:password
ou
--key-pass=file:/path/to/file
Especifica a senha da chave de assinatura. Se quiser especificar uma senha em texto simples, qualifique-a com pass:. Se você for transmitir o caminho a um arquivo que contém a senha, qualifique-a com file:.

Se essa senha é idêntica à senha do keystore, você pode omitir essa sinalização.

--connected-device Instrui o bundletool a criar APKs voltados à configuração de um dispositivo conectado. Se você não incluir essa sinalização, a bundletool vai gerar APKs para todas as configurações de dispositivos com suporte para seu app.
--device-id=serial-number Se você tiver mais de um dispositivo conectado, use essa sinalização para especificar o código serial do dispositivo em que você quer implantar o app.
--device-spec=spec_json Use esta sinalização para fornecer um caminho para um arquivo .json que especifique a configuração do dispositivo de destino. Para saber mais, acesse a seção sobre como Gerar e usar arquivos JSON de especificação de dispositivo.
--mode=universal Defina o modo como universal se quiser que a bundletool crie um único APK que inclua todo o código e os recursos do seu app. Assim, o APK vai ser compatível com todas as configurações de dispositivos a que seu app oferece suporte.

Observação: a bundletool inclui apenas módulos de recursos que especificam <dist:fusing dist:include="true"/> no manifesto em um APK universal. Para saber mais, leia sobre o manifesto do módulo de recursos.

Lembre-se de que esses APKs são maiores que os otimizados para uma configuração de dispositivo específica. No entanto, eles são mais fáceis de compartilhar com testadores internos que, por exemplo, querem testar seu app em diversas configurações de dispositivos.

--local-testing Use essa sinalização para ativar o pacote de app para testes locais. Os testes locais permitem ciclos de teste rápidos e iterativos, sem a necessidade de fazer o upload para servidores do Google Play.

Para ver um exemplo de como testar a instalação do módulo usando a sinalização --local-testing, consulte Instalações do módulo de teste local.

Implantar APKs em um dispositivo conectado

Depois de gerar um conjunto de APKs, a bundletool pode implantar a combinação certa de APKs desse conjunto em um dispositivo conectado.

Por exemplo, se você tiver um dispositivo conectado com o Android 5.0 (nível 21 da API) ou versões mais recentes, a bundletool transmite o APK base, os APKs do módulo de recursos e os APKs de configuração necessários para executar seu app nesse dispositivo. Como alternativa, se o dispositivo conectado usar o Android 4.4 (nível 20 da API) ou versões anteriores, o bundletool vai procurar um multi-APK compatível e o implantará no dispositivo.

Para implantar o app com base em um conjunto de APKs, use o comando install-apks e especifique o caminho do conjunto de APKs usando a sinalização --apks=/path/to/apks, conforme mostrado abaixo. Se houver vários dispositivos conectados, especifique o dispositivo de destino adicionando a sinalização --device-id=serial-id.

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

Gerar um conjunto de APKs específico para o dispositivo

Se preferir não criar um conjunto de APKs para todas as configurações de dispositivos com suporte para seu app, crie APKs voltados apenas para a configuração de um dispositivo conectado usando a opção --connected-device, como mostrado abaixo. Se houver vários dispositivos conectados, especifique o dispositivo incluindo a sinalização --device-id=serial-id.

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

Gerar e usar arquivos JSON de especificação de dispositivo

A bundletool é capaz de gerar um conjunto de APKs voltado a uma configuração de dispositivo especificada por um arquivo JSON. Para gerar primeiro um arquivo JSON para um dispositivo conectado, execute o seguinte comando:

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

A bundletool cria um arquivo JSON para seu dispositivo no diretório em que a ferramenta está localizada. Você pode transmiti-lo ao bundletool para gerar um conjunto de APKs voltados apenas à configuração descrita nesse arquivo JSON da seguinte forma:

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

Criar manualmente um JSON de especificação de dispositivo

Se você não tem acesso ao dispositivo para o qual quer criar um conjunto de APKs direcionado (por exemplo, um amigo quer testar seu app com um dispositivo que você não tem disponível), vai poder criar manualmente um arquivo JSON usando o seguinte formato:

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

Você pode transmitir esse JSON ao comando bundle extract-apks, conforme descrito na seção anterior.

Extrair APKs específicos do dispositivo de um conjunto de APKs já existente

Se você já tiver um conjunto de APKs e quiser extrair dele um subconjunto de APKs que segmentam uma configuração do dispositivo específico, use o comando extract-apks e defina um JSON de especificação de dispositivo, conforme mostrado a seguir.

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

Medir os tamanhos estimados de download de APKs em um conjunto

Para medir os tamanhos estimados de download de APKs em um conjunto, considerando que eles seriam disponibilizados compactados para transmissão via cabo, use o comando get-size total:

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

É possível modificar o comportamento do comando get-size total usando as seguintes sinalizações:

Sinalização Descrição
--apks=path (Obrigatória) Especifica o caminho para o arquivo do conjunto de APKs já existente cujo tamanho de download é medido.
--device-spec=path Especifica o caminho para o arquivo de especificação do dispositivo (com base em get-device-spec ou construído manualmente) para uso em correspondência. Você pode especificar um caminho parcial para avaliar um conjunto de configurações.
--dimensions=dimensions Especifica as dimensões usadas ao calcular as estimativas de tamanho. Aceita uma lista separada por vírgulas de SDK, ABI, SCREEN_DENSITY e LANGUAGE. Para medir em todas as dimensões, especifique ALL.
--instant Mede o tamanho de download dos APKs instantâneos, em vez dos APKs instaláveis. Por padrão, a bundletool mede os tamanhos de download de APKs instaláveis.
--modules=modules Especifica uma lista de módulos separados por vírgulas no conjunto de APKs a ser considerado na medição. O comando bundletool inclui automaticamente todos os módulos dependentes para o conjunto especificado. Por padrão, o comando mede o tamanho do download de todos os módulos instalados durante o primeiro download.

Criar e testar um pacote de app com uma dependência do pacote de SDKs (experimental)

Você pode usar a bundletool para criar um Android App Bundle com uma dependência do Android SDK Bundle e testar a geração de APKs dele.

Criar um pacote de app com uma dependência do pacote de SDKs

Você pode criar seu Android App Bundle com uma dependência do Android SDK Bundle na linha de comando e assiná-lo usando o jarsigner.

Cada módulo de pacote de app inclui um arquivo de buffer de protocolo do módulo (.pb): runtime_enabled_sdk_config.pb. Esse arquivo contém a lista de SDKs de que um módulo de pacote de app depende. Para ver a definição completa, consulte o arquivo runtime_enabled_sdk_config.proto.

Para criar um pacote de app com uma dependência do pacote de SDKs, você pode seguir o mesmo guia para criar um pacote de app usando a bundletool. No entanto, desta vez adicione um arquivo runtime_enabled_sdk_config.pb ao arquivo ZIP de cada módulo do app com código e recursos compilados.

Alguns campos importantes no arquivo runtime_enabled_sdk_config.pb:

  • Síntese do certificado: uma síntese do certificado SHA-256 da chave usada para assinar os APKs do SDK. Corresponde ao certificado no arquivo SdkMetadata.pb no formato Android SDK Archive.

  • ID do pacote de recursos: o ID do pacote em que todos os recursos neste SDK são remapeados ao gerar APKs para incorporar o SDK no app. Isso possibilita a compatibilidade com versões anteriores.

Um SDK pode aparecer apenas em um módulo. Se vários módulos dependerem do mesmo SDK, a duplicação vai precisar ser eliminada e movida para o módulo base. Diferentes módulos não podem depender de diferentes versões do SDK.

Gerar APKs de um pacote de app com uma dependência do pacote de SDKs

Para gerar APKs do pacote de app, siga as mesmas etapas descritas em Gerar um conjunto de APKs no seu pacote de app ou Gerar um conjunto de APKs específico para o dispositivo, mas desta vez forneça o comando bundletool build-apks com os SDKs de que o app depende. Esses SDKs podem ser fornecidos no formato de pacote do SDK ou do SDK Archive.

Você pode fornecer os SDKs como pacotes ao adicionar a sinalização --sdk-bundles da seguinte maneira:

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

É possível fornecer os SDKs como arquivos SDK ao adicionar a sinalização --sdk-archives da seguinte maneira:

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

Criar e testar um pacote de SDKs (experimental)

Você pode usar a bundletool para criar um Android SDK Bundle e testar a geração dos arquivos necessários para instalação e distribuição.

Criar um pacote de SDKs

É possível criar seu Android SDK Bundle (ASB) na linha de comando e assiná-lo usando o jarsigner.

Para criar um pacote de SDKs, siga estas etapas:

  1. Gere o manifesto e os recursos do pacote do SDK no formato proto seguindo as mesmas etapas de um pacote de app.

  2. Empacote o código compilado e os recursos do seu SDK em um arquivo ZIP de base, como faria com um módulo do app.

  3. Gere um arquivo SdkModulesConfig.pb.json e um SdkBundleConfig.pb.json correspondentes ao formato descrito nas especificações do Android SDK Bundle.

  4. Crie seu pacote do SDK usando o comando bundletool build-sdk-bundle da seguinte maneira:

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

A tabela abaixo descreve em mais detalhes as diversas sinalizações e opções que você pode configurar ao usar o comando bundletool build-sdk-bundle.

Sinalização Descrição
--modules (Obrigatória) O arquivo do módulo que você quer usar para criar o Android SDK Bundle final.
--output (Obrigatório) Caminho em que o Android SDK Bundle vai ser criado.
--sdk-modules-config (Obrigatório) Caminho para um arquivo JSON que descreve a configuração dos módulos do SDK. Para saber como formatar o arquivo JSON, consulte as especificações do Android SDK Bundle
--sdk-bundle-config Caminho para um arquivo JSON que descreve a configuração do pacote de SDKs. Para saber como formatar o arquivo JSON, consulte as especificações do Android SDK Bundle
--metadata-file Especifica o arquivo a ser incluído como metadados no Android SDK Bundle. O formato do valor da sinalização é <bundle-path>:<physical-file>, em que <bundle-path> indica o local do arquivo dentro do diretório de metadados do pacote de SDKs, e <physical-file> é um arquivo já existente que contém os dados brutos a serem armazenados. A sinalização pode ser repetida.
--overwrite Se definido, qualquer saída anterior vai ser substituída.

Gerar APKs de um pacote de SDKs

Depois de criar seu Android SDK Bundle, você pode testar um pacote de SDK localmente gerando os APKs com o comando bundletool build-sdk-apks, conforme mostrado no código a seguir.

Quando a bundletool gera APKs no pacote de SDKs, ela os inclui em um contêiner chamado arquivo de conjunto de APKs, que usa a extensão de arquivo .apks. A bundletool gera um único APK autônomo do pacote de SDK que é destinado a todas as configurações do dispositivo.

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

Se você quiser implantar o ASB em um dispositivo, também vai precisar incluir as informações de assinatura do app, como mostrado no comando a seguir. Se você não especificar informações de assinatura, a bundletool vai tentar assinar seus APKs com uma chave de depuração.

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

A tabela abaixo descreve em mais detalhes as diversas sinalizações e opções que você pode configurar ao usar o comando bundletool build-sdk-apks.

Sinalização Descrição
--sdk-bundle (Obrigatória) Caminho para o pacote do SDK. É preciso ter a extensão .asb.
--output (Obrigatória) Por padrão, o caminho em que o arquivo de conjunto de APKs precisa ser criado. Como alternativa, se você usar --output-format=DIRECTORY, esse vai ser o caminho para o diretório em que os APKs gerados vão ser armazenados.
--ks Caminho para o keystore que precisa ser usado para assinar os APKs gerados.
--ks-key-alias Alias da chave a ser usada no keystore para assinar os APKs gerados.
--key-pass Senha da chave no keystore a ser usada para assinar os APKs gerados. Se você for transmitir a senha em texto não criptografado, vai precisar prefixar o valor com pass:, por exemplo, pass:qwerty. Se a senha for a primeira linha de um arquivo, você vai precisar prefixar o valor com file:, por exemplo, file:/tmp/myPassword.txt. Se essa sinalização não estiver definida, a senha do keystore vai ser testada. Se ela não for aceita, o terminal da linha de comando vai pedir outra senha.
--ks-pass Senha do keystore a ser usado para assinar os APKs gerados. Se você for transmitir a senha em texto não criptografado, vai precisar prefixar o valor com pass:, por exemplo, pass:qwerty. Se a senha for a primeira linha de um arquivo, você vai precisar prefixar o valor com file:, por exemplo, file:/tmp/myPassword.txt. Se essa sinalização não estiver definida, o terminal de linha de comando vai pedir uma senha.
--aapt2 Caminho para o binário AAPT2 a ser usado.
--output-format Especifica o formato de saída dos APKs gerados. Por padrão, se ele for definido como APK_SET, vai gerar APKs no arquivo do conjunto de APKs criado. Se definido como DIRECTORY, ele vai enviar os APKs para o diretório especificado por --output.
--verbose Se definido, ele mostra informações extras sobre a execução do comando na saída padrão.
--version-code Código da versão do SDK. Esse é o código da versão usado pela Plataforma Android para instalar o APK, não a versão do SDK. Ele pode ser definido como um valor arbitrário. Se não for definido, o padrão vai ser 0.
--overwrite Se definido, qualquer saída anterior vai ser substituída.

Gerar um SDK Archive com base em um pacote de SDKs

Depois de fazer upload do Android SDK Bundle para um canal de distribuição, como o Google Play, o Android SDK Bundle é transformado em um Android SDK Archive (.asar) para realizar a distribuição aos desenvolvedores de apps pelo Maven. Para ver mais detalhes sobre o formato, consulte as especificações de formato SDK Archive.

Depois de criar seu pacote do Android SDK Bundle, você pode testar a geração de um Android SDK Archive localmente usando o comando bundletool build-sdk-asar, como mostrado no código a seguir.

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

A tabela abaixo descreve em mais detalhes as diversas sinalizações e opções que você pode configurar ao usar o comando bundletool build-sdk-asar.

Sinalização Descrição
--apk-signing-key-certificate (Obrigatória) Caminho para o certificado de assinatura do APK do SDK. Esse é o certificado correspondente à chave que você usou para assinar os APKs no comando build-sdk-apks.
--output (Obrigatória) Caminho em que o arquivo .asar vai ser criado.
--sdk-bundle (Obrigatória) Caminho para o pacote do SDK. É preciso ter a extensão .asb.
--overwrite Se definido, qualquer saída anterior vai ser substituída.

Formatos de SDKs ativados pelo ambiente de execução (experimental)

Os SDKs ativados pelo ambiente de execução introduzem dois formatos de arquivo do Android. O Android SDK Bundle (.asb), que é usado para publicar o SDK nas app stores, e o Android SDK Archive (.asar), que é usado para distribuir o SDK no Maven.

O formato Android SDK Bundle

Um pacote de SDKs é um formato de publicação para SDKs ativados pelo ambiente de execução. Ele contém todo o código e os recursos do SDK, incluindo o código de qualquer biblioteca de que o SDK depende. Ele não inclui o código e os recursos de outros SDKs ativados pelo ambiente de execução que são obrigatórios para o seu SDK.

Um Android SDK Bundle é um arquivo ZIP assinado que contém a extensão .asb. O código e os recursos do SDK são organizados de forma parecida com o que você encontraria em um APK. Um ASB também contém vários arquivos de configuração usados para ajudar na geração dos APKs instaláveis.

Figura 1. O conteúdo de um Android SDK Bundle.

A lista a seguir descreve em mais detalhes alguns dos arquivos do Android SDK Bundle:

  • SdkBundleConfig.pb: um arquivo de configuração no formato proto, contendo a lista de SDKs ativados pelo ambiente de execução que são obrigatórios para o seu SDK. Para ver a definição completa, consulte o arquivo sdk_bundle_config.proto.

  • modules.resm: um arquivo ZIP que contém todos os dados necessários para gerar os APKs do SDK.

  • SdkModulesConfig.pb: um arquivo de configuração no formato proto. Esse arquivo contém o nome, a versão e o nome da classe do ponto de entrada do SDK do framework (SandboxedSdkProvider). Para ver a definição completa, consulte o arquivo sdk_modules_config.proto.

  • base/: o único módulo que contém o código e os recursos do SDK.

    • manifest/: o manifesto do SDK no formato proto.
    • dex/: o código compilado no formato DEX. Vários arquivos DEX podem ser fornecidos.
    • res/, lib/ e assets/: esses diretórios são idênticos aos de um APK comum. Os caminhos nesses diretórios são preservados ao gerar os APKs do SDK.
    • root/: esse diretório armazena arquivos que são mais tarde realocados para a raiz dos APKs do SDK. Por exemplo, ele pode incluir recursos baseados em Java que o SDK carrega usando o método Class.getResource(). Os caminhos dentro desse diretório também são preservados.
    • BUNDLE-METADATA: esse diretório inclui arquivos de metadados que contêm informações úteis para ferramentas ou app stores. Esses arquivos de metadados podem incluir mapeamentos do ProGuard e a lista completa de arquivos DEX do SDK. Os arquivos neste diretório não são empacotados nos APKs do SDK.

O formato Android SDK Archive

O Android SDK Archive é o formato de distribuição de um SDK ativado pelo ambiente de execução no Maven. Ele é um arquivo ZIP que contém a extensão de arquivo .asar. Esse arquivo contém todas as informações necessárias para que as ferramentas de criação de apps gerem um Android App Bundle que dependa do SDK ativado pelo ambiente de execução.

Figura 2. O conteúdo de um Android SDK Archive Bundle.

A lista a seguir descreve em mais detalhes alguns dos arquivos do Android SDK Bundle:

  • SdkMetadata.pb: um arquivo de configuração no formato proto, contendo o nome e a versão do SDK, além do resumo do certificado da chave usada para assinar os APKs gerados para esse SDK. Para ver a definição completa, consulte o arquivo sdk_metadata.proto.

  • modules.resm: um arquivo ZIP que contém todos os dados necessários para gerar os APKs do SDK. Ele é o mesmo que o arquivo .resm no Android SDK Bundle.

  • AndroidManifest.xml: o arquivo de manifesto do SDK no formato de texto XML.

Outros recursos

Para saber mais sobre o uso da bundletool, teste o recurso a seguir.

Codelabs

  • Seu primeiro Android App Bundle, um codelab que explica os princípios básicos dos Android App Bundles e mostra como começar a criar o seu rapidamente usando o Android Studio. Esse codelab também mostra como testar seus pacotes de app usando a bundletool.