Table of Contents

Android 애플리케이션에서 EasyAR 기능 활성화

이 장은 Unity 같은 3D engine을 사용하지 않고 Android Studio에서 EasyAR Android project를 구성하는 방법을 소개합니다.

준비 작업

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

참고

모든 Android 장치가 EasyAR Sense의 모든 기능을 지원하는 것은 아닙니다. 일부 기능은 추가 hardware 또는 구성에 의존합니다. 자세한 내용은 해당 기능이 지원하는 장치 목록을 참조하십시오.

EasyAR Sense for Android 가져오기

이 섹션은 Unity가 아닌 Android project에 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 의존성과 native library를 모두 구성해야 합니다.

  • Java 계층 파일

    EasyAR.jar를 app/libs/ 또는 Gradle에서 지정한 경로에 넣습니다.

  • Native library (.so)

    EasyAR가 제공하는 native library를 ABI에 따라 다음 경로 또는 Gradle에서 지정한 경로에 넣습니다.

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

  • C++ header file

    EasyAR SDK의 include 디렉터리 아래 easyar 폴더를 다음 경로 또는 Android.mk/CMakeLists.txt에서 지정한 경로로 복사합니다.

    app/src/main/jni/easyar/

    header file 경로는 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를 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)

EasyAR와 시스템 library 링크

LOCAL_SHARED_LIBRARIES += EasyAR

# OpenGL ES (required)
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의 native library를 명시적으로 로드해야 합니다.

System.loadLibrary("arcore_sdk_c");
참고

ARCore v1.19.0 이전 버전을 사용하는 경우 Android 11에서 감지할 수 없습니다. 이는 Android 11부터 app visibility 제한이 도입되어 AndroidManifest.xml에 ARCore package 이름을 선언해야 하기 때문입니다.

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

Obfuscation 구성(ProGuard)

Java 코드에 obfuscation을 활성화한 경우 cn.easyar namespace를 제외해야 합니다.

EasyAR Sense는 runtime에 JNI를 통해 class name reflection으로 Java types를 얻습니다. cn.easyar 아래 class가 obfuscated되거나 이름이 변경되면 undefined behavior가 발생할 수 있습니다.

기본 규칙

-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 library에 이미 포함되어 있으므로 일반적으로 중복 구성할 필요가 없습니다.

Scoped Storage

Android 10부터 도입된 Scoped Storage 메커니즘은 file paths에 의존하는 일부 API에 영향을 줍니다. 이는 /sdcard 아래의 non-media paths, 예를 들어 사용자 지정 디렉터리가 Android 10에서 직접 접근할 수 없기 때문입니다. EasyAR에 대한 영향은 screen recording처럼 file paths를 전달해야 하는 일부 API가 Android 10에서 media paths의 직접 읽기/쓰기를 지원하지 않지만 Android 11에서는 정상적으로 작동한다는 점입니다.

해결 방법:

  • 간단한 방법(Android 10) AndroidManifest.xml에서 Scoped Storage를 비활성화합니다.

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

  • 권장 방법

    • app internal storage만 사용
    • 또는 MediaStore를 통해 media paths와 데이터 교환

Android Gradle Plugin 및 NDK

NDK r22부터 기본적으로 LLD linker를 사용하며 llvm-strip과 함께 사용해야 합니다. 이는 Android Gradle Plugin 4.0 미만 버전에 내장된 strip tool과 호환되지 않습니다. 해결 방법:

  • Android Gradle Plugin 4.0 이상으로 업그레이드
  • 또는 packagingOptions에서 doNotStrip을 사용해 stripping 비활성화(권장하지 않음)

Windows 경로 길이 제한

Windows 시스템에서 프로젝트 내 임의 파일, build 중 생성되는 임시 파일을 포함한 절대 경로 길이가 260자를 초과하면 Android Studio build가 실패할 수 있습니다.

해결 방법:

  • 프로젝트를 더 짧은 path에 배치합니다(예: C:\user\project)
  • 너무 깊은 디렉터리 계층을 피합니다

추가 읽기