Table of Contents

Enable EasyAR Features in Android Apps

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

Preparation

Before you begin, you need to prepare:

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

Not all Android devices support all features of EasyAR Sense. Some features require additional hardware or configurations. Refer to the device compatibility lists for specific features.

Import EasyAR Sense for Android

This section explains how to import the EasyAR Sense SDK into a non-Unity Android project. EasyAR Sense provides Java and C++ APIs and supports Kotlin, allowing you to develop in your preferred language.

Since configurations may vary across IDEs, this guide focuses on typical configurations for Android Studio + Gradle.

Selecting API usage approach

EasyAR Sense for Android provides two API usage approaches:

  • Using Java API only
  • Using Java and C++ API

Choose one configuration approach based on project requirements.

Use Java API only

When only using EasyAR's Java API, no NDK configuration is required.

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

Using Java and C++ API

When you need to use EasyAR's C++ API alongside Java, you need to configure both Java dependencies and native libraries.

  • 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 by 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, you need to enable Native Build in Gradle. Only the Java API requires no configuration. You can use ndk-build (Android.mk) for configuration.

Add the following in app/build.gradle:

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

If using CMake, refer to the 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 to run, and OpenGL ES 3.0 (GLESv3) is recommended.

Specify ABI architecture

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

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

If only one architecture is needed, keep only 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 to initialize when the application starts.

Example (Java):

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

Initialization must be completed before using EasyAR-related functions.

Additional configurations

On the Android platform, depending on the system version and the features used, additional configurations and limitations may apply.

Configure using ARCore

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

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

System.loadLibrary("arcore_sdk_c");
Note

When using ARCore versions before v1.19.0, it will not be detected on Android 11. This is due to the introduction of app visibility restrictions in Android 11, which require declaring the ARCore package name in AndroidManifest.xml.

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

Configure obfuscation (ProGuard)

If you enable obfuscation for Java code, you need to exclude the cn.easyar namespace.

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 the EasyAR aar library and usually do not need to be configured repeatedly.

Scoped storage

Starting with Android 10, the Scoped Storage mechanism has been introduced, which affects some file-path-dependent APIs. This is because non-media paths (such as custom directories) under /sdcard cannot be directly accessed on Android 10. The impact on EasyAR is reflected in some APIs that require file paths (such as screen recording) not supporting direct read/write operations on media paths on Android 10, but they work normally on Android 11.

Solutions:

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

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

  • Recommended solution

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

Android Gradle plugin and NDK

Since NDK r22, the default linker has been switched to LLD, which requires llvm-strip to work properly; this is incompatible with the built-in strip tool in Android Gradle Plugin versions below 4.0.
Solutions:

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

Windows path length limit

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

Solutions:

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

Further reading