Package Name — definizione, notazione di dominio inverso e requisiti

Cos’è Package Name in Android

Package Name è una stringa univoca che Android utilizza per identificare un’applicazione a livello di sistema operativo. Corrisponde al campo package nel file AndroidManifest.xml e al campo applicationId nel file build.gradle del modulo dell’applicazione. Senza un Package Name univoco, è impossibile installare un’applicazione sul dispositivo dell’utente.

Scopo di Package Name

Sul dispositivo, Package Name funge da chiave per la gestione delle applicazioni: il sistema archivia dati, impostazioni e cache di ciascuna applicazione nella directory /data/data/[packageName]. Due applicazioni con lo stesso identificatore non possono coesistere — quando si tenta di installare un duplicato, il sistema richiede di rimuovere l’esistente.

Package Name e Application ID

In Android Gradle Plugin versione 0.11+, è stata introdotta una separazione tra Package Name (nel manifest) e Application ID (in build.gradle). Application ID è l’identificatore effettivo dell’applicazione per il sistema e Google Play. Package Name nel manifest viene utilizzato per la risoluzione delle risorse e la generazione della classe R. Si consiglia di mantenerli uguali per semplicità.

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

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

Il campo applicationIdSuffix consente di aggiungere un suffisso ad Application ID per diverse configurazioni di build. Una versione debug può avere l’identificatore com.example.app.debug, permettendo l’installazione insieme alla versione di produzione per test paralleli.

Regole di denominazione di Package Name

Google Play stabilisce regole rigide per Package Name che devono essere seguite al momento della pubblicazione. L’identificatore deve essere univoco in tutto lo store, soddisfare i requisiti sintattici e non violare le politiche sui marchi.

Requisiti sintattici

Package Name può contenere solo lettere latine (A-Z, a-z), cifre (0-9), un punto (.) e il trattino basso (_). La lunghezza massima è di 150 caratteri. Ogni segmento tra i punti deve iniziare con una lettera. Trattini, spazi e caratteri speciali sono proibiti dalle regole di Google Play.

Requisiti di unicità

L’unicità di Package Name è un requisito assoluto del Google Play Store. Se un’altra applicazione utilizza già l’identificatore selezionato, la pubblicazione verrà rifiutata. Google non rilascia gli identificatori delle applicazioni eliminate, quindi scegliere il primo Package Name è una decisione critica per ogni sviluppatore.

Notazione di dominio inverso e convenzioni

La notazione di dominio inverso è uno standard di denominazione in cui il nome di dominio dell’azienda viene scritto in ordine inverso: com.example invece di example.com. Questo sistema garantisce l’unicità globale degli identificatori poiché ogni nome di dominio è intrinsecamente unico.

Prefissi standard

Gli sviluppatori in genere utilizzano un prefisso corrispondente al TLD del loro dominio: com per organizzazioni commerciali, org per organizzazioni no-profit, io per progetti tecnologici, net per servizi e soluzioni di rete. Per progetti personali, è accettabile com.github.username o com.email.

• com.company.app — formato standard per applicazioni commerciali
• org.company.app — per progetti no-profit e open-source
• io.company.app — popolare tra startup e prodotti SaaS
• com.github.username — per progetti personali su GitHub

Convenzioni per progetti multipiattaforma

Per le applicazioni rilasciate su iOS e Android, si consiglia di utilizzare lo stesso identificatore su entrambe le piattaforme. Ciò semplifica l’integrazione con Firebase, AppsFlyer, Adjust e altri sistemi di analisi che si legano all’identificatore del progetto. Ad esempio, com.mycompany.myapp sarà il Bundle ID su iOS e Package Name su Android.

Configurare Package Name in un progetto Android

La configurazione di Package Name in un progetto Android comporta la modifica di applicationId in build.gradle e della corrispondente struttura delle directory del codice sorgente Java/Kotlin. Android Studio fornisce strumenti per il refactoring di Package Name, ma per progetti complessi si consiglia una migrazione graduale.

Struttura delle directory e Package Name

// Il percorso del file corrisponde a 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)
    }
}

In Kotlin e Java, il Package Name nei file sorgente deve corrispondere alla struttura delle directory. Quando si modifica Package Name in build.gradle, è necessario spostare i file nelle directory corrispondenti e aggiornare tutte le dichiarazioni package e import. Android Studio può eseguire questa operazione automaticamente tramite Refactor -> Move, ma per progetti grandi con dozzine di file, si consiglia di verificare il risultato dopo il refactoring.

Se il progetto utilizza Data Binding, View Binding o Hilt, la modifica di Package Name influenzerà anche le classi generate. Le classi di binding vengono create in base al Package Name del modulo e alla directory layout. Dopo aver cambiato l’identificatore, sarà necessario ricostruire il progetto per aggiornare tutti i riferimenti generati. Si consiglia di eseguire una clean build dopo la modifica di Package Name per evitare errori dovuti a vecchi riferimenti in cache.

In Gradle 7.0+, è stato introdotto il supporto per namespace in build.gradle, che ha sostituito il campo package in AndroidManifest.xml per la generazione della classe R e delle risorse. Nel frattempo, applicationId rimane l’identificatore effettivo dell’applicazione per il sistema e Google Play. Ciò consente di avere applicationId e namespace diversi, utile per i moduli libreria dove namespace è fisso mentre l’identificatore pubblico può cambiare durante il build.

Per progetti con architettura modulare, la modifica di Package Name di un modulo può influenzare gli import in altri moduli. Se il modulo data ha il pacchetto com.example.data e il modulo domain utilizza le sue classi, dopo aver cambiato l’identificatore, aggiornare gli import in tutti i moduli dipendenti. Android Gradle Plugin versione 8.0+ semplifica questo processo con la generazione automatica di namespace da build.gradle.

Verificare Package Name tramite codice

Per ottenere l’Application ID corrente, utilizzare la classe BuildConfig: BuildConfig.APPLICATION_ID. Ciò è utile per la logica condizionale nel codice, il binding all’ambiente o la visualizzazione dell’identificatore nelle schermate di debug. BuildConfig viene generato automaticamente in base a build.gradle.

// Ottenere Application ID in fase di esecuzione
val packageName = BuildConfig.APPLICATION_ID
val packageManager = packageManager
val appInfo = packageManager.getPackageInfo(packageName, 0)

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

Modificare Package Name dopo la pubblicazione

Modificare Package Name dopo aver pubblicato un’applicazione su Google Play è un’operazione che significa creare un prodotto completamente nuovo. Il sistema non consente di aggiornare un’applicazione esistente con un Package Name diverso, quindi decidere di cambiare l’identificatore equivale a riavviare il progetto nello store.

Conseguenze della modifica di Package Name

Modificando Package Name si perdono: tutte le valutazioni e recensioni, statistiche di installazione, integrazione con Google Services (se non migrata), collegamenti al progetto Firebase (richiede la creazione di un nuovo google-services.json). Gli utenti non riceveranno un aggiornamento automatico — vedranno la nuova applicazione nello store.

• Valutazioni e recensioni — rimangono con l’applicazione precedente, non vengono trasferite
• Statistiche di installazione — vengono azzerate per il nuovo Package Name
• Progetti Firebase — richiedono una nuova configurazione google-services.json e la riconfigurazione di tutti i servizi
• Utenti — non ricevono aggiornamenti automatici, devono essere notificati separatamente

Quando la modifica di Package Name è giustificata

Modificare Package Name può essere giustificato durante un rebranding aziendale, il trasferimento dell’applicazione a un altro account sviluppatore o la creazione di una versione separata per un’altra regione. In ogni caso, prima della modifica, si consiglia di informare gli utenti tramite l’applicazione precedente e preparare un piano di migrazione con trasferimento dati. Senza un piano di migrazione, gli utenti perderanno l’accesso ai contenuti acquistati, agli abbonamenti e ai dati salvati dell’applicazione. La migrazione include il trasferimento del database e dei file tramite SharedPreferences o Room.

Prima di modificare Package Name, assicurarsi che il nuovo identificatore sia univoco e rispetti le regole di denominazione. Creare una nuova applicazione in Google Play con il nuovo Package Name e pubblicarla come prodotto separato. Nella descrizione dell’applicazione precedente, fornire un collegamento alla nuova. Considerare l’utilizzo di Google Play Custom Store Listing per reindirizzare gli utenti.