Table of Contents

Mengaktifkan fitur EasyAR dalam aplikasi Android

Bab ini memperkenalkan cara mengonfigurasi project Android EasyAR di Android Studio tanpa menggunakan 3D engine seperti Unity.

Persiapan

Sebelum mulai, Anda perlu menyiapkan:

  • Versi terbaru Android Studio

  • JDK 8/11/17

  • Android Gradle Plugin 4.0 atau lebih baru

  • Android NDK r28 atau lebih baru

  • Mendapatkan lisensi otorisasi EasyAR

  • Memilih versi rilis dan mengunduh EasyAR Sense

Catatan

Tidak semua perangkat Android mendukung semua fitur EasyAR Sense. Beberapa fitur bergantung pada hardware atau konfigurasi tambahan. Untuk detail, lihat daftar perangkat yang didukung oleh fitur terkait.

Mengimpor EasyAR Sense for Android

Bagian ini memperkenalkan cara mengimpor EasyAR Sense SDK ke project Android non-Unity. EasyAR Sense menyediakan Java dan C++ API serta mendukung Kotlin, sehingga Anda dapat mengembangkan dengan bahasa yang paling Anda kuasai.

Karena cara konfigurasi IDE yang berbeda mungkin bervariasi, di sini hanya dijelaskan cara konfigurasi tipikal berbasis Android Studio + Gradle.

Memilih cara penggunaan API

EasyAR Sense for Android menyediakan dua cara penggunaan API:

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

Pilih salah satunya untuk dikonfigurasi sesuai kebutuhan proyek Anda.

Hanya menggunakan Java API

Saat hanya menggunakan Java API EasyAR, konfigurasi NDK tidak diperlukan.

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

Menggunakan Java dan C++ API

Saat Anda perlu menggunakan C++ API EasyAR secara bersamaan, Anda harus mengonfigurasi dependensi Java dan pustaka native.

  • File layer Java

    Letakkan EasyAR.jar di app/libs/ atau di path yang ditentukan oleh Gradle.

  • Pustaka native (.so)

    Letakkan pustaka native yang disediakan EasyAR berdasarkan ABI pada path berikut, atau pada path yang ditentukan oleh Gradle.

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

  • File header C++

    Salin folder easyar di bawah direktori include dalam EasyAR SDK ke path berikut, atau ke path yang ditentukan oleh Android.mk/CMakeLists.txt.

    app/src/main/jni/easyar/

    Path file header harus ditentukan secara eksplisit di Android.mk atau CMakeLists.txt.

Catatan konfigurasi Gradle

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

Tambahkan berikut ini ke app/build.gradle:

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

Jika menggunakan CMake, lihat dokumentasi resmi Google untuk konfigurasi.

Konfigurasi NDK

Menyatakan EasyAR sebagai pustaka prebuilt

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)

Menautkan EasyAR dan pustaka sistem

LOCAL_SHARED_LIBRARIES += EasyAR

# OpenGL ES (required)
LOCAL_LDLIBS += -lGLESv3

EasyAR membutuhkan setidaknya OpenGL ES 2.0 saat runtime. OpenGL ES 3.0 (GLESv3) direkomendasikan.

Menentukan arsitektur ABI

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

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

Jika hanya membutuhkan salah satu arsitektur, pertahankan hanya item yang sesuai.

Konfigurasi permission AndroidManifest

EasyAR Sense memerlukan permission berikut. Permission yang hilang akan menyebabkan kegagalan inisialisasi 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 melakukan inisialisasi.

Contoh (Java):

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

Inisialisasi harus selesai sebelum menggunakan fitur terkait EasyAR.

Konfigurasi tambahan

Pada platform Android, bergantung pada versi sistem dan fitur yang digunakan, Anda mungkin juga perlu memperhatikan konfigurasi dan batasan berikut.

Mengonfigurasi penggunaan ARCore

Jika proyek menggunakan ARCore, lihat dokumentasi resminya untuk menyelesaikan konfigurasi terkait AndroidManifest.xml dan build.gradle.

Selain itu, sebelum menginisialisasi EasyAR, Anda harus memuat native library ARCore secara eksplisit:

System.loadLibrary("arcore_sdk_c");
Catatan

Saat menggunakan versi sebelum ARCore v1.19.0, ARCore tidak dapat terdeteksi di Android 11. Hal ini karena Android 11 mulai memperkenalkan pembatasan app visibility, sehingga nama package ARCore perlu dideklarasikan di AndroidManifest.xml.

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

Mengonfigurasi obfuscation (ProGuard)

Jika obfuscation diaktifkan untuk kode Java, Anda perlu mengecualikan namespace cn.easyar.

EasyAR Sense saat runtime menggunakan reflection nama class untuk memperoleh Java type melalui JNI. Jika class di bawah cn.easyar di-obfuscate atau diganti namanya, undefined behavior dapat terjadi.

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 sudah disertakan dalam aar library EasyAR, sehingga biasanya tidak perlu dikonfigurasi ulang.

Scoped Storage

Mekanisme Scoped Storage yang diperkenalkan mulai Android 10 akan memengaruhi sebagian API yang bergantung pada file path. Hal ini karena path non-media di bawah /sdcard, seperti direktori kustom, tidak dapat diakses langsung di Android 10. Dampaknya pada EasyAR terlihat pada sebagian API yang memerlukan file path, seperti screen recording, yang tidak mendukung baca tulis langsung media path di Android 10, tetapi dapat bekerja normal di Android 11.

Solusi:

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

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

  • Solusi yang direkomendasikan

    • Hanya gunakan app internal storage
    • Atau lakukan pertukaran data dengan media path melalui MediaStore

Android Gradle Plugin dan NDK

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

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

Batas panjang path Windows

Pada sistem Windows, jika panjang path absolut file apa pun dalam proyek, termasuk file sementara yang dihasilkan selama build, melebihi 260 karakter, build Android Studio dapat gagal.

Solusi:

  • Letakkan proyek di path yang lebih pendek, misalnya C:\user\project
  • Hindari tingkat direktori yang terlalu dalam

Bacaan lanjutan