(Descontinuado) Criar versões diferentes do app usando variantes de build

1. Introdução

Última atualização: 14/04/2022

As variantes de build são úteis para criar diferentes versões do app. Por exemplo, você talvez queira criar uma versão gratuita do app, com um conjunto limitado de conteúdo, e outra versão paga com mais conteúdo. Você também pode compilar versões do app que sejam direcionadas a diferentes dispositivos, com base no nível da API ou em outras variações de dispositivos.

Neste codelab, você vai modificar o app Dice Roller que criou na Unidade 1: noções básicas de Kotlin para ter duas versões: "demo" e "full". A versão "full" tem uma caixa de texto adicional que exibe o resultado da rolagem do dado, ou seja, o usuário não precisa depender somente da imagem do dado para saber o resultado da jogada.

O que você já precisa saber

Você precisa ter o seguinte:

  • Concluído os programas de aprendizagem 1 a 4 de noções básicas do Android. Para fazer os codelabs de pré-requisito, consulte os programas de aprendizagem Unidade 1: noções básicas de Kotlin.
  • Conhecimento geral do sistema de compilação do Android. Para se familiarizar com os componentes principais, consulte a visão geral de build.

O que você vai aprender

  • O que são variantes de build.
  • O que são conjuntos de origem.
  • Como criar versões diferentes do app usando variantes de build e conjuntos de origem.
  • Como fornecer IDs de aplicativo exclusivos às variantes do app.

O que você vai criar

Neste codelab, você vai começar com o app DiceRoller que foi criado nos programas de aprendizagem da Unidade 1: noções básicas de Kotlin. O app DiceRoller tem a imagem de um dado e o botão ROLL (jogar) abaixo dela. Quando o usuário clica em ROLL, o dado é jogado e a imagem muda de acordo com o resultado.

Você vai criar outros arquivos do projeto e adicionar código para:

  • Criar variações de produto "demo" e "full" do app.
  • Criar conjuntos de origem "demo" e "full" correspondentes às variações de produto.
  • Adicionar uma caixa ao layout da versão "full" do app.
  • Programar a caixa da versão "full" para exibir o resultado da jogada quando o usuário clicar em ROLL.
  • Personalizar os títulos do app para as versões "demo" e "full".
  • Fornecer IDs de aplicativo exclusivos para as versões "demo" e "full" do app.

Veja como vai ficar a versão completa do app:

App DiceRoller com caixa dinâmica.

O que é necessário

2. Configurar o ambiente

Buscar o código

Se você não tiver o app DiceRoller completo da Unidade 1: noções básicas de Kotlin, faça o download do código do app no GitHub (link em inglês).

Para fazer o download do código do app e abrir no Android Studio, siga estas etapas:

  1. Na página inicial do repositório do GitHub android-basics-kotlin-dice-roller-with-images-app-solution, clique em Code > Download ZIP.
  2. Depois de fazer o download do arquivo ZIP, abra o projeto no Android Studio e clique em File > Open. Você pode iniciar uma atividade vazia ou abrir um projeto anterior, se solicitado. Isso não importa, já que abriremos o projeto baixado.
  3. Navegue até o local onde o arquivo ZIP foi transferido por download (provavelmente na pasta Downloads), selecione-o e clique em Open.

Usar a visualização Project

Ao trabalhar com variantes de build, você precisa trabalhar com os arquivos do projeto na visualização Project para ver todos os diretórios das diferentes variantes. Para fazer isso, abra o painel Project no Android Studio, clique no menu de tipo de visualização (definido como Android por padrão) e selecione a visualização Project.

3. Entender as variantes de build

Variantes de build são o resultado de diferentes combinações de variações de produto e tipos de build. Pense nas variações de produto como atributos mais voltados ao usuário e nos tipos de build como atributos mais voltados para o desenvolvedor. Você não precisa configurar as variantes de build diretamente. Em vez disso, configure um conjunto de variações de produto e um conjunto de tipos de build, que determinam as variantes de build.

Especificamente, as variantes de build representam cada combinação de variação de produto e tipo de build e recebem nomes como <product-flavor><build-type>. Por exemplo, se você tivesse os tipos de build debug e release e as variações de produto demo e full, as variantes de build resultantes seriam:

  • demoDebug
  • demoRelease
  • fullDebug
  • fullRelease

Vamos configurar variações de produto e tipos de build para o app DiceRoller.

4. Configurar variações de produtos

Variações de produto são os atributos mais voltados ao usuário do app, porque geralmente representam as versões disponíveis para ele. Para criar as versões "demo" e "full" do nosso app, é necessário adicionar as duas variações do produto e as atribuir a uma dimensão de variações. Para adicionar as variações de produto, abra o arquivo build.gradle no nível do app (app > build.gradle na visualização Project) e cole o código abaixo no bloco android {}.

flavorDimensions "app_type"  
productFlavors {
   demo {
       dimension "app_type"
         }
   full {
       dimension "app_type"
   }
}

Esse código faz o seguinte:

  • Cria uma dimensão de variações com o nome app_type.
  • Cria duas variações de produto, representadas pelos blocos demo {} e full {}.
  • Atribui as duas variações de produto à dimensão app_type. Isso é opcional se houver apenas uma dimensão de variações.

Esse é o código básico necessário para definir variações de produto. Você vai usar outras opções mais adiante neste codelab.

5. Configurar tipos de build

Os tipos de build são atributos mais voltados ao desenvolvedor do app, porque geralmente representam estágios de desenvolvimento (por exemplo, depuração, Beta e lançamento). O Android Studio configura automaticamente dois tipos de build: debug e release. O tipo de build debug serve para fins de depuração, enquanto o tipo de build release serve para distribuição.

Você pode criar tipos de build e modificar as configurações editando o bloco buildTypes {} no arquivo build.gradle no nível do app. O bloco buildTypes {} padrão tem esta aparência:

buildTypes {
   release {
       minifyEnabled false
       proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
   }
}

Você pode ver a configuração padrão do tipo de build release. Não falaremos sobre as propriedades minifyEnabled ou proguardFiles neste codelab. O tipo de build debug não aparece no arquivo de configuração do build por padrão, mas você pode adicionar um bloco debug {} para adicionar ou mudar determinadas configurações. A configuração padrão funciona para nossos objetivos. Ela pode ficar como está.

6. Usar a janela de ferramentas "Build Variants"

Agora que você tem duas variações de produto e dois tipos de build, vamos ver as variantes de build que eles criam. Para ver as novas variantes de build no Android Studio:

  1. Na barra de ferramentas, clique em Sync Project with Gradle Files 4e7fbf18152549d8.png. Sempre que você fizer mudanças em arquivos de configuração do build, o Studio vai solicitar a sincronização dos arquivos para salvar a nova configuração do build e verificar se há erros.
  2. Clique em Build > Select Build Variant (ou View > Tool Windows > Build Variants) para exibir a janela Build Variants.
  3. Clique em demoDebug na coluna Active Build Variant para abrir um menu que contém todas as variantes de build: demoDebug, demoRelease, fullDebug e fullRelease. Use esse menu para selecionar diferentes variantes de build que vão ser executadas e testadas.

Janela de ferramentas &quot;Build Variants&quot; mostrando o menu &quot;Active Build Variant&quot;.

Execute as variantes demoDebug e fullDebug. As variantes baseadas no tipo de build release exigem mais configuração para serem executadas. Portanto, não vamos trabalhar com elas neste codelab. Até o momento, as variantes demoDebug e fullDebug são iguais pela perspectiva do usuário.

7. Criar recursos diferentes para variantes diferentes

Agora que você já tem as versões demo e full do app, vamos adicionar alguns recursos à versão full.

Adicionar um recurso premium usando conjuntos de origem

Para a variação de produto full, vamos adicionar uma caixa que mostra o resultado da jogada para que os usuários não precisem depender apenas da imagem do dado para saber o resultado. Para adicionar esse recurso premium, use os conjuntos de origem. Um conjunto de origem é um diretório que inclui conteúdo para tipos de build, variações de produto e variantes de build específicos. O conjunto de origem main padrão (app > src > main) tem conteúdo para compartilhar entre todas as variantes de build. Esse conteúdo padrão pode ser substituído por outros em conjuntos de origem diferentes.

A forma como você substitui o que está no conjunto de origem main e determina quais conjuntos de origem precisam ser adicionados varia de acordo com o que vai mudar.

Para mudar um recurso, como um layout ou uma imagem (algo em main > res), siga estas etapas gerais:

  1. Crie um conjunto de origem ou diretório para a variação de produto que você quer mudar. Vamos falar sobre onde e como criar esse conjunto de origem na próxima seção.
  2. Cole o arquivo de recursos que você quer alterar nesse novo conjunto de origem e atualize-o. Quando o Plug-in do Android para Gradle (AGP, na sigla em inglês) cria uma variante de build que depende do novo conjunto de origem, ele substitui o código do recurso em main pelo código do novo conjunto de origem.

Para substituir um comportamento em uma classe Java ou Kotlin (algo em main > java), siga estas etapas gerais:

  1. Crie conjuntos de origem ou diretórios para a variação de produto que você quer mudar e todas as outras variações de produto na mesma dimensão de variações.
  2. Cole o arquivo que você quer mudar em todos os conjuntos de origem de variações de produto e modifique as cópias que vão mudar.
  3. Exclua o arquivo original do conjunto de origem main.

Para adicionar uma caixa dinâmica à versão "full" do app, considere o recurso premium como duas mudanças principais:

  • Personalize o layout: adicione uma caixa modificando o arquivo activity_main.xml.
  • Personalize o comportamento do app: mude o que é exibido na caixa com base na jogada do dado modificando o arquivo MainActivity.kt.

Na próxima seção, você vai aprender onde e como criar conjuntos de origem.

Determinar onde criar novos conjuntos de origem

O Plug-in do Android para Gradle (AGP) mostra como organizar os arquivos para cada tipo de build, variação de produto e variante de build. Para adicionar um recurso premium à variação de produto full que inclui uma mudança no arquivo MainActivity.kt, crie conjuntos de origem para as variações full e demo. Para descobrir onde criar esses conjuntos de origem, siga estas etapas no Android Studio:

  1. Clique em Gradle na janela do ambiente de desenvolvimento integrado.
  2. Vá até MyApplication > Tasks > android e clique duas vezes em sourceSets. Se a pasta Tasks não aparecer, deixe o Gradle criar a lista de tarefas durante a sincronização clicando em File > Settings > Experimental e desmarque Do not build Gradle task list during Gradle sync (Android Studio > Preferences > Experimental no macOS). Depois que o Gradle executar a tarefa, a janela Run vai mostrar a saída.
  3. Se a exibição não estiver no modo de texto conforme mostrado abaixo, clique em Toggle view 82487fd4e011f105.png na janela Run.

Na janela Run, você vai ver esta saída:

------------------------------------------------------------
Project ':app'
------------------------------------------------------------

...

debug
-----
Compile configuration: debugCompile
build.gradle name: android.sourceSets.debug
Java sources: [app/src/debug/java]
Kotlin sources: [app/src/debug/kotlin, app/src/debug/java]
Manifest file: app/src/debug/AndroidManifest.xml
Android resources: [app/src/debug/res]
Assets: [app/src/debug/assets]
AIDL sources: [app/src/debug/aidl]
RenderScript sources: [app/src/debug/rs]
JNI sources: [app/src/debug/jni]
JNI libraries: [app/src/debug/jniLibs]
Java-style resources: [app/src/debug/resources]

...

full
----
Compile configuration: fullCompile
build.gradle name: android.sourceSets.full
Java sources: [app/src/full/java]
Kotlin sources: [app/src/full/kotlin, app/src/full/java]
Manifest file: app/src/full/AndroidManifest.xml
Android resources: [app/src/full/res]
Assets: [app/src/full/assets]
AIDL sources: [app/src/full/aidl]
RenderScript sources: [app/src/full/rs]
JNI sources: [app/src/full/jni]
JNI libraries: [app/src/full/jniLibs]
Java-style resources: [app/src/full/resources]

A lista de caminhos de arquivo em "debug" descreve onde o AGP procura o código do app e os recursos para uma variação de produto "debug" por padrão. Da mesma forma, a lista de caminhos de arquivo em "full" descreve onde o AGP procura conteúdo para a variação de produto "full" por padrão.

Observe os caminhos de arquivo "Java sources" (para arquivos como as classes Java e Kotlin) e "Android resources" (para arquivos como layouts e imagens). Agora que você sabe onde criar novos conjuntos de origem, faça isso e adicione o código ao recurso premium.

Personalizar o layout da versão "full"

Para adicionar uma caixa à versão "full" do app, siga estas etapas:

Primeiro, crie o conjunto de origem full e o diretório de recursos Java:

  1. Abra o painel Project e selecione a visualização Project.
  2. Navegue até o diretório DiceRoller/app/src/.
  3. Clique com o botão direito do mouse no diretório src e selecione New > Directory.
  4. No menu em Gradle Source Sets, selecione full/resources e pressione Enter.

Em seguida, cole o arquivo activity_main.xml do conjunto de origem main no conjunto de origem full.

  1. Navegue para DiceRoller/app/src/main/res/.
  2. Clique com o botão direito do mouse no arquivo activity_main.xml e em Copy.
  3. Navegue para DiceRoller/app/src/full/res/.
  4. Clique com o botão direito no diretório res e em Paste.

Depois, para adicionar uma caixa à variação full do app, adicione este código ao arquivo activity_main.xml no conjunto de origem full:

<TextView
    android:id="@+id/resultTextView"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:textSize="16sp"
    android:text="Result"
    app:layout_constraintBottom_toTopOf="@+id/button"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintTop_toBottomOf="@id/imageView" />

Execute as variantes de build fullDebug e demoDebug do app. Para isso, selecione a variante de build que você quer executar usando a janela de ferramentas Build Variants e clique em Run. Você vai ver a nova caixa somente para a variante fullDebug. A caixa ainda não faz nada, então vamos programá-la para mudar de acordo com a jogada do dado.

O app DiceRoller com a caixa que diz

Personalizar o comportamento da versão "full"

Para a versão "full" do app, a caixa precisa exibir o resultado escrito da jogada do dado. Para programar esse comportamento, siga estas etapas:

Primeiro, crie o diretório de origem Java do conjunto de origem full.

  1. No painel Project da visualização Project, navegue até o diretório DiceRoller/app/src/full.
  2. Clique com o botão direito do mouse no diretório full e selecione New > Directory.
  3. No menu Gradle Source Sets, selecione java e pressione Enter.

Depois, crie o conjunto de origem debug e o diretório de origem Java.

  1. No painel Project da visualização Project, navegue até o diretório DiceRoller/app/src.
  2. Clique com o botão direito do mouse no diretório src e selecione New > Directory.
  3. No menu Gradle Source Sets, selecione debug/java e pressione Enter.

Depois, navegue até o diretório DiceRoller/app/src/main/java.

  1. Cole o arquivo MainActivity.kt nos diretórios full/java e debug/java.
  2. Exclua o diretório java, incluindo o arquivo MainActivity.kt, do conjunto de origem principal. Clique com o botão direito do mouse no diretório java e em Delete.
  3. No arquivo MainActivity.kt do conjunto de origem completo, adicione o código abaixo ao método rollDice():
// Update the result text view
val resultTextView: TextView = findViewById(R.id.resultTextView)
resultTextView.text = when (diceRoll) {
    1 -> "One"
    2 -> "Two"
    3 -> "Three"
    4 -> "Four"
    5 -> "Five"
    else -> "Six"
}

Execute as variantes de build fullDebug e demoDebug novamente. A caixa na versão "full" deve incluir o resultado da jogada do dado.

App DiceRoller com caixa dinâmica.

Mudar os títulos do app

Para esclarecer, vamos especificar qual versão do app você está usando no título. Na verdade, esse tipo de mudança pode ser feito sem conjuntos de origem. O título do app é definido pela propriedade label no arquivo AndroidManifest.xml (app > manifests > AndroidManifest.xml). Para que o valor label mude de acordo com a variante em execução, abra o arquivo AndroidManifest.xml e mude a linha do rótulo para:

android:label="${appLabel}"

Isso define uma variável, appLabel, como o título do app.

Em seguida, para definir o valor de appLabel ou mudar o título da versão "demo" do app, adicione a linha manifestPlaceholders ao bloco demo {} criado anteriormente:

demo {
   dimension "version"
   manifestPlaceholders = [appLabel: "Dice Roller - Demo"]
   applicationIdSuffix ".demo"
}

Da mesma forma, para mudar o título da variação full do app, adicione outra linha manifestPlaceholders ao bloco full {}:

full {
   dimension "version"
   manifestPlaceholders = [appLabel: "Dice Roller - Full"]
   applicationIdSuffix ".full"
}

Agora, execute as variantes demoDebug e fullDebug novamente. Você vai ver os títulos diferentes para cada variante de build.

O app DiceRoller com a caixa dinâmica foi concluído.

8. Fornecer IDs de aplicativo exclusivos às variantes de build

Ao criar um APK ou AAB para o app, as ferramentas de build marcam o app com o ID do aplicativo definido no bloco defaultConfig {} do arquivo build.gradle no nível do app, como mostrado abaixo. No entanto, se você quiser criar versões diferentes do app para aparecerem como páginas de detalhes separadas na Google Play Store, como uma versão "demo" ou "full", é necessário atribuir um ID do aplicativo diferente a cada uma delas. Para cada variação dentro do bloco productFlavors {}, é possível redefinir a propriedade applicationId ou anexar um segmento ao ID do aplicativo padrão usando applicationIdSuffix, como mostrado abaixo:

defaultConfig {
   applicationId "com.example.diceroller"
   ...
}

flavorDimensions "version"
productFlavors {
   demo {
 dimension "version"
       manifestPlaceholders = [appLabel: "Dice Roller - Demo"]
         applicationIdSuffix ".demo"
   }
   full {
       dimension "version"
       manifestPlaceholders = [appLabel: "Dice Roller - Full"]
         applicationIdSuffix ".full"
   }
}

9. Parabéns

Parabéns! Você criou duas versões do app DiceRoller usando variantes de build.

Você configurou variações de produto e tipos de build para criar variantes de build. Você adicionou um recurso premium à versão "full" do app usando conjuntos de origem. Você aprendeu a atribuir um ID de aplicativo exclusivo a cada variante de build para que elas sejam consideradas apps separados na Play Store.

Agora você sabe as etapas básicas para criar várias versões de um app e atender melhor a diferentes grupos de usuários.

Qual é a próxima etapa?

Documentos de referência