在 Android 應用中啟用 EasyAR 功能

本章介紹如何在 Android Studio 中配置 EasyAR 的 Android 工程，無需使用 Unity 等 3D 引擎。

準備工作

開始之前，您需要準備：

最新版本的 Android Studio
JDK 8/11/17
Android Gradle Plugin 4.0 或以上
Android NDK r28 或以上
取得 EasyAR 授權許可證
選擇 EasyAR Sense 發佈版本並下載

附註

並非所有安卓裝置均支援 EasyAR Sense 的所有功能，部分功能依賴額外硬體或配置，具體可查閱對應功能支援的裝置列表。

導入 EasyAR Sense for Android

本節介紹如何在非 Unity 的 Android 工程中導入 EasyAR Sense SDK。 EasyAR Sense 提供 Java 和 C++ API，並支援 Kotlin，您可以使用最習慣的語言進行開發。

由於不同 IDE 的配置方式可能存在差異，這裡僅說明基於 Android Studio + Gradle 的典型配置方式。

選擇 API 使用方式

EasyAR Sense for Android 提供兩種 API 使用方式：

僅使用 Java API
使用 Java 和 C++ API

請根據專案需求選擇其中一種進行配置。

僅使用 Java API

當僅使用 EasyAR 的 Java API 時，無需配置 NDK。

將 EasyAR.aar 放入 app/libs/ 或 Gradle 指定目錄。

使用 Java 和 C++ API

當需要同時使用 EasyAR 的 C++ API 時，需要同時配置 Java 依賴與原生庫。

Java 層檔案

將 EasyAR.jar 放入 app/libs/ 或 Gradle 指定路徑。

原生庫（.so）

將 EasyAR 提供的原生庫按 ABI 放入以下路徑或 Gradle 指定路徑。

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

C++ 標頭檔

將 EasyAR SDK 中 include 目錄下的 easyar 資料夾拷貝到以下路徑或 Android.mk/CMakeLists.txt 指定路徑。
```
app/src/main/jni/easyar/
```
標頭檔路徑需在 Android.mk 或 CMakeLists.txt 中顯式指定。

Gradle 配置說明

當您使用 C++ API 時，需要在 Gradle 中啟用 Native Build, 僅適用 Java API 無需配置。您可以使用 ndk-build（Android.mk）進行配置。

在 app/build.gradle 中添加：

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

如果使用 CMake，請參考 Google 官方文件進行配置。

Ndk 配置

宣告 EasyAR 為預編譯庫

include $(CLEAR_VARS)

# 確保該路徑指向 jniLibs 中當前 ABI 目錄
LOCAL_PATH := $(LOCAL_PATH_TOP)/../jniLibs/$(TARGET_ARCH_ABI)

LOCAL_MODULE := EasyAR
LOCAL_SRC_FILES := libEasyAR.so

include $(PREBUILT_SHARED_LIBRARY)

連結 EasyAR 與系統庫

LOCAL_SHARED_LIBRARIES += EasyAR

# OpenGL ES（必需）
LOCAL_LDLIBS += -lGLESv3

EasyAR 運行至少需要 OpenGL ES 2.0，推薦使用 OpenGL ES 3.0（GLESv3）。

指定 ABI 架構

在 app/build.gradle 中顯式指定 ABI，避免無效架構被打包：

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

如果只需要其中一種架構，可只保留對應項。

AndroidManifest 權限配置

EasyAR Sense 需要以下權限，缺失將導致初始化失敗或黑屏：

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

完整範例：

<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

在應用啟動時呼叫 Engine.initialize 進行初始化。

範例（Java）：

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

附註

初始化必須在使用 EasyAR 相關功能之前完成。

額外配置

在 Android 平台上，根據系統版本及所使用的功能不同，可能還需要注意以下配置和限制。

Configure using ARCore

若專案中使用 ARCore，請參考其官方文件完成 AndroidManifest.xml 和 build.gradle 的相關設定。

此外，在初始化 EasyAR 之前，必須顯式載入 ARCore 的原生函式庫：

System.loadLibrary("arcore_sdk_c");

附註

使用 ARCore v1.19.0 之前版本時，在 Android 11 上將無法被偵測到。這是由於 Android 11 開始引入了應用程式可見性限制，需在 AndroidManifest.xml 中宣告 ARCore 封裝名稱。

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

Configure ProGuard

若啟用 Java 程式碼混淆，需排除 cn.easyar 命名空間。

EasyAR Sense 在執行時會透過 JNI 使用類別名稱反射取得 Java 型別。若 cn.easyar 下的類別被混淆或重新命名，可能導致未定義行為。

基本規則

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

Scoped Storage

Android 10 開始引入的 Scoped Storage（分區儲存） 機制，會對部分依賴檔案路徑的 API 造成影響。這是由於 /sdcard 下的非媒體路徑（如自訂目錄）在 Android 10 上無法直接存取所致。對 EasyAR 的影響體現在部分需傳入檔案路徑的 API（如螢幕錄製）在 Android 10 上，不支援直接讀寫媒體路徑，但在 Android 11 上可正常運作。

解決方式：

簡便方案（Android 10）在 AndroidManifest.xml 中停用 Scoped Storage：

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

推薦方案
- 僅使用應用程式內部儲存
- 或透過 MediaStore 與媒體路徑進行資料交換

Android Gradle Plugin and NDK

自 NDK r22 起，預設使用 LLD 連結器，並需配合 llvm-strip 使用；這與 Android Gradle Plugin 4.0 以下版本內建的 strip 工具不相容。 解決方式:

升級至 Android Gradle Plugin 4.0 或以上
或在 packagingOptions 中使用 doNotStrip 停用 stripping（不推薦）

Windows 路徑長度限制

在 Windows 系統上，若專案中任意檔案（包括建置過程中產生的暫存檔）的絕對路徑長度超過 260 個字元，可能導致 Android Studio 建置失敗。