Building ARDK Apps for Android

Use the following steps to build and deploy your ARDK app to Android devices.

Note

If you are planning to submit your app to the Google Play Store, your app must meet Google Play’s target API level requirement, which is currently API level 31. Building ARDK apps for API level 31 using Unity 2021 requires installing and configuring a newer version of gradle, as described in Building for Android API level 31 with OpenCL.

Prerequisites

You should have a Unity project configured with the ARDK package, as described in Adding ARDK to Unity.

Your Unity project should have an Authentication asset configured with your API key, as described in Authentication.

You should have an Android device compatible with ARDK. See “Runtime Requirements” in System Requirements for a list of compatible Android devices and minimum Android versions.

Your Unity scene should be configured to request Android permissions such as camera and location permissions, as described in Permissions.

Steps

  1. Open the External Tools window (Unity> Preferences) to specify your Android SDK and NDK paths. It is recommended to select the Use embedded JDK option.

../../_images/ExternalTools.png
  1. Access the Build Settings (menu: File > Build Settings) and open Player Settings.

../../_images/BuildMenu.png

Change the Company Name to your organization’s name. Then navigate to the Android> Other Settings pane to specify your build settings.

../../_images/BuildSettings.png

Under the Rendering section, uncheck the Auto Graphics API setting, and remove the Vulkan renderer if it is present. ARCore and Vulkan will not work together.

../../_images/AndroidGraphics.png

For Scripting Backend choose IL2CPP. Choosing Mono may cause crash issues when using awareness features.

For Target Architectures select both ARMv7 and ARM64. Note that ARCore does not support running 32-bit only apps on some 64-bit devices.

../../_images/AndroidScriptSettings.png

Some other settings and their effects on your application:

Setting

Value

Function

Multithreaded Rendering

Enable this option to use multithreaded rendering. Both enabling and disabling this option is supported by ARDK.

Package Name

Set the application ID, which uniquely identifies your app on the device and in the Google Play Store.

Minimum API Level

Android 5.1 ‘Lollipop’ (API level 22)

Minimum Android version (API level) required to run the application. In Unity 2020 this value is Android 5.0.

Target API level

Automatic (highest installed)

Target Android version (API level) against which to compile the application. For API level 30 and higher see notes below.

Note

If your target API level is set to API level 30 or higher, after you complete these build configuration steps, you will need to add a custom AndroidManifest.xml file to your Unity project configured with ARCore, as described in Building for Android 11 (API level 30) and higher.

If your target API level is set to API level 31 or higher, after you complete these build configuration steps, you will need to update the version of gradle that Unity uses to build, as described in Building for Android API level 31 with OpenCL.

  1. Back in the Build Settings window, the Example/StarterScene should be automatically added and checked inside the Scenes In Build box. If it is not checked, find the scene in the Unity Project window and drag it into the box.

../../_images/Scenes.png
  1. Connect your Android device to your computer, and click the Build and Run button. Save the build to your desired location and click Save. The app should automatically open on your phone after a short time.

../../_images/BuildAndRun.png

Building for Android 11 (API level 30) and higher

In Android 11, Google enforced a limit on what you can query about other apps on the device. Now you can only query for the existence of apps you specifically referenced in your manifest. This breaks ARDK as it doesn’t include this new manifest tag. This new security policy is only applied to apps built targeting API level 30 or above.

You’ll need to provide a custom AndroidManifest.xml that adds the query tag for ARCore by doing the following:

  • Add a custom AndroidManifest.xml to your Unity project. Configure your project to generate a manifest file by navigating to File > Build Settings. Open Player Settings, find the Publishing Settings section, and enable Custom Main Manifest.

../../_images/ManifestSetting.png

This will create a AndroidManifest.xml in your project’s Assets/Plugins/Android folder.

  • Edit the custom AndroidManifest.xml and add a <queries> <package android:name="com.google.ar.core" /> </queries> section. Your AndroidManifest.xml might look something like:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.unity3d.player" xmlns:tools="http://schemas.android.com/tools">
  <application>

    ...various activity, intent, meta-data tags...

  </application>

  ...various uses-feature and uses-permission tags...

  <queries>
    <package android:name="com.google.ar.core" />
  </queries>
</manifest>
  • Build your project with the new custom AndroidManifest.xml.

Building for Android API level 31 with OpenCL

Starting in Android API 31, Android by default blocks usage to using system shared libraries unless the libraries are specified in the application’s manifest. ARDK needs access to the system OpenCL library for various features. If OpenCL is not available, ARDK falls back to using OpenGL, which results in worse performance. Niantic has determined that the performance difference can be up to 2x slower on certain devices.

ARDK enables OpenCL in the app manifest, but this additionally requires gradle 6.7.1 or better to properly build. The default version of gradle that comes with Unity 2021 is 6.1.1, which does not support the <uses-native-library> field in your manifest necessary to enable OpenCL. Use the following steps to configure your build to enable OpenCL when using Unity 2021 or earlier.

  1. Install gradle 6.7.1 or better from https://gradle.org/releases/

  2. In Unity, under Preferences, External Tools, Android, disable using the default gradle that comes with Unity and replace with the path to your locally installed gradle 6.7.1.

../../_images/BuildSettingsCustomGradle.png

If you’re building using the command line and not through the Unity UI, you can set a custom gradle path by setting the AndroidExternalToolsSettings.gradlePath in your Unity build script.

AndroidExternalToolsSettings.gradlePath = path-to-downloaded-gradle
  1. In Unity, under Build Settings, click Player Settings. Then, under Publishing Settings enable Custom Base Gradle Template.

../../_images/PublishSettingsCustomBaseGradle.png

This should generate a template file in Assets/Plugins/Android/baseProjectTemplate.gradle.

  1. Modify the generated baseProjectTemplate.gradle file to force 4.2.0 (or newer) for the gradle plugin version.

allprojects {
    buildscript {
        repositories {**ARTIFACTORYREPOSITORY**
            google()
            jcenter()
        }

        dependencies {
            // If you are changing the Android Gradle Plugin version, make sure it is compatible with the Gradle version preinstalled with Unity
            // See which Gradle version is preinstalled with Unity here https://docs.unity3d.com/Manual/android-gradle-overview.html
            // See official Gradle and Android Gradle Plugin compatibility table here https://developer.android.com/studio/releases/gradle-plugin#updating-gradle
            // To specify a custom Gradle version in Unity, go do "Preferences > External Tools", uncheck "Gradle Installed with Unity (recommended)" and specify a path to a custom Gradle version
            classpath 'com.android.tools.build:gradle:4.2.0'
            **BUILD_SCRIPT_DEPS**
        }
    }

    repositories {**ARTIFACTORYREPOSITORY**
        google()
        jcenter()
        flatDir {
            dirs "${project(':unityLibrary').projectDir}/libs"
        }
    }
}
  1. Build your Android app and verify as usual.