bundletool

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. bundletool pode converter um pacote de app para vários APKs que serão implantados em dispositivos.

Os Android SDK Bundles (ASBs) e os APKs deles são criados com a bundletool. Ela também está disponível como uma ferramenta de linha de comando para que você possa criar pacotes de apps e SDKs e recriar o build do lado do servidor do Google Play para APKs do seu app ou do SDK ativado no momento da execução.

Fazer o download de bundletool

Faça o download do 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

Use 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 você está usando um servidor de build contínuo, por exemplo, também é possível criar seu pacote de app na linha de comando e assiná-lo usando jarsigner.

Para saber mais 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 são implantados em um dispositivo.

Há duas maneiras de testar o pacote de app:

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 inclui os APKs gerados 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 suporte 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ê quiser 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 a seguir descreve em mais detalhes as diversas flags e opções que você pode usar com o comando bundletool build-apks:

Tabela 1. Opções para o comando bundletool build-apks.

Flag 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, siga as etapas da seção sobre como implantar APKs em um dispositivo conectado.
--overwrite Substitui qualquer arquivo de saída existente pelo caminho especificado usando a opção --output. Se você não incluir essa flag e o arquivo de saída já existir, haverá um erro de build.
--aapt2=path Especifica um caminho personalizado para o AAPT2. Por padrão, o bundletool inclui a própria versão do AAPT2.
--ks=path (Opcional) Especifica o caminho para o keystore de implantação usado para assinar os APKs. Se você não incluir essa flag, a bundletool vai 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 keystore. Se você especificar uma senha em texto simples, qualifique-a com pass:. Se você transmitir o caminho para um arquivo que contém a senha, qualifique-o com file:. Se você especificar um keystore usando a flag --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 você especificar uma senha em texto simples, qualifique-a com pass:. Se você transmitir o caminho para um arquivo que contém a senha, qualifique-o com file:.

Se essa senha é idêntica à senha do keystore, você pode omitir a flag.
--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 flag para especificar o ID serial do dispositivo em que você quer implantar o app.
--device-spec=spec_json Fornece um caminho para um arquivo .json que especifica 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 Define o modo como universal. Use essa opção se quiser que bundletool crie um único APK que inclua todo o código e os recursos do seu app para que ele seja compatível com todas as configurações de dispositivos a que o 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 recurso.

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 Permite que seu pacote de app faça testes locais. Os testes locais permitem ciclos de teste rápidos e iterativos, sem a necessidade de fazer upload em servidores do Google Play.

Para ver um exemplo de como testar a instalação do módulo usando a flag --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 mais recente, 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 estiver executando o Android 4.4 (API de nível 20) ou anterior, a bundletool vai procurar um multi-APK compatível para implantar no dispositivo.

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

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

Gerar um conjunto de APKs específico para o dispositivo

Se você não quiser criar um conjunto de APKs para todas as configurações de dispositivos com suporte no app, crie APKs voltados apenas para a configuração de um dispositivo conectado usando a opção --connected-device, como mostrado no comando a seguir. Se houver vários dispositivos conectados, especifique o dispositivo incluindo a flag --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 pode 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 este comando:

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

A bundletool cria um arquivo JSON para seu dispositivo no diretório da ferramenta. Em seguida, você pode transmiti-lo à 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 que 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), crie um arquivo JSON manualmente usando este formato:

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

Em seguida, 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 uma distribuição compactada para transmissão via cabo, use o comando get-size total:

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

Modifique o comportamento do comando get-size total usando as seguintes flags:

Tabela 2. Opções para o comando get-size total.

Flag Descrição
--apks=path (Obrigatória) Especifica o caminho para o arquivo do conjunto de APKs já existente com um tamanho de download em processo de medição.
--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.

Outros recursos

Para saber mais sobre o uso de bundletool, assista a Pacotes de app: como testar pacotes com a bundletool e o Play Console.