The Android Developer Challenge is back! Submit your idea before December 2.

bundletool

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 apps: localmente usando a ferramenta de linha de comando bundletool e por meio do Google Play fazendo upload do pacote no Play Console. Esta página explica como usar o bundletool para testar seu pacote de apps localmente.

O bundletool é a ferramenta subjacente que o Gradle, o Android Studio e o Google Play usam para criar um Android App Bundle ou converter um pacote de apps em vários APKs implantados em dispositivos. O bundletool também está disponível como uma ferramenta de linha de comando, com a qual você pode recriar, inspecionar e verificar a compilação do lado do servidor dos APKs do seu app no Google Play.

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 (IDE, na sigla em inglês) se você, por exemplo, estiver usando um servidor de compilação contínua, você poderá criar seu pacote de apps a partir da linha de comando e assiná-lo usando jarsigner.

Por padrão, o IDE não usa pacotes de apps para implantar o app em um dispositivo local para testes. No entanto, você pode modificar a configuração de execução/depuração e selecionar a opção para implantar o APK do pacote de apps para ver como isso afeta a execução do app.

Fazer o download do bundletool

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

Gerar um conjunto de APKs do seu pacote de apps

Quando o bundletool gera APKs do pacote de apps, ele 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 compatíveis com seu pacote de apps, use o comando bundletool build-apks, conforme 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, conforme mostrado no comando abaixo. Se você não especificar informações de assinatura, o bundletool 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 as diversas sinalizações e opções que você pode configurar ao usar o comando bundletool build-apks em mais detalhes. Somente --bundle e --output são obrigatórios. Todas as outras sinalizações são opcionais.

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 Compilar seu projeto.
--output=path (Obrigatória) Especifica o nome do arquivo `.apks` de saída, que contém todos os artefatos de APK para seu app. Para testar os artefatos desse arquivo em um dispositivo, vá para a seção sobre como implantar APKs em um dispositivo conectado.
--overwrite Inclua esta sinalização se quiser substituir qualquer arquivo de saída existente pelo 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 você especificar uma senha em texto simples, qualifique-a com pass:. Se você passar o caminho para um arquivo que contenha a senha, qualifique-o 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 você especificar uma senha em texto simples, qualifique-a com pass:. Se você passar o caminho para um arquivo que contenha a senha, qualifique-o com o file:.

Se essa senha for idêntica à senha do keystore, você poderá 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, o bundletool gerará APKs para todas as configurações de dispositivos compatíveis com seu app.
--device-id=serial-number Se você tiver mais de um dispositivo conectado, use esta 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 especifica a configuração do dispositivo de destino. Para saber mais, acesse a seção sobre como Criar e usar arquivos JSON de especificação do dispositivo.
--mode=universal Configure o modo como universal se quiser que o bundletool crie apenas um APK que inclua todo o código e os recursos do seu app, de modo que o APK seja compatível com todas as configurações de dispositivos compatíveis com o app.

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

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

Implantar APKs em um dispositivo conectado

Depois de gerar um conjunto de APKs, o 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 (API de nível 21) ou posterior, o bundletool enviará o APK de base, os APKs de recursos dinâmicos e os APKs de configuração necessários para executar o app nesse dispositivo. Como alternativa, se o dispositivo conectado estiver executando o Android 4.4 (API de nível 20) ou anterior, o bundletool procurará um multi-APK compatível e o implantará no dispositivo.

Para implantar o app a partir de um conjunto de APKs, use o comando install-apks e especifique o caminho do conjunto de APKs usando --apks=/path/to/apks, conforme mostrado abaixo. Se você tiver vários dispositivos conectados, especifique um 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 compatíveis com seu app, crie APKs voltados somente para a configuração de um dispositivo conectado usando a opção --connected-device, conforme mostrado abaixo. Se você tiver vários dispositivos conectados, especifique um dispositivo de destino 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

O bundletool é capaz de gerar um conjunto de APKs voltado ao 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
    

O bundletool cria um arquivo JSON para seu dispositivo no diretório em que a ferramenta está localizada. Você pode passá-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 tiver acesso ao dispositivo para o qual quer criar um conjunto de APKs (por exemplo, um amigo quer testar seu app com um dispositivo que você não tem disponível), poderá criar manualmente um arquivo JSON usando o seguinte formato:

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

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

Extrair APKs específicos do dispositivo a partir de um conjunto de APKs existente

Se você tiver um conjunto de APKs existente e quiser extrair dele um subconjunto de APKs voltados a uma configuração de dispositivo específica, poderá usar o comando extract-apks e definir um JSON de especificação de dispositivo, da seguinte maneira:

    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, 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
    

Você pode 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 existente cujo tamanho de download é medido.
--device-spec=path Especifica o caminho para o arquivo de especificação do dispositivo (de get-device-spec ou construído manualmente) para usar para 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 todas as dimensões, especifique ALL.
--instant Mede o tamanho de download dos APKs ativados para instantâneos, em vez dos APKs instaláveis. Por padrão, o 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 do bundletool, teste o recurso a seguir.

Codelabs

  • Your First Android App Bundle, um codelab que explora os princípios básicos dos Android App Bundles e mostra como começar rapidamente a compilação do seu usando o Android Studio. Esse codelab também explora como testar seus pacotes de apps usando o bundletool.