Package Name — định nghĩa, ký pháp tên miền ngược và yêu cầu

Package Name trong Android là gì

Package Name là một chuỗi duy nhất mà Android sử dụng để nhận dạng ứng dụng ở cấp hệ điều hành. Nó tương ứng với trường package trong tệp AndroidManifest.xml và trường applicationId trong tệp build.gradle của mô-đun ứng dụng. Nếu không có Package Name duy nhất, không thể cài đặt ứng dụng trên thiết bị người dùng.

Mục đích của Package Name

Trên thiết bị, Package Name đóng vai trò là khóa quản lý ứng dụng: hệ thống lưu trữ dữ liệu, cài đặt và bộ nhớ đệm của mỗi ứng dụng trong thư mục /data/data/[packageName]. Hai ứng dụng có cùng định danh không thể cùng tồn tại — khi cố gắng cài đặt bản sao, hệ thống sẽ yêu cầu xóa ứng dụng hiện có.

Package Name và Application ID

Trong Android Gradle Plugin phiên bản 0.11+, sự phân tách đã được giới thiệu giữa Package Name (trong tập tin kê khai) và Application ID (trong build.gradle). Application ID là định danh ứng dụng thực tế cho hệ thống và Google Play. Package Name trong tập tin kê khai được sử dụng để giải quyết tài nguyên và tạo lớp R. Nên giữ chúng giống nhau để đơn giản.

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

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

Trường applicationIdSuffix cho phép thêm hậu tố vào Application ID cho các cấu hình build khác nhau. Phiên bản debug có thể có định danh com.example.app.debug, cho phép cài đặt cùng với phiên bản production để kiểm thử song song.

Quy tắc đặt tên Package Name

Google Play đặt ra các quy tắc nghiêm ngặt cho Package Name phải tuân thủ khi xuất bản. Định danh phải là duy nhất trên toàn cửa hàng, đáp ứng các yêu cầu cú pháp và không vi phạm chính sách nhãn hiệu.

Yêu cầu cú pháp

Package Name chỉ có thể chứa chữ cái Latin (A-Z, a-z), chữ số (0-9), dấu chấm (.) và dấu gạch dưới (_). Độ dài tối đa là 150 ký tự. Mỗi đoạn giữa các dấu chấm phải bắt đầu bằng một chữ cái. Dấu gạch nối, khoảng trắng và ký tự đặc biệt bị cấm theo quy tắc Google Play.

Yêu cầu về tính duy nhất

Tính duy nhất của Package Name là một yêu cầu tuyệt đối của Google Play Store. Nếu một ứng dụng khác đã sử dụng định danh được chọn, việc xuất bản sẽ bị từ chối. Google không giải phóng định danh của các ứng dụng đã bị xóa, vì vậy việc chọn Package Name đầu tiên là một quyết định quan trọng đối với mọi nhà phát triển.

Ký pháp tên miền ngược và quy ước

Ký pháp tên miền ngược là một tiêu chuẩn đặt tên trong đó tên miền của công ty được viết theo thứ tự ngược: com.example thay vì example.com. Hệ thống này đảm bảo tính duy nhất toàn cầu của các định danh vì mỗi tên miền vốn dĩ là duy nhất.

Tiền tố chuẩn

Các nhà phát triển thường sử dụng tiền tố tương ứng với TLD của miền: com cho tổ chức thương mại, org cho tổ chức phi lợi nhuận, io cho dự án công nghệ, net cho dịch vụ và giải pháp mạng. Đối với dự án cá nhân, có thể sử dụng com.github.username hoặc com.email.

• com.company.app — định dạng chuẩn cho ứng dụng thương mại
• org.company.app — cho dự án phi lợi nhuận và mã nguồn mở
• io.company.app — phổ biến trong các startup và sản phẩm SaaS
• com.github.username — cho dự án cá nhân trên GitHub

Quy ước cho dự án đa nền tảng

Đối với các ứng dụng được phát hành trên iOS và Android, nên sử dụng cùng một định danh trên cả hai nền tảng. Điều này đơn giản hóa việc tích hợp với Firebase, AppsFlyer, Adjust và các hệ thống phân tích khác gắn với định danh dự án. Ví dụ, com.mycompany.myapp sẽ là Bundle ID trên iOS và Package Name trên Android.

Cấu hình Package Name trong dự án Android

Cấu hình Package Name trong dự án Android bao gồm việc thay đổi applicationId trong build.gradle và cấu trúc thư mục mã nguồn Java/Kotlin tương ứng. Android Studio cung cấp các công cụ tái cấu trúc Package Name, nhưng đối với các dự án phức tạp, nên di chuyển từng bước.

Cấu trúc thư mục và Package Name

// Đường dẫn tệp tương ứng với 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)
    }
}

Trong Kotlin và Java, Package Name trong các tệp nguồn phải khớp với cấu trúc thư mục. Khi thay đổi Package Name trong build.gradle, bạn cần di chuyển các tệp đến các thư mục tương ứng và cập nhật tất cả các khai báo package và import. Android Studio có thể thực hiện việc này tự động qua Refactor -> Move, nhưng đối với các dự án lớn với hàng chục tệp, nên kiểm tra kết quả sau khi tái cấu trúc.

Nếu dự án sử dụng Data Binding, View Binding hoặc Hilt, việc thay đổi Package Name cũng sẽ ảnh hưởng đến các lớp được tạo. Các lớp binding được tạo dựa trên Package Name của mô-đun và thư mục layout. Sau khi thay đổi định danh, bạn cần xây dựng lại dự án để cập nhật tất cả các tham chiếu được tạo. Nên thực hiện clean build sau khi thay đổi Package Name để tránh lỗi từ các tham chiếu cũ được lưu trong bộ nhớ đệm.

Trong Gradle 7.0+, hỗ trợ cho namespace trong build.gradle đã được giới thiệu, thay thế trường package trong AndroidManifest.xml cho mục đích tạo lớp R và tài nguyên. Trong khi đó, applicationId vẫn là định danh ứng dụng thực tế cho hệ thống và Google Play. Điều này cho phép có applicationId và namespace khác nhau, hữu ích cho các mô-đun thư viện nơi namespace cố định trong khi định danh công khai có thể thay đổi trong quá trình build.

Đối với các dự án có kiến trúc mô-đun, việc thay đổi Package Name của một mô-đun có thể ảnh hưởng đến các import trong các mô-đun khác. Nếu mô-đun data có gói com.example.data và mô-đun domain sử dụng các lớp của nó, sau khi thay đổi định danh, hãy cập nhật import trong tất cả các mô-đun phụ thuộc. Android Gradle Plugin phiên bản 8.0+ đơn giản hóa quá trình này với việc tự động tạo namespace từ build.gradle.

Kiểm tra Package Name qua mã

Để lấy Application ID hiện tại, hãy sử dụng lớp BuildConfig: BuildConfig.APPLICATION_ID. Điều này thuận tiện cho logic có điều kiện trong mã, liên kết môi trường hoặc hiển thị định danh trong màn hình debug. BuildConfig được tạo tự động dựa trên build.gradle.

// Lấy Application ID trong thời gian chạy
val packageName = BuildConfig.APPLICATION_ID
val packageManager = packageManager
val appInfo = packageManager.getPackageInfo(packageName, 0)

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

Thay đổi Package Name sau khi xuất bản

Thay đổi Package Name sau khi xuất bản ứng dụng trên Google Play là một thao tác đồng nghĩa với việc tạo một sản phẩm hoàn toàn mới. Hệ thống không cho phép cập nhật ứng dụng hiện có với Package Name khác, vì vậy quyết định thay đổi định danh tương đương với việc khởi động lại dự án trong cửa hàng.

Hậu quả của việc thay đổi Package Name

Khi thay đổi Package Name, sẽ mất: tất cả xếp hạng và đánh giá, thống kê cài đặt, tích hợp Google Services (nếu không được di chuyển), liên kết dự án Firebase (yêu cầu tạo google-services.json mới). Người dùng sẽ không nhận được cập nhật tự động — họ sẽ thấy ứng dụng mới trong cửa hàng.

• Xếp hạng và đánh giá — vẫn ở lại với ứng dụng cũ, không được chuyển
• Thống kê cài đặt — được đặt lại cho Package Name mới
• Dự án Firebase — yêu cầu cấu hình google-services.json mới và cấu hình lại tất cả các dịch vụ
• Người dùng — không nhận được cập nhật tự động, cần được thông báo riêng

Khi nào việc thay đổi Package Name là hợp lý

Thay đổi Package Name có thể hợp lý khi đổi thương hiệu công ty, chuyển ứng dụng sang tài khoản nhà phát triển khác hoặc tạo phiên bản riêng cho khu vực khác. Trong mọi trường hợp, trước khi thay đổi, nên thông báo cho người dùng qua ứng dụng cũ và chuẩn bị kế hoạch di chuyển với chuyển dữ liệu. Nếu không có kế hoạch di chuyển, người dùng sẽ mất quyền truy cập vào nội dung đã mua, đăng ký và dữ liệu ứng dụng đã lưu. Việc di chuyển bao gồm chuyển cơ sở dữ liệu và tệp qua SharedPreferences hoặc Room.

Trước khi thay đổi Package Name, hãy đảm bảo định danh mới là duy nhất và tuân thủ các quy tắc đặt tên. Tạo ứng dụng mới trong Google Play với Package Name mới và xuất bản nó như một sản phẩm riêng. Trong mô tả ứng dụng cũ, cung cấp liên kết đến ứng dụng mới. Cân nhắc sử dụng Google Play Custom Store Listing để chuyển hướng người dùng.