Table of Contents

Enable EasyAR features in an Android application

This chapter describes how to configure an Android project for EasyAR in Android Studio without using a 3D engine such as 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 later

  • Android NDK r28 or later

  • Obtain an EasyAR authorization license

  • Select an EasyAR Sense release version and download it

Note

Not all Android devices support all EasyAR Sense features. Some features depend on additional hardware or configuration. For details, refer to the device support list for the corresponding feature.

Import EasyAR Sense for Android

This section describes how to import EasyAR Sense SDK into an Android project that does not use Unity. EasyAR Sense provides Java and C++ APIs and supports Kotlin, so you can develop with the language you are most comfortable with.

Because configuration methods may differ between IDEs, this section only describes the typical configuration method based on Android Studio + Gradle.

Choose the API usage method

EasyAR Sense for Android provides two API usage methods:

  • Use only the Java API
  • Use the Java and C++ APIs

Choose one of them for configuration according to your project requirements.

Use only the Java API

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

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

Use the Java and C++ APIs

When you need to use EasyAR's C++ API at the same time, you must configure both Java dependencies and native libraries.

  • Java layer files

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

  • Native libraries (.so)

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

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

  • C++ header files

    Copy the easyar folder under the include directory in EasyAR SDK to the following path, or to 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 notes

When you use the C++ API, you need to enable Native Build in Gradle. If you only use the Java API, no configuration is required. You can configure it with ndk-build (Android.mk).

Add the following to app/build.gradle:

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

If you use CMake, refer to the official Google documentation for configuration.

NDK configuration

Declare EasyAR as a prebuilt library

include $(CLEAR_VARS)

# Make sure 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 at runtime. OpenGL ES 3.0 (GLESv3) is recommended.

Specify ABI architectures

Explicitly specify 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 permissions 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 when the application starts to initialize EasyAR.

Example (Java):

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

Initialization must be completed before using EasyAR-related features.

Extra configuration

On the Android platform, depending on the system version and the features used, you may also need to pay attention to the following configurations and restrictions.

Configure ARCore usage

If your project uses ARCore, refer to its official documentation to complete the related configuration of AndroidManifest.xml and build.gradle.

In addition, before initializing EasyAR, you must explicitly load the ARCore native library:

System.loadLibrary("arcore_sdk_c");
Note

When using versions earlier than ARCore v1.19.0, ARCore cannot be detected on Android 11. This is because Android 11 introduced app visibility restrictions, and the ARCore package name needs to be declared in AndroidManifest.xml.

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

Configure obfuscation (ProGuard)

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

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

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 ProGuard rules above are already included in EasyAR's aar library, so repeated configuration is usually not required.

Scoped Storage

The Scoped Storage mechanism introduced in Android 10 affects some APIs that depend on file paths. This is because non-media paths under /sdcard, such as custom directories, cannot be accessed directly on Android 10. The impact on EasyAR is that some APIs requiring file paths, such as screen recording, do not support directly reading and writing media paths on Android 10, but 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 app internal storage
    • Or exchange data with media paths through MediaStore

Android Gradle Plugin and NDK

Starting from NDK r22, the LLD linker is used by default and needs to work with llvm-strip; this is incompatible with the built-in strip tool in Android Gradle Plugin versions earlier than 4.0. Solutions:

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

Windows path length limit

On Windows, if the absolute path length of any file in the project, including temporary files generated during build, exceeds 260 characters, Android Studio build may fail.

Solutions:

  • Place the project under a shorter path, such as C:\user\project
  • Avoid overly deep directory levels

Further reading