Unity Native: Android Library Project

By Artem Glotov

As mentioned in our previous article, you can import an Android Library project (.androidlib) into your Unity project. The Unity documentation* on this feature is limited. In this article, we will explore the most convenient methods and strategies to accomplish this, aiming to avoid common issues for streamlined development and maintenance.

What you need to know:

• Unity doesn’t work with Kotlin DSL** (build.gradle.kts files). Kotlin DSL support began with Android Gradle Plugin (AGP) 4.0 and is the default from AGP 8.1 onwards (as of 2023, Kotlin DSL is not supported in any version of Unity). This means that you can use only Groovy DSL (build.gradle files) in your Android Library project.
• Unity requires the existence of an AndroidManifest.xml file with a specified package name in the .androidlib folder, even though modern Android libraries permit its absence if the namespace is specified in the build.gradle file. Namespace support began with AGP 7.0 and is mandatory from AGP 8.0 onwards** (namespace is supported starting from Unity 2022.3).

Even though Unity won’t include .androidlib assets in builds for non-Android platforms, particularly if they’re in platform-specific paths like Assets/Plugins/Android/ or Packages/../Plugins/Android, it’s still good practice to set platform-specific import settings. This ensures assets are only used where intended and can prevent confusion for other developers or when revisiting the project later.

Structure

Unity supports the following Android Library project structures:

1. Without build.gradle file

This structure is the minimal working configuration supported by Unity, where Unity generates the build.gradle file. The AndroidManifest.xml file should be placed at the top level, as the generated build.gradle file will search for it there.

In Unity 2020.3, a project.properties file is required for Unity to generate a build.gradle file at build time. From Unity 2021.3 onwards, this file is not required.

without-gradle-file.androidlib
├── src
│   └── main
│       └── java
│           └── ... kotlin/java source files
├── AndroidManifest.xml
└── project.properties (required for Unity 2020)

project.properties structure

This file contains info required for generating a build.gradle file.

• target – specifies the API level to use for targetSdkVersion
• android.library – specifies that this is an Android Library project; if set to false, Unity will ignore the .androidlib during the build.

target=android-33
android.library=true

2. With build.gradle file (recommended)

This structure is used if you created an Android Library module using Android Studio or need a custom build.gradle file (for example, to specify Android dependencies). You will also receive this structure when creating an Android module as described in the section below.

with-gradle-file.androidlib
├── src
│   └── main
│       ├── java
│       │   └── ... kotlin/java source files
│       └── AndroidManifest.xml
└── build.gradle

How to develop and maintain

This solution is suitable for personal studio use. If you plan to share the plugin with multiple studios, I recommend creating a separate Android repository, developing native plugins, and then publishing to Maven.

1. Create an Android Studio Project

Create an Android Studio project near your Unity project.

• Set the package name for it. We will use com.sample.android
• The minimum supported Android version should be the same as in your Unity project (you can check it in Edit > Project Settings > Android Settings > Other Settings > Minimum API Level). We will use 21
• You can use any DSL you want for the project (not for the module!) (Kotlin or Groovy). We will use Kotlin DSL

For Unity 2022.3 and newer versions that work with modern Gradle versions, it’s very important to make sure the Gradle and Android Gradle Plugin (AGP) versions match in both the Android Studio project and the Unity project.

For Unity 2021.3 and earlier versions, you’ll see big changes in the Gradle file setup needed by Android Studio projects and Unity projects. In this case, you should:

• Update Gradle and Android Gradle Plugin (AGP) in the Android Studio project. Choose a version with the API that works well with both projects
• Change the module’s build.gradle file to use the new API

In this example, we’re dealing with a more complex situation using Unity 2020.3. Here’s what we do:

• In the project’s Gradle file, we change the AGP (Android Gradle Plugin) version to 7.3.1
• We also update the Gradle version to 7.6

These versions don’t require a namespace in the build.gradle file, but they do allow for a newer, more modern setup in Gradle. Also, it’s worth noting that Unity 2023.3 uses the same version setup (as shown in the table at the start of the article), which will be useful in future migrations to newer Unity versions.

Update AGP version

Replace com.android.application with com.android.library in the plugins block of the project’s Gradle file.

The former is utilized for Android applications, while the latter is for Android libraries. The version designated for this plugin will also serve as the AGP version. (You will need to do this for all versions of Unity.)

// Top-level build file where you can add configuration options common to all sub-projects/modules.
plugins {
    id("com.android.library") version "7.3.1" apply false
    id("org.jetbrains.kotlin.android") version "1.6.20" apply false
}

Update Gradle version

Use CLI:

./gradlew wrapper --gradle-version=7.6

2. Create Android Library Module

Create an Android Library module** in Android Studio.

• Use the AndroidManifest.xml file with the package attribute specified. Unity requires it.

  <?xml version="1.0" encoding="utf-8"?>
  <manifest package="com.sample.android">
  </manifest>

• Use Groovy DSL for the module configuration file
• Use your preferred language (Kotlin or Java). We will use Kotlin

Update Gradle’s Module File

For Unity 2021.3 and earlier versions, you also need to update the module’s build.gradle file to use the Gradle API supported by both environments, Unity project and Android Studio project, as mentioned earlier.

plugins {
    id 'com.android.library'
    id 'org.jetbrains.kotlin.android' // This plugin is required for Kotlin
}

android {
    compileSdkVersion 33

    defaultConfig {
        minSdkVersion 21

        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
        consumerProguardFiles "consumer-rules.pro"
    }

    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    kotlinOptions {
        jvmTarget = '1.8'
    }
}

Remove Unused Files

Remove the app module automatically created earlier by Android Studio since you don’t need it:

1. Delete the include(":app") line from the settings.gradle.kts file
2. Sync the project with Gradle files.
3. Remove the app folder from the project view

You can also remove the following from the newly created androidsample module:

• The androidTest and test folders, as well as the lines with testImplementation, androidTestImplementation and testInstrumentationRunner in the module’s build.gradle file, if you don’t need to write tests for your module
• The consumer-rules.pro and proguard-rules.pro files and any lines referencing them in the module’s build.gradle file, if you don’t intend to shrink or obfuscate** your code

3. Move Android Library Module to Unity Project

• Move the Android Library module folder to the Unity project. You can use Assets/Plugins/Android or the Pacakges/YourPackage/Plugins/Android folder for this
• Add the .androidlib extension to the module folder name (we will use androidsample.androidlib).

4. Reference External Module in Android Studio Project

Add a reference to the relocated module in the project settings.gradle.kts file in Android Studio, using the relative path from settings.gradle.kts to the new module destination.

include(":androidsample")
project(":androidsample").projectDir = File("../Packages/Native.Sample.Android/Plugins/Android/androidsample.androidlib")

5. (Only Kotlin) Add the Kotlin Gradle Plugin to a Unity Project

Add the Kotlin Gradle plugin (KGP) (org.jetbrains.kotlin:kotlin-gradle-plugin) to the dependencies block in baseProjectTemplate.gradle to support Kotlin in your Unity project. The version of the Kotlin plugin depends on the Unity version. See details in the table below.
Unity 2020, 2021:

allprojects {
    buildscript {
        // other configurations...

        dependencies {
            classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.6.20"
        }
    }
}

Unity 2022, 2023:

plugins {
    // other configurations...
    id "org.jetbrains.kotlin.jvm" version "1.9.20"
}

According to KGP*** and Unity Gradle* documentation, here are the relationships between the Unity versions and compatible Kotlin Gradle plugin versions:

Summary

Now you know how to create an Android Library module inside your Unity project, and how to link the Android Studio project to it. This setup enables you to:

• Work on the module in Android Studio, using its features like syntax highlighting
• Automatically update the Unity project with any changes, without needing to copy and paste manually

(*) Content in this article is sourced from Unity’s Documentation. Copyright © 2024 Unity Technologies. Publication Date: 2024-02-05.

(**) Content in this article is sourced from Android’s Documentation. Copyright © 2024 Google LLC.

(***) Content in this article is sourced from Kotlin’s Documentation. Copyright © 2024 JetBrains s.r.o.

Tags