Table of Contents

Enable EasyAR in Android applications

This chapter describes how to configure an EasyAR Android project in Android Studio without using 3D engines like Unity.

Preparations

Before starting, you need to prepare:

  • Latest version of Android Studio
  • JDK 8/11/17
  • Android Gradle Plugin 4.0 or above
  • Android NDK r28 or above
  • Obtain an EasyAR license key
  • Select EasyAR Sense release version and download
Note

Not all Android devices support all features of EasyAR Sense. Some features require additional hardware or configuration. Please refer to the device compatibility list for specific features.

Import EasyAR Sense for Android

This section describes how to import EasyAR Sense SDK in non-Unity Android projects. EasyAR Sense provides both Java and C++ APIs, and supports Kotlin, allowing development in your preferred language.

Since configuration methods may vary across IDEs, this guide focuses on typical configuration using Android Studio + Gradle.

Choose API usage

EasyAR Sense for Android provides two ways to use the API:

  • Only use Java API
  • Use Java and C++ API

Please choose one of them to configure according to your project requirements.

Only use Java API

When only using EasyAR's Java API, no need to configure NDK.

Place EasyAR.aar in app/libs/ or the directory specified by Gradle.

Use Java and C++ API

When needing to use EasyAR's C++ API simultaneously, both Java dependencies and native libraries need to be configured.

  • Java layer files

    Place EasyAR.jar in app/libs/ or the path specified by Gradle.

  • Native libraries (.so)

    Place the native libraries provided by EasyAR under the following path or the path specified by Gradle, organized by ABI.

    app/src/main/jniLibs/
├── armeabi-v7a/
│   └── libEasyAR.so
└── arm64-v8a/
    └── libEasyAR.so

  • C++ header files

    Copy the easyar folder from the include directory in the EasyAR SDK to the following path or the path specified in Android.mk/CMakeLists.txt.

    app/src/main/jni/easyar/

    The header file path must be explicitly specified in Android.mk or CMakeLists.txt.

Gradle configuration instructions

When using the C++ API, Native Build needs to be enabled in Gradle. Only applicable to Java API without configuration. You can configure using ndk-build (Android.mk).

Add in app/build.gradle:

android {
    externalNativeBuild {
        ndkBuild {
            path "src/main/jni/Android.mk"
        }
    }
}

If using CMake, please refer to Google official documentation for configuration.

NDK configuration

Declare EasyAR as a prebuilt library

include $(CLEAR_VARS)

# Ensure this path points to the current ABI directory in jniLibs
LOCAL_PATH := $(LOCAL_PATH_TOP)/../jniLibs/$(TARGET_ARCH_ABI)

LOCAL_MODULE := EasyAR
LOCAL_SRC_FILES := libEasyAR.so

include $(PREBUILT_SHARED_LIBRARY)

LOCAL_SHARED_LIBRARIES += EasyAR

# OpenGL ES (required)
LOCAL_LDLIBS += -lGLESv3

EasyAR requires at least OpenGL ES 2.0. OpenGL ES 3.0 (GLESv3) is recommended.

Specify ABI architecture

Explicitly specify ABIs in app/build.gradle to avoid packaging invalid architectures:

android {
    defaultConfig {
        ndk {
            abiFilters "armeabi-v7a", "arm64-v8a"
        }
    }
}

If only one architecture is needed, only keep the corresponding item.

AndroidManifest permission configuration

EasyAR Sense requires the following permissions. Missing them will cause initialization failure or a black screen:

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.INTERNET" />

Complete example:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="cn.easyar.samples.helloar">

    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.INTERNET" />

</manifest>

Initialize EasyAR

Call Engine.initialize during application startup for initialization.

Example (Java):

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Engine.initialize(this, key);
}
Note

Initialization must be completed before using any EasyAR related functions.

Additional configurations

On the Android platform, depending on the OS version and features used, the following configurations and limitations may also require attention.

Configuring arcore usage

If ARCore is used in the project, refer to its official documentation to complete the relevant configuration in AndroidManifest.xml and build.gradle.

Additionally, before initializing EasyAR, the native library of ARCore must be explicitly loaded:

System.loadLibrary("arcore_sdk_c");
Note

When using ARCore versions prior to v1.19.0, it will not be detectable on Android 11. This is due to the app visibility restrictions introduced in Android 11, requiring the declaration of the ARCore package name in AndroidManifest.xml.

<queries>
    <package android:name="com.google.ar.core" />
    
</queries>

Configuring proguard

If code obfuscation is enabled for Java code, the namespace cn.easyar must be excluded.

EasyAR Sense uses class name reflection to obtain Java types via JNI at runtime. If classes under cn.easyar are obfuscated or renamed, it may lead to undefined behavior.

Basic rules

-keep class cn.easyar.** { *; }

-dontwarn javax.annotation.Nonnull
-dontwarn javax.annotation.Nullable
-keepattributes *Annotation*

-keep class cn.easyar.RefBase { native <methods>; }
-keepclassmembers class cn.easyar.* {
    <fields>;
    protected <init>(long, cn.easyar.RefBase);
}
-keep,allowobfuscation interface cn.easyar.FunctorOf* { *; }

-keep class cn.easyar.Buffer { native <methods>; }
-keep class cn.easyar.Engine { native <methods>; }
-keep class cn.easyar.JniUtility { native <methods>; }

-keep class cn.easyar.engine.** { *; }
-keep class cn.easyar.CameraParameters
-keep interface cn.easyar.FunctorOfVoidFromInputFrame

The above ProGuard rules are already included in EasyAR's aar library and typically do not require reconfiguration.

Scoped storage

The Scoped Storage mechanism introduced in Android 10 affects some file path-dependent APIs. This is because non-media paths under /sdcard (such as custom directories) cannot be directly accessed on Android 10. The impact on EasyAR is that some APIs requiring file paths (e.g., screen recording) do not support direct read/write to media paths on Android 10, but work normally on Android 11.

Solution:

  • Simple solution (Android 10) Disable Scoped Storage in AndroidManifest.xml:

    <application
    android:requestLegacyExternalStorage="true"
    ... >
</application>

  • Recommended solution

    • Use only internal app storage
    • Or exchange data with media paths via MediaStore

Android gradle plugin and NDK

Since NDK r22, the LLD linker is used by default and requires llvm-strip; this is incompatible with the built-in strip tool in Android Gradle Plugin versions below 4.0. Solution:

  • Upgrade to Android Gradle Plugin 4.0 or higher
  • Or use doNotStrip in packagingOptions to disable stripping (not recommended)

Windows path length limitation

On Windows systems, if the absolute path length of any file (including temporary files generated during the build process) exceeds 260 characters, it may cause Android Studio build failures.

Solution:

  • Place the project in a shorter path (e.g., C:\user\project)
  • Avoid excessively deep directory hierarchies

Further reading