Package Name — какво е, обратна домейн нотация и изисквания

Какво е Package Name в Android

Package Name — е уникален низ, който Android използва за идентификация на приложението на ниво операционна система. Той съответства на полето package във файла AndroidManifest.xml и на полето applicationId във файла build.gradle на модула на приложението. Без уникален Package Name инсталирането на приложението на устройството на потребителя е невъзможно.

Предназначение на Package Name

На устройството Package Name служи като ключ за управление на приложения: системата съхранява данни, настройки и кеш на всяко приложение в директорията /data/data/[packageName]. Две приложения с еднакъв идентификатор не могат да съществуват едновременно — при опит за инсталиране на дубликат системата предлага премахване на съществуващото.

Package Name и Application ID

В Android Gradle Plugin версия 0.11+ се появи разделение между Package Name (в манифеста) и Application ID (в build.gradle). Application ID е действителният идентификатор на приложението за системата и Google Play. Package Name в манифеста се използва за разрешаване на ресурси и генериране на R клас. Препоръчително е да ги държите еднакви за простота.

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

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

Полето applicationIdSuffix позволява добавяне на суфикс към Application ID за различни конфигурации на компилация. Debug версията може да има идентификатор com.example.app.debug, което позволява инсталирането ѝ до продукционната версия за паралелно тестване.

Правила за именуване на Package Name

Google Play поставя строги правила за Package Name, които трябва да се спазват при публикуване. Идентификаторът трябва да бъде уникален в мащаба на целия магазин, да отговаря на синтактичните изисквания и да не нарушава политиката за използване на търговски марки.

Синтактични изисквания

Package Name може да съдържа само латински букви (A-Z, a-z), цифри (0-9), точка (.) и знак за долна черта (_). Максимална дължина — 150 знака. Всеки сегмент между точките трябва да започва с буква. Тиретата, интервалите и специалните знаци са забранени от правилата на Google Play.

Изисквания за уникалност

Уникалност на Package Name — абсолютно изискване на Google Play Store. Ако друго приложение вече използва избрания идентификатор, публикуването ще бъде отказано. Google не освобождава идентификатори на изтрити приложения, затова изборът на първия Package Name е критично решение за всеки проект на разработчик.

Обратна домейн нотация и конвенции

Обратна домейн нотация — е стандарт за именуване, при който името на домейна на компанията се записва в обратен ред: com.example вместо example.com. Такава система гарантира глобална уникалност на идентификаторите, тъй като всяко домейн име по дефиниция е уникално.

Стандартни префикси

Разработчиците обикновено използват префикс, съответстващ на TLD на техния домейн: com за търговски организации, org за нетърговски, io за технологични проекти, net за мрежови услуги и решения. За лични проекти е допустимо използването на com.github.username или com.email.

• com.company.app — стандартен формат за търговски приложения
• org.company.app — за нетърговски проекти и проекти с отворен код
• io.company.app — популярно сред стартъпи и SaaS продукти
• com.github.username — за лични проекти в GitHub

Конвенции за мултиплатформени проекти

За приложения, публикувани на iOS и Android, се препоръчва използването на един и същ идентификатор на двете платформи. Това опростява интеграцията с Firebase, AppsFlyer, Adjust и други аналитични системи, които се свързват с идентификатора на проекта. Например com.mycompany.myapp ще бъде Bundle ID на iOS и Package Name на Android.

Конфигуриране на Package Name в Android проект

Конфигуриране на Package Name в Android проект включва промяна на applicationId в build.gradle и съответната структура от директории на Java/Kotlin кода. Android Studio предоставя инструменти за рефакториране на Package Name, но за сложни проекти се препоръчва поетапна миграция.

Структура на директориите и Package Name

// Пътят към файла съответства на 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)
    }
}

В Kotlin и Java Package Name в изходните файлове трябва да съответства на структурата от директории. При промяна на Package Name в build.gradle файловете трябва да бъдат преместени в съответните директории и всички декларации package и import трябва да бъдат актуализирани. Android Studio може да направи това автоматично чрез Refactor -> Move, но за големи проекти с десетки файлове се препоръчва проверка на резултата след рефакториране.

Ако проектът използва Data Binding, View Binding или Hilt, промяната на Package Name ще засегне и генерираните класове. Binding класовете се създават на базата на Package Name на модула и директорията layout. След промяна на идентификатора ще е необходимо да се изгради проектът наново, за да се актуализират всички генерирани препратки. Препоръчително е да се изпълни clean build след промяна на Package Name, за да се елиминират грешките поради кеширани стари препратки.

В Gradle 7.0+ се появи поддръжка за namespace в build.gradle, който замени package в AndroidManifest.xml за целите на генериране на R клас и ресурси. В същото време applicationId остава действителният идентификатор на приложението за системата и Google Play. Това позволява различни applicationId и namespace, което е полезно за библиотечни модули, където namespace е фиксиран, а публичният идентификатор може да се променя при компилация.

За проекти с модулна архитектура, промяната на Package Name на един модул може да засегне импорти в други модули. Ако модулът data има пакет com.example.data, а модулът domain използва неговите класове, след промяна на идентификатора актуализирайте импорти във всички зависими модули. Приставката Gradle за Android версия 8.0+ опростява този процес чрез автоматично генериране на namespace от build.gradle.

Проверка на Package Name чрез код

Текущият Application ID може да бъде получен чрез класа BuildConfig: BuildConfig.APPLICATION_ID. Това е удобно за условна логика в кода, обвързване със средата или показване на идентификатора на debug екрани. BuildConfig се генерира автоматично на базата на build.gradle.

// Получаване на Application ID по време на изпълнение
val packageName = BuildConfig.APPLICATION_ID
val packageManager = packageManager
val appInfo = packageManager.getPackageInfo(packageName, 0)

println("Версия на приложението: ${appInfo.versionName} (${appInfo.versionCode})")
println("Пакет: $packageName")

Промяна на Package Name след публикуване

Промяна на Package Name след публикуване на приложението в Google Play — операция, която означава създаване на напълно нов продукт. Системата не позволява актуализиране на съществуващо приложение с друг Package Name, затова решението за промяна на идентификатора е равносилно на рестартиране на проекта в магазина.

Последици от промяна на Package Name

При промяна на Package Name се губят: всички рейтинги и отзиви, статистика за инсталации, интеграция с Google Services (ако не е прехвърлена), препратки към Firebase проект (изисква създаване на нов google-services.json). Потребителите няма да получат автоматична актуализация — те ще видят ново приложение в магазина.

• Рейтинги и отзиви — остават при старото приложение, не се прехвърлят
• Статистика за инсталации — се нулира за новия Package Name
• Firebase проекти — изискват нова конфигурация на google-services.json и пренастройване на всички услуги
• Потребители — не получават автоматична актуализация, трябва да бъдат уведомени отделно

Кога промяната на Package Name е оправдана

Промяна на Package Name може да бъде оправдана при ребрандиране на компанията, прехвърляне на приложението под друг акаунт на разработчик или при създаване на отделна версия за друг регион. Във всеки случай, преди промяна се препоръчва уведомяване на потребителите чрез старото приложение и подготовка на миграционен план с прехвърляне на данни. Без миграционен план потребителите ще загубят достъп до закупено съдържание, абонаменти и запазени данни на приложението. Миграцията включва прехвърляне на база данни и файлове чрез SharedPreferences или Room.

Преди промяна на Package Name се уверете, че новият идентификатор е уникален и отговаря на правилата за именуване. Създайте ново приложение в Google Play с новия Package Name и го публикувайте като отделен продукт. В описанието на старото приложение добавете линк към новото. Обмислете използването на Google Play Custom Store Listing за пренасочване на потребители.