Table of Contents

Mengaktifkan fitur EasyAR di aplikasi Android

Bab ini menjelaskan cara mengkonfigurasi proyek Android EasyAR di Android Studio tanpa menggunakan mesin 3D seperti Unity.

Persiapan

Sebelum memulai, Anda perlu menyiapkan:

  • Versi terbaru Android Studio
  • JDK 8/11/17
  • Android Gradle Plugin 4.0 atau lebih tinggi
  • Android NDK r28 atau lebih tinggi
  • Mendapatkan lisensi otorisasi EasyAR
  • Pilih versi rilis EasyAR Sense dan unduh
Catatan

Tidak semua perangkat Android mendukung semua fitur EasyAR Sense. Beberapa fitur memerlukan perangkat keras tambahan atau konfigurasi khusus. Silakan periksa daftar perangkat yang didukung untuk fitur terkait.

Mengimpor EasyAR Sense untuk Android

Bagian ini menjelaskan cara mengimpor SDK EasyAR Sense di proyek Android non-Unity. EasyAR Sense menyediakan API Java dan C++, serta mendukung Kotlin, memungkinkan Anda menggunakan bahasa yang paling nyaman.

Karena konfigurasi IDE berbeda-beda, di sini hanya dijelaskan metode konfigurasi tipikal berbasis Android Studio + Gradle.

Cara menggunakan API

EasyAR Sense for Android menyediakan dua cara penggunaan API:

  • Hanya menggunakan Java API
  • Menggunakan Java dan C++ API

Silakan pilih salah satu untuk dikonfigurasi sesuai kebutuhan proyek.

Hanya menggunakan Java API

Saat hanya menggunakan Java API dari EasyAR, tidak perlu mengkonfigurasi NDK.

Letakkan EasyAR.aar ke dalam app/libs/ atau direktori yang ditentukan oleh Gradle.

Menggunakan Java dan C++ API

Saat perlu menggunakan C++ API EasyAR secara bersamaan, perlu mengkonfigurasi dependensi Java dan library native.

  • File lapisan Java

    Letakkan EasyAR.jar ke dalam app/libs/ atau jalur yang ditentukan oleh Gradle.

  • Library native (.so)

    Letakkan library native yang disediakan EasyAR sesuai ABI ke jalur berikut atau jalur yang ditentukan oleh Gradle.

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

  • File header C++

    Salin folder easyar dari direktori include di SDK EasyAR ke jalur berikut atau jalur yang ditentukan oleh Android.mk/CMakeLists.txt.

    app/src/main/jni/easyar/

    Jalur file header perlu ditentukan secara eksplisit di Android.mk atau CMakeLists.txt.

Penjelasan konfigurasi Gradle

Saat Anda menggunakan C++ API, perlu mengaktifkan Native Build di Gradle, hanya menggunakan Java API tidak perlu dikonfigurasi. Anda dapat menggunakan ndk-build (Android.mk) untuk konfigurasi.

Tambahkan di app/build.gradle:

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

Jika menggunakan CMake, silakan merujuk ke dokumentasi resmi Google untuk konfigurasi.

Konfigurasi NDK

Mendeklarasikan EasyAR sebagai library prebuilt

include $(CLEAR_VARS)

# Pastikan jalur ini menunjuk ke direktori ABI saat ini di jniLibs
LOCAL_PATH := $(LOCAL_PATH_TOP)/../jniLibs/$(TARGET_ARCH_ABI)

LOCAL_MODULE := EasyAR
LOCAL_SRC_FILES := libEasyAR.so

include $(PREBUILT_SHARED_LIBRARY)

Menghubungkan EasyAR dengan library sistem

LOCAL_SHARED_LIBRARIES += EasyAR

# OpenGL ES (diperlukan)
LOCAL_LDLIBS += -lGLESv3

EasyAR memerlukan minimal OpenGL ES 2.0, direkomendasikan menggunakan OpenGL ES 3.0 (GLESv3).

Menentukan arsitektur ABI

Tentukan ABI secara eksplisit di app/build.gradle, untuk menghindari arsitektur tidak valid yang ikut terbundel:

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

Jika hanya memerlukan satu arsitektur, cukup pertahankan item yang sesuai.

Konfigurasi izin AndroidManifest

EasyAR Sense memerlukan izin berikut, jika tidak ada akan menyebabkan inisialisasi gagal atau layar hitam:

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

Contoh lengkap:

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

Menginisialisasi EasyAR

Panggil Engine.initialize saat aplikasi dimulai untuk inisialisasi.

Contoh (Java):

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

Inisialisasi harus diselesaikan sebelum menggunakan fungsi terkait EasyAR.

Konfigurasi tambahan

Di platform Android, tergantung versi sistem dan fitur yang digunakan, mungkin perlu memperhatikan konfigurasi dan batasan berikut.

Konfigurasi penggunaan ARCore

Jika proyek menggunakan ARCore, silakan merujuk ke dokumentasi resminya untuk menyelesaikan konfigurasi terkait di AndroidManifest.xml dan build.gradle.

Selain itu, sebelum menginisialisasi EasyAR, pustaka asli ARCore harus dimuat secara eksplisit:

System.loadLibrary("arcore_sdk_c");
Catatan

Saat menggunakan versi ARCore sebelum v1.19.0, tidak akan terdeteksi di Android 11. Ini disebabkan oleh pembatasan visibilitas aplikasi yang diperkenalkan mulai Android 11, yang mengharuskan deklarasi nama paket ARCore di AndroidManifest.xml.

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

Konfigurasi pengaburan (ProGuard)

Jika pengaburan kode Java diaktifkan, perlu mengecualikan ruang nama cn.easyar.

EasyAR Sense menggunakan refleksi nama kelas untuk mendapatkan tipe Java melalui JNI saat runtime. Jika kelas di bawah cn.easyar diaburkan atau diganti namanya, dapat menyebabkan perilaku tidak terdefinisi.

Aturan dasar

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

Aturan presisi yang direkomendasikan

-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

Aturan ProGuard di atas telah disertakan dalam pustaka aar EasyAR, sehingga biasanya tidak perlu dikonfigurasi ulang.

Scoped Storage

Mekanisme Scoped Storage (penyimpanan terpartisi) yang diperkenalkan mulai Android 10, akan memengaruhi beberapa API yang bergantung pada jalur file. Ini disebabkan oleh ketidakmampuan mengakses jalur non-media di bawah /sdcard (seperti direktori kustom) secara langsung di Android 10. Dampaknya pada EasyAR terlihat pada beberapa API yang memerlukan jalur file sebagai masukan (seperti perekaman layar) di Android 10 tidak mendukung penulisan/ pembacaan langsung ke jalur media, tetapi berfungsi normal di Android 11.

Solusi:

  • Opsi sederhana (Android 10) Nonaktifkan Scoped Storage di AndroidManifest.xml:

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

  • Opsi yang direkomendasikan

    • Hanya gunakan penyimpanan internal aplikasi
    • Atau bertukar data dengan jalur media melalui MediaStore

Android Gradle Plugin dan NDK

Sejak NDK r22, linker LLD digunakan secara default dan memerlukan llvm-strip; ini tidak kompatibel dengan alat strip bawaan versi Android Gradle Plugin di bawah 4.0. Solusi:

  • Tingkatkan ke Android Gradle Plugin 4.0 atau lebih tinggi
  • Atau gunakan doNotStrip di packagingOptions untuk menonaktifkan stripping (tidak direkomendasikan)

Batasan panjang jalur Windows

Di sistem Windows, jika panjang jalur absolut dari file apa pun dalam proyek (termasuk file sementara yang dihasilkan selama proses pembangunan) melebihi 260 karakter, dapat menyebabkan pembangunan Android Studio gagal.

Solusi:

  • Tempatkan proyek di jalur yang lebih pendek (misalnya C:\user\project)
  • Hindari hierarki direktori yang terlalu dalam

Bacaan lebih lanjut