Android 앱에서 EasyAR 기능 활성화

이 장에서는 Unity와 같은 3D 엔진 없이 Android Studio에서 EasyAR의 Android 프로젝트를 구성하는 방법을 설명합니다.

준비 작업

시작하기 전에 다음을 준비해야 합니다:

최신 버전의 Android Studio
JDK 8/11/17
Android Gradle Plugin 4.0 이상
Android NDK r28 이상
EasyAR 라이선스 키 획득
EasyAR Sense 릴리스 버전 선택 및 다운로드

참고

모든 Android 기기가 EasyAR Sense의 모든 기능을 지원하는 것은 아니며, 일부 기능은 추가 하드웨어 또는 구성이 필요합니다. 자세한 내용은 해당 기능의 지원 기기 목록을 참조하십시오.

Android용 EasyAR Sense 가져오기

이 섹션에서는 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 플랫폼에서는 시스템 버전 및 사용하는 기능에 따라 다음과 같은 구성과 제한 사항을 주의해야 할 수 있습니다.

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>

ProGuard 구성

Java 코드에 난독화를 활성화하는 경우 cn.easyar 네임스페이스를 제외해야 합니다.

EasyAR Sense는 런타임에 JNI를 통해 클래스 이름 리플렉션으로 Java 타입을 가져옵니다. cn.easyar 하위 클래스가 난독화되거나 이름이 변경되면 정의되지 않은 동작이 발생할 수 있습니다.

기본 규칙

-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 규칙은 EasyAR의 aar 라이브러리에 이미 포함되어 있어 일반적으로 중복 구성이 필요 없습니다.

스코프 저장소(Scoped Storage)

Android 10부터 도입된 스코프 저장소(Scoped Storage) 메커니즘은 파일 경로에 의존하는 일부 API에 영향을 미칩니다. 이는 /sdcard 하위의 비미디어 경로(예: 사용자 정의 디렉터리)가 Android 10에서 직접 접근 불가능해지기 때문입니다. EasyAR에 미치는 영향은 파일 경로를 전달해야 하는 일부 API(예: 화면 녹화)에서 나타나며, Android 10에서는 미디어 경로를 직접 읽고 쓸 수 없지만 Android 11에서는 정상 작동합니다.

해결 방법:

간편한 방법(Android 10) AndroidManifest.xml에서 스코프 저장소 비활성화:

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

권장 방법
- 애플리케이션 내부 저장소만 사용
- 또는 MediaStore를 통해 미디어 경로와 데이터 교환

Android Gradle 플러그인과 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 빌드가 실패할 수 있습니다.