Configure the app module

This page describes useful app settings in the module-level build.gradle.kts file. In addition to giving an overview of important properties set in the build.gradle.kts file, learn how to:

• 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 or Kotlin package name, such as com.example.myapp. This ID uniquely identifies your app on the device and in the Google Play Store.

Your application ID is defined by the applicationId property in your module's build.gradle.kts file, as shown here. Update the value of the applicationId by replacing com.example.myapp with your app's ID:

android {
    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 15
        targetSdk = 24
        versionCode = 1
        versionName = "1.0"
    }
    ...
}

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

Although the application ID looks like a traditional Kotlin or Java package name, 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 package name you chose during setup. You can technically toggle the two properties independently from then on, but it is not recommended.

It is recommended that you do the following when setting the application ID:

• Keep the application ID the same as the namespace. The distinction between the two properties can be a bit confusing, but if you keep them the same, you have nothing to worry about.
• Don't change the application ID after you publish your app. If you change it, Google Play Store treats 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 not what you want.

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 Kotlin or Java package name for its generated R and BuildConfig classes.

Your namespace is defined by the namespace property in your module's build.gradle.kts file, as shown in the following code snippet. The namespace is initially set to the package name you choose when you create your project.

android {
    namespace = "com.example.myapp"
    ...
}

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, which is used to access your app resources. For example, in the preceding build file, the R class is created at com.example.myapp.R.

The name you set for the build.gradle.kts file's namespace property should always match your project's base package name, where you keep your activities and other app code. 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, keep your namespace the same as your application ID, as they are by default.

Change the namespace

In most cases, you should 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, change the namespace by updating the namespace property in your module's build.gradle.kts 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, 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, the package attribute is set to the application ID. The merged manifest's package attribute is where the 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"
    ...
}

android {
    namespace "com.example.myapp"
    testNamespace "com.example.mytestapp"
    ...
}

Caution: Don't set testNamespace and namespace to the same value, otherwise namespace collisions occur.

To learn more about testing, see Test apps on Android.