Configurar o módulo do app

Nesta página você encontra configurações úteis de apps no arquivo build.gradle do módulo que provavelmente precisará ativar ou desativar. Além de fornecer uma visão geral das propriedades importantes definidas no arquivo build.gradle, descrevemos como:

  • mudar o ID do aplicativo para diferentes configurações do build;
  • ajustar com segurança o namespace de forma independente do ID do aplicativo.

Definir o ID do aplicativo

Todo app Android tem um ID do aplicativo exclusivo que se parece com um nome de pacote Java, como com.example.myapp. Esse ID identifica o app de modo exclusivo no dispositivo e na Google Play Store. Depois que você publicar seu app, nunca troque o ID do aplicativo. Se você quiser fazer upload de uma nova versão do app, o ID do aplicativo (e o certificado que você assina com ele) precisa ser igual ao originalmente publicado. Se você mudar o ID do aplicativo, a Google Play Store tratará o upload como um app completamente diferente.

O ID do aplicativo é definido pela propriedade applicationId no arquivo build.gradle do módulo, como mostrado abaixo:

Groovy

android {
    defaultConfig {
        applicationId "com.example.myapp"
        minSdkVersion 15
        targetSdkVersion 24
        versionCode 1
        versionName "1.0"
    }
    ...
}

Kotlin

android {
    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 15
        targetSdk = 24
        versionCode = 1
        versionName = "1.0"
    }
    ...
}

Embora o ID do aplicativo pareça ser um nome de pacote Java tradicional (o namespace do código), as regras de nomenclatura para o ID do aplicativo são um pouco mais restritivas:

  • Ele precisa ter pelo menos dois segmentos (um ou mais pontos).
  • Cada segmento precisa começar com uma letra.
  • Todos os caracteres precisam ser alfanuméricos ou um sublinhado [a-zA-Z0-9_].

Quando você cria um novo projeto no Android Studio, o applicationId é atribuído automaticamente ao nome do pacote no estilo Java que você escolheu durante a configuração. Tecnicamente, é possível ativar/desativar as duas propriedades de maneira independente, mas isso não é recomendado.

Isto é o que recomendamos quanto à definição do ID do aplicativo:

  • Mantenha o ID do aplicativo igual ao namespace. A diferenciação entre as duas propriedades pode ser um pouco confusa, mas se elas forem iguais, você não vai precisar se preocupar.
  • Não mude o ID do aplicativo depois da publicação. Se você mudar, a Google Play Store vai tratar o upload subsequente como um novo app.
  • Defina explicitamente o ID do aplicativo. Se isso não for feito usando a propriedade applicationId, o ID do aplicativo vai assumir automaticamente o mesmo valor do namespace. Isso significa que a edição do namespace vai mudar o ID do aplicativo, o que costuma ser indesejado.

Observação: o ID do aplicativo costumava ser diretamente vinculado ao nome do pacote do código. Por isso, algumas APIs do Android usam o termo "package name" (nome do pacote) nos nomes de métodos e de parâmetros delas, mas esse é, na verdade, o ID do aplicativo. Por exemplo, o método Context.getPackageName() retorna o ID do aplicativo. Não é necessário compartilhar o verdadeiro nome do pacote do código fora do código do app.

Cuidado: se você estiver usando uma WebView, considere usar o nome do pacote como um prefixo no ID do aplicativo, ou você poderá encontrar problemas, conforme descrito no 211768.

Mudar o ID do aplicativo para testes

Por padrão, as ferramentas de compilação aplicam um ID do aplicativo ao seu APK de teste de instrumentação usando o ID do aplicativo para a variante de build em questão, que contém .test no nome. Por exemplo, um APK de teste da variante de compilação com.example.myapp.free tem com.example.myapp.free.test como ID do aplicativo.

Embora não seja necessário, você pode mudar o ID do aplicativo definindo a propriedade testApplicationId no bloco defaultConfig ou productFlavor.

Definir o namespace

Cada módulo do Android tem um namespace, que é usado como nome do pacote Java das classes R e BuildConfig geradas.

O namespace é definido pela propriedade namespace no arquivo build.gradle do módulo, conforme mostrado no snippet de código a seguir. O namespace é definido inicialmente como o nome do pacote no estilo Java que você escolhe ao criar seu projeto.

android {
    namespace 'com.example.myapp'
    ...
}

Ao criar seu app no pacote de aplicativo (APK) final, as ferramentas de build do Android usam o namespace para duas coisas:

  • Elas aplicam esse nome como o namespace para a classe R.java gerada do app, que é usada para acessar os recursos dele.

    Exemplo: no arquivo de build anterior, a classe R é criada em com.example.myapp.R.

  • Elas usam esse nome para resolver quaisquer nomes de classe relativos que são declarados no arquivo de manifesto.

    Exemplo: no arquivo de build anterior, uma atividade declarada como <activity android:name=".MainActivity"> é resolvida como com.example.myapp.MainActivity.

Por isso, o nome definido para a propriedade namespace do arquivo build.gradle precisa sempre corresponder ao nome do pacote básico do seu projeto, em que você mantém as atividades e outros códigos do app. É claro que você pode ter outros subpacotes no projeto, mas esses arquivos precisam importar a classe R.java usando o namespace da propriedade namespace.

Para um fluxo de trabalho mais simples, também recomendamos manter o namespace igual ao ID do aplicativo, já que eles são padrão.

Mudar o namespace

É altamente recomendável manter o namespace e o ID do aplicativo iguais, como eles são por padrão. No entanto, talvez seja necessário mudar o namespace em algum momento se você estiver reorganizando seu código ou para evitar conflitos de namespace. Nesses casos, é possível mudar o namespace atualizando a propriedade namespace no arquivo build.gradle do módulo, independentemente do ID do aplicativo. Antes de fazer isso, confira se o ID do aplicativo está definido explicitamente. Assim, a mudança do namespace não vai mudar o ID do aplicativo. Para mais informações sobre como o namespace pode afetar o ID do aplicativo, consulte Definir o ID do aplicativo.

Se você tiver nomes diferentes para o namespace e o applicationId do Gradle, lembre-se de que as ferramentas de build copiam o ID do aplicativo para o arquivo de manifesto final do app quando a criação termina. Então, se você inspecionar o arquivo AndroidManifest.xml após uma criação, não se surpreenda se o atributo package tiver sido definido como o ID do aplicativo. O atributo package do manifesto integrado é o local que a Google Play Store e a Plataforma Android consultam para identificar seu app.

Mudar o namespace para testes

O namespace padrão dos conjuntos de origem androidTest e test é o namespace principal, com .test adicionado ao fim. Por exemplo, se a propriedade namespace do arquivo build.gradle for com.example.myapp, o namespace para testes será definido como com.example.myapp.test por padrão. Para mudar o namespace para testes, use a propriedade testNamespace, conforme mostrado no snippet de código a seguir:

android {
    namespace 'com.example.myapp'
    testNamespace 'com.example.mytestapp'
    ...
}

Cuidado: não defina testNamespace e namespace com o mesmo valor, porque isso gera conflitos de namespace.

Para saber mais sobre testes, consulte Testar apps no Android.