Version: 2021.1
Customizing an Android Splash Screen
Android Manifest

Gradle for Android

Gradle is an Android build system that automates a number of build processes and prevents many common build errors. In Unity, Gradle reduces the method reference count in DEX (Dalvik Executable format) files, which means you are less likely to come across DEX limit problems.

Unity uses Gradle for all Android builds. You can either build the output package (.apk, .aab) in Unity, or export a Gradle project from Unity, and then build it with an external tool such as Android Studio.

Unity version Gradle version
2020.3 starting from 2020.3.15f1
2021.1 starting from 2021.1.16f1
6.1.1
2020.1, 2020.2, 2020.3 up to and including 2020.3.14f1
2021.1 up to and including 2021.1.15f1
5.6.4
2019.4 5.1.1

To learn more about:

Building or exporting a Gradle project

To build a Gradle project, follow these steps:

  1. In the Unity Editor, open the Build Settings for your Project (menu: File > Build Settings).
  2. In the Platform list, make sure that Android is selected as the Build target. If Android isn’t the current Build target, select it in the Platform list, then select the Switch Platform button.
Build settings for Android
Build settings for Android

Select the:

  • Build button to generate an .apkThe Android Package format output by Unity. An APK is automatically deployed to your device when you select File > Build & Run. More info
    See in Glossary
    file.
  • Build and Run button to generate an .apk file, deploy it to a connected device, and run it.

To export your Unity Project as a Gradle project, enable the Export Project setting, and then select the Export button. When you do this, Unity generates a Gradle project in the folder you specify, and doesn’t build an .apk file. Import this project into Android Studio or another external tool to make further changes, or to build it from there.

Exported Gradle project structure

Unity 2019.3 and newer versions create a Gradle project with two modules:

  • UnityLibrary module: Contains the Unity runtime and project data. This module is a library that you can integrate into any other Gradle project. You can use it to embed Unity into existing Android applications.
  • Launcher module: Contains the application’s name and all of its icons. This is a simple Android application module that launches Unity. You can replace it with your own application.
Build settings for Android
Build settings for Android

build.gradle templates

Gradle templates describe and configure how to build your Android app with Gradle. Each Gradle template represents a singleGradle project. Gradle projects can include, and depend on other Gradle projects.

A Gradle template consists of the following files:

File Location Contains
baseProjectTemplate.gradle In the exported project, root/build.gradle folder Contains configuration that is shared between all other templates/Gradle projects (repositories and the dependency on the Android Gradle plug-in).
launcherTemplate.gradle_ In the exported project, root/launcher/build.gradle folder Contains instructions on how to build the Android application (bundling, signing, APK splitting). It depends on the unityLibrary project and outputs either an .apk file or an app bundle.
mainTemplate.gradle In the exported project, root/unityLibrary/build.gradle folder Contains instructions on how to build Unity as a Library. Outputs an .aar file. You can override the Unity template with a custom template in the Unity Editor. See the Providing a custom Gradle build template section on this page for more details.
libTemplate.gradle Varies Used if your Unity Project contains Android Library Projects as plug-insA set of code created outside of Unity that creates functionality in Unity. There are two kinds of plug-ins you can use in Unity: Managed plug-ins (managed .NET assemblies created with tools like Visual Studio) and Native plug-ins (platform-specific native code libraries). More info
See in Glossary
.

Customizing your Gradle build

You can provide a custom Gradle build template and select minification options in the Publishing Settings section of the Player SettingsSettings that let you set various player-specific options for the final game built by Unity. More info
See in Glossary
window.

Gradle-specific settings in the Publishing Settings section of the Player settings window

Providing a custom Gradle build template

You can use a custom build.gradle file for the unityLibrary module when you build the APK from Unity. This file contains specific build instructions specified in template variables. For a list of template variables, see the next section.

To use your own build.gradle file for the unityLibrary module, follow these steps:

  1. In the Unity Editor, open the Player Settings window (menu: Edit > Project Settings > Player), and select Android.
  2. In the Publishing Settings section, enable the Custom Main Gradle Template setting.

Unity then generates a default mainTemplate.gradle file in your Project’s Assets/Plugins/Android/ folder. The path to the new file also appears under the Custom Main Gradle Template option in the Player Settings. Double-click the mainTemplate.gradle file in the Project view to open it in an external text editor.

mainTemplate.gradle file in the Project view for the unityLibrary module
mainTemplate.gradle file in the Project view for the unityLibrary module

By default, Unity uses the settingsTemplate.gradle file from the Unity install directory to create the settings.gradle file for your build. The settings.gradle file contains project components which are involved in the build process. Unity creates the following components by default, which should always be included in the settings.gradle file:

  • launcher
  • unityLibrary

Additionally, if you add Android library plugins to your project, Unity automatically includes them in the settings file by replacing the **INCLUDES** entry.

If you want to add additional components to the settings.gradle file that Unity doesn’t include by default, create a settingsTemplate.gradle file in your project’s Assets/Plugins/Android/ folder. This overrides the default template.

If you use your own settingsTemplate.gradle file, it must contain the following lines:

include ':launcher', ':unityLibrary'
**INCLUDES**

IPostGenerateGradleAndroidProject

IPostGenerateGradleAndroidProject returns the path to the unityLibrary module. This keeps everything similar to versions earlier than Unity 2019.3 and doesn’t require any further changes, which means Unity can reach the app’s manifest and resources in a consistent way across versions.

Template variables

The mainTemplate.gradle file can contain the following variables:

Variable: Description:
DEPS List of project dependenciesIn the context of the Package Manager, a dependency is a specific package version (expressed in the form package_name@package_version) that a project or another package requires in order to work. Projects and packages use the dependencies attribute in their manifests to define the set of packages they require. For projects, these are considered direct dependencies; for packages, these are indirect, or transitive, dependencies. More info
See in Glossary
; that is, the libraries that the Project uses.
APIVERSION API version to build for (for example, 25).
MINSDKVERSION Minimum API version (for example, 25).
BUILDTOOLS SDK Build tools used (for example, 25.0.1).
TARGETSDKVERSION API version to target (for example, 25).
APPLICATIONID Android Application ID (for example, com.mycompany.myapp).
MINIFY_DEBUG Enable minify for debug builds (true or false).
PROGUARD_DEBUG Use proguard for minification in debug builds (true or false.)
MINIFY_RELEASE Enable minify for release builds (true or false).
PROGUARD_RELEASE Use proguard for minification in release builds (true or false).
USER_PROGUARD Custom user proguard file (for example, proguard-user.txt).
SIGN Complete the signingConfigs section if this build is signed.
SIGNCONFIG Set to signingConfig signingConfig.release if this build is signed.
DIR_GRADLEPROJECT The directory where Unity creates the Gradle project.
DIR_UNITYPROJECT The directory of your Unity Project.

Minification

You can use Proguard minification to shrink and optimize your app. To activate this option, follow these steps:

  1. Open the Player Settings window (menu: Edit > Project Settings > Player), and select Android.
  2. In the Publishing Settings section, under Minify, select Proguard for either release builds, debug builds, or both.

Note: Proguard might strip out important code that your app needs, so use these options carefully.

To generate a custom proguard.txt file, enable the User Proguard File setting in the Publishing Settings section of the Player Settings. This immediately generates the proguard.txt file in your Project’s Assets/Plugins/Android/ folder.

To learn more about ProGuard, see the ProGuard manual.

Errors when building with Gradle

If an error occurs when you use Gradle to build your app for Android, Unity displays an error dialog box. Select the Troubleshoot button to open the Gradle troubleshooting Unity documentation in your system’s browser.


  • Unity as a Library for Android added in 2019.3.NewIn20193
Customizing an Android Splash Screen
Android Manifest