Configure the app module

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:

android {
    defaultConfig {
        applicationId "com.example.myapp"
        minSdkVersion 15
        targetSdkVersion 24
        versionCode 1
        versionName "1.0"
    }
    ...
}

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.