Package Name — چیست، نمادگذاری دامنه معکوس و الزامات

Package Name در اندروید چیست

Package Name — یک رشته منحصر‌به‌فرد است که اندروید برای شناسایی برنامه در سطح سیستم عامل از آن استفاده می‌کند. این رشته با فیلد 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 در iOS به عنوان Bundle ID و در Android به عنوان Package Name خواهد بود.

پیکربندی Package Name در پروژه اندروید

پیکربندی Package Name در پروژه اندروید شامل تغییر 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 یک ماژول می‌تواند بر importها در ماژول‌های دیگر تأثیر بگذارد. اگر ماژول data دارای بسته com.example.data باشد و ماژول domain از کلاس‌های آن استفاده کند، پس از تغییر شناسه importها را در تمام ماژول‌های وابسته به‌روزرسانی کنید. پلاگین Gradle اندروید نسخه 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 را برای هدایت کاربران در نظر بگیرید.