Package Name — co to jest, odwrotna notacja domenowa i wymagania

Czym jest Package Name w Android

Package Name — to unikalny ciąg znaków, którego Android używa do identyfikacji aplikacji na poziomie systemu operacyjnego. Odpowiada on polu package w pliku AndroidManifest.xml oraz polu applicationId w pliku build.gradle modułu aplikacji. Bez unikalnego Package Name instalacja aplikacji na urządzeniu użytkownika jest niemożliwa.

Przeznaczenie Package Name

Na urządzeniu Package Name pełni rolę klucza do zarządzania aplikacjami: system przechowuje dane, ustawienia i pamięć podręczną każdej aplikacji w katalogu /data/data/[packageName]. Dwie aplikacje z tym samym identyfikatorem nie mogą współistnieć — przy próbie zainstalowania duplikatu system proponuje usunięcie istniejącej.

Package Name a Application ID

W Android Gradle Plugin w wersji 0.11+ pojawiło się rozdzielenie między Package Name (w manifeście) a Application ID (w build.gradle). Application ID to faktyczny identyfikator aplikacji dla systemu i Google Play. Package Name w manifeście jest używany do rozwiązywania zasobów i generowania klasy R. Zaleca się utrzymywanie ich w zgodności dla uproszczenia.

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

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

Pole applicationIdSuffix pozwala dodać sufiks do Application ID dla różnych konfiguracji kompilacji. Wersja debug może mieć identyfikator com.example.app.debug, co umożliwia zainstalowanie jej obok wersji produkcyjnej do równoległego testowania.

Zasady nazewnictwa Package Name

Google Play ustanawia ścisłe zasady dla Package Name, których należy przestrzegać przy publikacji. Identyfikator musi być unikalny w skali całego sklepu, spełniać wymagania składniowe i nie naruszać polityki dotyczącej znaków towarowych.

Wymagania składniowe

Package Name może zawierać tylko litery łacińskie (A-Z, a-z), cyfry (0-9), kropkę (.) i znak podkreślenia (_). Maksymalna długość — 150 znaków. Każdy segment między kropkami musi zaczynać się od litery. Łączniki, spacje i znaki specjalne są zabronione przez zasady Google Play.

Wymagania dotyczące unikalności

Unikalność Package Name — to bezwzględny wymóg Google Play Store. Jeśli inna aplikacja już używa wybranego identyfikatora, publikacja zostanie odrzucona. Google nie zwalnia identyfikatorów usuniętych aplikacji, dlatego wybór pierwszego Package Name to krytyczna decyzja dla każdego projektu deweloperskiego.

Odwrotna notacja domenowa i konwencje

Odwrotna notacja domenowa — to standard nazewnictwa, w którym nazwa domeny firmy jest zapisywana w odwrotnej kolejności: com.example zamiast example.com. Taki system gwarantuje globalną unikalność identyfikatorów, ponieważ każda nazwa domeny jest z definicji unikalna.

Standardowe prefiksy

Deweloperzy zazwyczaj używają prefiksu odpowiadającego TLD ich domeny: com dla organizacji komercyjnych, org dla non-profit, io dla projektów technologicznych, net dla usług sieciowych i rozwiązań. Dla projektów osobistych dopuszczalne jest użycie com.github.username lub com.email.

• com.company.app — standardowy format dla aplikacji komercyjnych
• org.company.app — dla projektów non-profit i open-source
• io.company.app — popularne wśród startupów i produktów SaaS
• com.github.username — dla projektów osobistych na GitHub

Konwencje dla projektów wieloplatformowych

Dla aplikacji wydawanych na iOS i Android zaleca się używanie tego samego identyfikatora na obu platformach. Upraszcza to integrację z Firebase, AppsFlyer, Adjust i innymi systemami analitycznymi, które wiążą się z identyfikatorem projektu. Na przykład com.mycompany.myapp będzie Bundle ID na iOS i Package Name na Android.

Konfiguracja Package Name w projekcie Android

Konfiguracja Package Name w projekcie Android obejmuje zmianę applicationId w build.gradle oraz odpowiedniej struktury katalogów kodu Java/Kotlin. Android Studio udostępnia narzędzia do refaktoryzacji Package Name, ale dla złożonych projektów zaleca się migrację krok po kroku.

Struktura katalogów a Package Name

// Ścieżka pliku odpowiada 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)
    }
}

W Kotlin i Java Package Name w plikach źródłowych musi odpowiadać strukturze katalogów. Przy zmianie Package Name w build.gradle należy przenieść pliki do odpowiednich katalogów i zaktualizować wszystkie deklaracje package i import. Android Studio potrafi to robić automatycznie przez Refactor -> Move, ale dla dużych projektów z dziesiątkami plików zaleca się sprawdzenie wyniku po refaktoryzacji.

Jeśli projekt używa Data Binding, View Binding lub Hilt, zmiana Package Name wpłynie również na generowane klasy. Klasy Binding są tworzone na podstawie Package Name modułu i katalogu layout. Po zmianie identyfikatora konieczne będzie przebudowanie projektu, aby zaktualizować wszystkie wygenerowane odniesienia. Zaleca się wykonanie clean build po zmianie Package Name, aby wyeliminować błędy z powodu buforowanych starych odniesień.

W Gradle 7.0+ pojawiła się obsługa namespace w build.gradle, który zastąpił package w AndroidManifest.xml do celów generowania klasy R i zasobów. Przy czym applicationId pozostaje faktycznym identyfikatorem aplikacji dla systemu i Google Play. Pozwala to na posiadanie różnych applicationId i namespace, co jest przydatne dla modułów bibliotecznych, gdzie namespace jest stały, a publiczny identyfikator może się zmieniać podczas kompilacji.

Dla projektów z architekturą modułową zmiana Package Name jednego modułu może wpłynąć na importy w innych modułach. Jeśli moduł data ma pakiet com.example.data, a moduł domain używa jego klas, po zmianie identyfikatora zaktualizuj importy we wszystkich zależnych modułach. Wtyczka Gradle Android w wersji 8.0+ upraszcza ten proces dzięki automatycznej generacji namespace z build.gradle.

Sprawdzanie Package Name przez kod

Bieżący Application ID można uzyskać przez klasę BuildConfig: BuildConfig.APPLICATION_ID. Jest to wygodne do logiki warunkowej w kodzie, wiązania ze środowiskiem lub wyświetlania identyfikatora na ekranach debug. BuildConfig jest generowany automatycznie na podstawie build.gradle.

// Pobieranie Application ID w czasie wykonania
val packageName = BuildConfig.APPLICATION_ID
val packageManager = packageManager
val appInfo = packageManager.getPackageInfo(packageName, 0)

println("Wersja aplikacji: ${appInfo.versionName} (${appInfo.versionCode})")
println("Pakiet: $packageName")

Zmiana Package Name po publikacji

Zmiana Package Name po publikacji aplikacji w Google Play — to operacja, która oznacza utworzenie całkowicie nowego produktu. System nie pozwala na aktualizację istniejącej aplikacji z innym Package Name, dlatego decyzja o zmianie identyfikatora jest równoznaczna z ponownym uruchomieniem projektu w sklepie.

Konsekwencje zmiany Package Name

Przy zmianie Package Name tracone są: wszystkie oceny i recenzje, statystyki instalacji, integracja z Google Services (jeśli nie została przeniesiona), odniesienia do projektu Firebase (wymaga utworzenia nowego google-services.json). Użytkownicy nie otrzymają automatycznej aktualizacji — zobaczą nową aplikację w sklepie.

• Oceny i recenzje — pozostają przy starej aplikacji, nie są przenoszone
• Statystyki instalacji — są zerowane dla nowego Package Name
• Projekty Firebase — wymagają nowej konfiguracji google-services.json i ponownego skonfigurowania wszystkich usług
• Użytkownicy — nie otrzymują automatycznej aktualizacji, należy ich poinformować osobno

Kiedy zmiana Package Name jest uzasadniona

Zmiana Package Name może być uzasadniona przy rebrandingu firmy, przeniesieniu aplikacji na inne konto deweloperskie lub przy tworzeniu oddzielnej wersji dla innego regionu. W każdym przypadku przed zmianą zaleca się poinformowanie użytkowników przez starą aplikację i przygotowanie planu migracji z przeniesieniem danych. Bez planu migracji użytkownicy stracą dostęp do zakupionych treści, subskrypcji i zapisanych danych aplikacji. Migracja obejmuje przeniesienie bazy danych i plików przez SharedPreferences lub Room.

Przed zmianą Package Name upewnij się, że nowy identyfikator jest unikalny i zgodny z zasadami nazewnictwa. Utwórz nową aplikację w Google Play z nowym Package Name i opublikuj ją jako osobny produkt. W opisie starej aplikacji umieść link do nowej. Rozważ użycie Google Play Custom Store Listing do przekierowania użytkowników.