This page describes useful app settings in the module-level build.gradle
file
that you will likely want to toggle. In addition to giving an overview of
important properties set in the build.gradle
file, we describe how you can:
- Change the application ID for different build configurations.
- Safely adjust the namespace independent of the application ID.
Set the application ID
Every Android app has a unique application ID that looks like a Java package name, such as com.example.myapp. This ID uniquely identifies your app on the device and in Google Play Store. Once you publish your app, you should never change the application ID. If you want to upload a new version of your app, the application ID (and the certificate you sign it with) must be the same as what it was when originally published—if you change the application ID, Google Play Store treats the upload as a completely different app.
Your application ID is defined by the applicationId
property in your module's
build.gradle
file, as shown here:
Groovy
android { defaultConfig { applicationId "com.example.myapp" minSdkVersion 15 targetSdkVersion 24 versionCode 1 versionName "1.0" } ... }
Kotlin
android { defaultConfig { applicationId = "com.example.myapp" minSdk = 15 targetSdk = 24 versionCode = 1 versionName = "1.0" } ... }
Although the application ID looks like a traditional Java package name (your code’s namespace), the naming rules for the application ID are a bit more restrictive:
- It must have at least two segments (one or more dots).
- Each segment must start with a letter.
- All characters must be alphanumeric or an underscore [a-zA-Z0-9_].
When you create a new project in Android
Studio, the applicationId
is
automatically assigned the Java-style package name you chose during setup. You
can technically toggle the two properties independently from then on, but we
don’t recommend it.
Here is what we recommend when it comes to setting the application ID:
- Keep the application ID the same as the namespace. The distinction between the the two properties can be a bit confusing, but if you keep them same, you have nothing to worry about.
- Do not change the application ID after you publish your app. If you change it, Google Play Store will treat the subsequent upload as a new app.
- Explicitly define the application ID. If the application ID is not explicitly
defined using the
applicationId
property, it automatically takes on the same value as the namespace. This means that changing the namespace changes the application ID, which is usually undesired.
Note: The application ID used to be directly tied to
your code's package name; so some Android APIs use the term "package name" in
their method names and parameter names, but this is actually your application
ID. For example, the Context.getPackageName()
method returns your application ID.
There's no need to ever share your code's true package name outside your app
code.
Caution: If you are using WebView
,
consider using your package name as a prefix in your application
ID; otherwise you might encounter problems as described in issue
211768.
Change the application ID for testing
By default, the build tools apply an application ID to your
instrumentation test
APK using the application ID for the given build variant, appended with
.test
. For example, a test APK for the com.example.myapp.free
build variant
has the application ID com.example.myapp.free.test
.
Although it shouldn't be necessary, you can change the application ID by
defining the testApplicationId
property in your defaultConfig
or
productFlavor
block.
Set the namespace
Every Android module has a namespace, which is used as the Java package name for
its generated R
and BuildConfig
classes.
Your namespace is defined by the namespace
property in your module's
build.gradle
file, as shown in the following code snippet. The namespace
is
initially set to the Java-style package name you choose when you create your
project.
android {
namespace 'com.example.myapp'
...
}
While building your app into the final application package (APK), the Android
build tools use the namespace as the namespace for your app's generated R
class (used to access your
app resources).
For example, in the preceding build file, the R
class is created at
com.example.myapp.R
.
As such, the name you set for the build.gradle
file's namespace
property
should always match your project's base package name, where you keep your
activities and other app code. Of course, you can have other sub-packages in
your project, but those files must import the R
class using the
namespace from the namespace
property.
For a simpler workflow, you should keep your namespace the same as your application ID, as they are by default.
Change the namespace
For simplicity, you should try to keep the namespace and application ID the
same, as they are by default. However, you may need to change the namespace at
some point if you're reorganizing your code, or to avoid namespace collisions.
In these cases, it is possible to change the namespace (by updating the
namespace
property in your module's build.gradle
file) independent of the
application ID. Before you do so, make sure that your application ID is
explicitly defined, so that changing the namespace doesn't likewise change the
application ID. For more information on how the namespace can affect the
application ID, see Set the application ID.
If you have different names for the namespace
and the Gradle applicationId
, remember that the build tools copy
the application ID into your app's final manifest file at the end of the build.
So if you inspect your AndroidManifest.xml
file after a build,
don't be surprised that the package
attribute has been set to the
application ID. The merged manifest's package
attribute is where
Google Play Store and the Android platform actually look to identify your app.
Change the namespace for testing
The default namespace for the androidTest
and test
source sets is the main
namespace, with .test
added at the end. For example, if the
namespace
property in the build.gradle
file is
com.example.myapp
, the testing namespace is by default set to
com.example.myapp.test
. To change the namespace for testing, use the
testNamespace
property, as shown in the following code snippet:
android {
namespace 'com.example.myapp'
testNamespace 'com.example.mytestapp'
...
}
Caution: Do not set testNamespace
and
namespace
to the same value, otherwise there will be namespace
collisions.
To learn more about testing, see Test apps on Android.