Package Name — o que é, notação de domínio reverso e requisitos

O que é Package Name no Android

Package Name é uma string única que o Android usa para identificar um aplicativo no nível do sistema operacional. Corresponde ao campo package no arquivo AndroidManifest.xml e ao campo applicationId no arquivo build.gradle do módulo do aplicativo. Sem um Package Name único, é impossível instalar um aplicativo no dispositivo do usuário.

Propósito do Package Name

No dispositivo, o Package Name serve como chave para o gerenciamento de aplicativos: o sistema armazena dados, configurações e cache de cada aplicativo no diretório /data/data/[packageName]. Dois aplicativos com o mesmo identificador não podem coexistir — ao tentar instalar uma duplicata, o sistema solicita a remoção do existente.

Package Name e Application ID

No Android Gradle Plugin versão 0.11+, foi introduzida uma separação entre Package Name (no manifesto) e Application ID (no build.gradle). O Application ID é o identificador real do aplicativo para o sistema e o Google Play. O Package Name no manifesto é usado para resolução de recursos e geração da classe R. Recomenda-se mantê-los iguais para simplicidade.

// build.gradle (Module: app)
android {
    defaultConfig {
        applicationId "com.example.myapplication"
        minSdkVersion 24
        targetSdkVersion 34
        versionCode 1
        versionName "1.0"
    }

    buildTypes {
        debug {
            applicationIdSuffix ".debug"
        }
    }
}

O campo applicationIdSuffix permite adicionar um sufixo ao Application ID para diferentes configurações de build. Uma versão debug pode ter o identificador com.example.app.debug, permitindo instalá-la junto com a versão de produção para testes paralelos.

Regras de Nomenclatura do Package Name

O Google Play estabelece regras rigorosas para o Package Name que devem ser seguidas na publicação. O identificador deve ser único em toda a loja, atender aos requisitos sintáticos e não violar políticas de marcas registradas.

Requisitos Sintáticos

O Package Name pode conter apenas letras latinas (A-Z, a-z), dígitos (0-9), ponto final (.) e sublinhado (_). O comprimento máximo é de 150 caracteres. Cada segmento entre os pontos deve começar com uma letra. Hífens, espaços e caracteres especiais são proibidos pelas regras do Google Play.

Requisitos de Unicidade

A unicidade do Package Name é um requisito absoluto da Google Play Store. Se outro aplicativo já usar o identificador selecionado, a publicação será rejeitada. O Google não libera identificadores de aplicativos excluídos, portanto escolher o primeiro Package Name é uma decisão crítica para todo desenvolvedor.

Notação de Domínio Reverso e Convenções

A notação de domínio reverso é um padrão de nomenclatura onde o nome de domínio da empresa é escrito em ordem inversa: com.example em vez de example.com. Este sistema garante a unicidade global dos identificadores porque cada nome de domínio é inerentemente único.

Prefixos Padrão

Os desenvolvedores normalmente usam um prefixo correspondente ao TLD do seu domínio: com para organizações comerciais, org para organizações sem fins lucrativos, io para projetos de tecnologia, net para serviços e soluções de rede. Para projetos pessoais, com.github.username ou com.email é aceitável.

• com.company.app — formato padrão para aplicativos comerciais
• org.company.app — para projetos sem fins lucrativos e open-source
• io.company.app — popular entre startups e produtos SaaS
• com.github.username — para projetos pessoais no GitHub

Convenções para Projetos Multiplataforma

Para aplicativos publicados no iOS e Android, recomenda-se usar o mesmo identificador em ambas as plataformas. Isso simplifica a integração com Firebase, AppsFlyer, Adjust e outros sistemas de análise que se vinculam ao identificador do projeto. Por exemplo, com.mycompany.myapp será o Bundle ID no iOS e Package Name no Android.

Configurar Package Name no Projeto Android

Configurar o Package Name em um projeto Android envolve alterar o applicationId no build.gradle e a estrutura de diretórios de código fonte Java/Kotlin correspondente. O Android Studio fornece ferramentas para refatoração do Package Name, mas para projetos complexos, recomenda-se uma migração passo a passo.

Estrutura de Diretórios e Package Name

// O caminho do arquivo corresponde ao Package Name
// com/example/myapp/MainActivity.kt

package com.example.myapp

import android.os.Bundle
import androidx.activity.ComponentActivity

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
    }
}

Em Kotlin e Java, o Package Name nos arquivos fonte deve corresponder à estrutura de diretórios. Ao alterar o Package Name no build.gradle, você precisa mover os arquivos para os diretórios correspondentes e atualizar todas as declarações package e import. O Android Studio pode fazer isso automaticamente via Refactor -> Move, mas para projetos grandes com dezenas de arquivos, recomenda-se verificar o resultado após a refatoração.

Se o projeto usar Data Binding, View Binding ou Hilt, alterar o Package Name também afetará as classes geradas. As classes de binding são criadas com base no Package Name do módulo e no diretório layout. Após alterar o identificador, você precisará reconstruir o projeto para atualizar todas as referências geradas. Recomenda-se executar uma limpeza de build após alterar o Package Name para evitar erros de referências antigas em cache.

No Gradle 7.0+, foi introduzido suporte para namespace no build.gradle, que substituiu o campo package no AndroidManifest.xml para fins de geração da classe R e recursos. Enquanto isso, o applicationId continua sendo o identificador real do aplicativo para o sistema e o Google Play. Isso permite ter applicationId e namespace diferentes, o que é útil para módulos de biblioteca onde o namespace é fixo enquanto o identificador público pode mudar durante o build.

Para projetos com arquitetura modular, alterar o Package Name de um módulo pode afetar os imports em outros módulos. Se o módulo data tem o pacote com.example.data e o módulo domain usa suas classes, após alterar o identificador, atualize os imports em todos os módulos dependentes. O Android Gradle Plugin versão 8.0+ simplifica este processo com geração automática de namespace a partir do build.gradle.

Verificar Package Name Através do Código

Para obter o Application ID atual, use a classe BuildConfig: BuildConfig.APPLICATION_ID. Isso é útil para lógica condicional no código, vinculação ao ambiente ou exibição do identificador em telas de debug. O BuildConfig é gerado automaticamente com base no build.gradle.

// Obtendo Application ID em tempo de execução
val packageName = BuildConfig.APPLICATION_ID
val packageManager = packageManager
val appInfo = packageManager.getPackageInfo(packageName, 0)

println("App version: ${appInfo.versionName} (${appInfo.versionCode})")
println("Package: $packageName")

Alterar Package Name Após a Publicação

Alterar o Package Name após publicar um aplicativo no Google Play é uma operação que significa criar um produto totalmente novo. O sistema não permite atualizar um aplicativo existente com um Package Name diferente, portanto decidir alterar o identificador equivale a reiniciar o projeto na loja.

Consequências de Alterar o Package Name

Ao alterar o Package Name, perdem-se: todas as classificações e avaliações, estatísticas de instalação, integração com Google Services (se não migrada), links do projeto Firebase (requer criar um novo google-services.json). Os usuários não receberão uma atualização automática — verão o novo aplicativo na loja.

• Classificações e avaliações — permanecem no aplicativo antigo, não transferidas
• Estatísticas de instalação — zeradas para o novo Package Name
• Projetos Firebase — exigem nova configuração do google-services.json e reconfiguração de todos os serviços
• Usuários — não recebem atualizações automáticas, precisam ser notificados separadamente

Quando Alterar Package Name é Justificado

Alterar o Package Name pode ser justificado durante um rebranding da empresa, transferência do aplicativo para outra conta de desenvolvedor ou ao criar uma versão separada para outra região. Em qualquer caso, antes da alteração, recomenda-se notificar os usuários através do aplicativo antigo e preparar um plano de migração com transferência de dados. Sem um plano de migração, os usuários perderão acesso ao conteúdo comprado, assinaturas e dados salvos do aplicativo. A migração inclui transferir o banco de dados e arquivos via SharedPreferences ou Room.

Antes de alterar o Package Name, certifique-se de que o novo identificador é único e segue as regras de nomenclatura. Crie um novo aplicativo no Google Play com o novo Package Name e publique-o como um produto separado. Na descrição do aplicativo antigo, forneça um link para o novo. Considere usar o Google Play Custom Store Listing para redirecionar os usuários.