配置EasyAR Sense for Android¶

这篇文章介绍如何使用EasyAR package配置EasyAR非Unity的Android工程。

如果你需要运行EasyAR非Unity的Android样例，请阅读这篇文章。

安装需求¶

JDK 1.8
Android SDK Build Tools 至少需要版本30.0.3
Android NDK r22

推荐安装最新版本的NDK和SDK

你可以在Eclipse或Android Studio中使用EasyAR。

注意：EasyAR Sense有Java和C++ API，并支持Kotlin，你可以使用最习惯的语言进行开发。

导入EasyAR Sense for Android¶

使用不同IDE的配置细节可能会有所不同。这里我们只介绍使用gradle和Android Studio 2.2或更新版本的配置方式。

只使用 Java API

将 EasyAR.aar 放入 app/libs 或由gradle配置显示指定的目录。

使用 Java 和 C++ API

将 EasyAR.jar 放入 app/libs 或由gradle配置显示指定的目录。
将 armeabi-v7a 和/或 arm64-v8a 放入 app/src/main/jniLibs 或由gradle配置显示指定的目录。
将 include 中的 easyar 文件夹放入 app/src/main/jni 或由Android.mk 或者 CMakeLists.txt中显示指定的目录。

有关arm64-v8a的支持，可以阅读关于 Android arm64-v8a 。

Gradle Configuration for EasyAR Sense -- Java API¶

无需特别设置。

Gradle Configuration for EasyAR Sense -- C++ API¶

可以参考 Google 官方文档获取更多信息。

Makefile / CMakeLists¶

这里我们只描述如何配置 Android.mk，如果你偏向于 CMake，可以参考 Google 官方文档。

prebuilt library

include $(CLEAR_VARS)
# make sure this path is avaliable for libEasyAR.so
LOCAL_PATH := $(LOCAL_PATH_TOP)/../jniLibs/$(TARGET_ARCH_ABI)
LOCAL_MODULE := EasyAR
LOCAL_SRC_FILES := libEasyAR.so
include $(PREBUILT_SHARED_LIBRARY)

link libEasyAR.so

GLESv2 是必须加入的。

LOCAL_LDLIBS += -lGLESv2
LOCAL_SHARED_LIBRARIES += EasyAR

External Native Build¶

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

如果你偏向于 CMake，可以参考 Google 官方文档.

指定 ABIs¶

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

如果只需要armeabi-v7a或arm64-v8a，可以在上面只保留其中一个。

注意：从2019年8月1日开始，Google Play Store不支持带有armeabi-v7a而不带有arm64-v8a的应用提交。(Support 64-bit architectures)

在AndroidManifest中添加权限¶

EasyAR需要以下这些权限，缺少权限将会导致初始化失败并黑屏。

android.permission.CAMERA android.permission.INTERNET

将这些添加到AndroidManifest中。

<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>

初始化EasyAR¶

使用 cn.easyar.Engine.initialize 来初始化EasyAR。你可以添加初始化函数到你的activity中如下，

protected void onCreate() {
    Engine.initialize(this, key);
}

其它代码¶

剩下的就是写EasyAR的逻辑以及其它代码。你可以参考EasyAR的样例来实现。

Windows上文件夹路径长度260字符限制¶

在Windows上，如果工程中的任意文件（包括生成过程中的临时文件）的绝对路径超过了260字符，在Android Studio中都可能编译失败。此时应减少文件夹长度以绕过此问题。

ARCore¶

如果使用ARCore，请参考其官方文档以配置AndroidManifest和build.gradle。

此外，需要在初始化EasyAR之前。调用

System.loadLibrary("arcore_sdk_c");

使用ARCore v1.19.0之前的版本，在Android 11上将无法被检测到。这是因为Android 11限制了应用对已安装应用的可见性，需要在Android.manifest中声明。

<queries>
    <package android:name="com.google.ar.core" /> <!-- remove this line after updating to ARCore v1.19.0 or later -->
</queries>

混淆¶

如果需要对Java代码进行混淆，请排除cn.easyar命名空间。EasyAR Sense中会通过JNI使用类名获取Java类型，如果cn.easyar中的类被改名，将产生未定义行为。

如果使用ProGuard，可以添加

-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

此ProGuard规则已包含在aar库中。

Scoped Storage¶

Android 10和Android 11中的 Scoped Storage ，会对部分API的使用造成影响。

具体地说，外部路径/sdcard除媒体路径(如/sdcard/Movies)之外的路径无法访问。在Android 10上(而非Android 11上)，媒体路径只能通过 MediaStore 访问。

部分需要传入路径的API，如录屏，在Android 10上默认不支持读写媒体路径，但在Android 11上支持。

为了简便，可以在Android 10上使用android:requestLegacyExternalStorage="true"禁用scoped storage。或者只读取/写入内部存储，通过MediaStore与媒体路径进行交换。

Android Gradle plugin¶

NDK r22默认使用LLD链接器，需要与llvm-strip命令配合，与Android Gradle Plugin 4.0以下版本中自带的strip命令不兼容。

升级到Android Gradle Plugin 4.0，或者使用packagingOptions的doNotStrip选项禁用stripping。