Table of Contents

Abilitare le funzioni EasyAR in un'applicazione Android

Questo capitolo presenta come configurare un progetto Android di EasyAR in Android Studio senza usare un 3D engine come Unity.

Preparazione

Prima di iniziare, è necessario preparare:

  • L'ultima versione di Android Studio

  • JDK 8/11/17

  • Android Gradle Plugin 4.0 o superiore

  • Android NDK r28 o superiore

  • Ottenere una licenza di autorizzazione EasyAR

  • Selezionare una versione di rilascio e scaricare EasyAR Sense

Nota

Non tutti i dispositivi Android supportano tutte le funzioni di EasyAR Sense. Alcune funzioni dipendono da hardware o configurazioni aggiuntive. Per i dettagli, consultare la lista dei dispositivi supportati dalla funzione corrispondente.

Importare EasyAR Sense for Android

Questa sezione presenta come importare EasyAR Sense SDK in un progetto Android non Unity. EasyAR Sense fornisce API Java e C++ e supporta Kotlin, quindi è possibile sviluppare con il linguaggio più familiare.

Poiché i metodi di configurazione dei diversi IDE possono variare, qui viene descritto solo il metodo di configurazione tipico basato su Android Studio + Gradle.

Scegliere il metodo di utilizzo dell'API

EasyAR Sense for Android fornisce due metodi di utilizzo API:

  • Usare solo la Java API
  • Usare le API Java e C++

Scegliere una delle due configurazioni in base ai requisiti del progetto.

Usare solo la Java API

Quando si usa solo la Java API di EasyAR, non è necessaria la configurazione NDK.

Mettere EasyAR.aar in app/libs/ o nella directory specificata da Gradle.

Usare le API Java e C++

Quando è necessario usare contemporaneamente la C++ API di EasyAR, è necessario configurare sia le dipendenze Java sia le librerie native.

  • File del layer Java

    Mettere EasyAR.jar in app/libs/ o nel percorso specificato da Gradle.

  • Librerie native (.so)

    Mettere le librerie native fornite da EasyAR in base all'ABI nel seguente percorso o nel percorso specificato da Gradle.

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

  • File header C++

    Copiare la cartella easyar sotto la directory include in EasyAR SDK nel seguente percorso o nel percorso specificato da Android.mk/CMakeLists.txt.

    app/src/main/jni/easyar/

    Il percorso dei file header deve essere specificato esplicitamente in Android.mk o CMakeLists.txt.

Note di configurazione Gradle

Quando si usa la C++ API, è necessario abilitare Native Build in Gradle. Se si usa solo la Java API, non è richiesta alcuna configurazione. È possibile configurarlo con ndk-build (Android.mk).

Aggiungere quanto segue in app/build.gradle:

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

Se si usa CMake, fare riferimento alla documentazione ufficiale Google per la configurazione.

Configurazione NDK

Dichiarare EasyAR come libreria precompilata

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)

Collegare EasyAR e le librerie di sistema

LOCAL_SHARED_LIBRARIES += EasyAR

# OpenGL ES (required)
LOCAL_LDLIBS += -lGLESv3

EasyAR richiede almeno OpenGL ES 2.0 a runtime. OpenGL ES 3.0 (GLESv3) è consigliato.

Specificare le architetture ABI

Specificare esplicitamente ABI in app/build.gradle per evitare di pacchettizzare architetture non valide:

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

Se serve una sola architettura, mantenere solo l'elemento corrispondente.

Configurazione dei permessi AndroidManifest

EasyAR Sense richiede i seguenti permessi. Permessi mancanti causeranno errore di inizializzazione o schermo nero:

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

Esempio completo:

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

Inizializzare EasyAR

Chiamare Engine.initialize all'avvio dell'applicazione per eseguire l'inizializzazione.

Esempio (Java):

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

L'inizializzazione deve essere completata prima di usare funzionalità relative a EasyAR.

Configurazione aggiuntiva

Sulla piattaforma Android, a seconda della versione del sistema e delle funzioni usate, potrebbe essere necessario prestare attenzione anche alle seguenti configurazioni e limitazioni.

Configurare l'uso di ARCore

Se il progetto usa ARCore, fare riferimento alla documentazione ufficiale per completare la configurazione relativa di AndroidManifest.xml e build.gradle.

Inoltre, prima di inizializzare EasyAR, è necessario caricare esplicitamente la native library di ARCore:

System.loadLibrary("arcore_sdk_c");
Nota

Quando si usano versioni precedenti ad ARCore v1.19.0, ARCore non può essere rilevato su Android 11. Questo perché Android 11 ha introdotto restrizioni di app visibility e il nome package di ARCore deve essere dichiarato in AndroidManifest.xml.

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

Configurare obfuscation (ProGuard)

Se l'obfuscation è abilitata per il codice Java, è necessario escludere il namespace cn.easyar.

EasyAR Sense usa a runtime class name reflection per ottenere Java types tramite JNI. Se le classi sotto cn.easyar vengono obfuscated o rinominate, può verificarsi undefined behavior.

Regole di base

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

Regole precise consigliate

-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

Le regole ProGuard sopra sono già incluse nella aar library di EasyAR, quindi di solito non è necessario configurarle di nuovo.

Scoped Storage

Il meccanismo Scoped Storage introdotto da Android 10 influisce su alcune API che dipendono da file paths. Ciò è dovuto al fatto che non-media paths sotto /sdcard, come directory personalizzate, non possono essere accessibili direttamente su Android 10. L'impatto su EasyAR è che alcune API che richiedono file paths, come screen recording, su Android 10 non supportano lettura e scrittura diretta di media paths, ma funzionano normalmente su Android 11.

Soluzioni:

  • Soluzione semplice (Android 10) Disabilitare Scoped Storage in AndroidManifest.xml:

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

  • Soluzione consigliata

    • Usare solo app internal storage
    • Oppure scambiare dati con media paths tramite MediaStore

Android Gradle Plugin e NDK

A partire da NDK r22, viene usato di default il linker LLD e deve essere usato insieme a llvm-strip; questo non è compatibile con lo strumento strip integrato nelle versioni di Android Gradle Plugin precedenti alla 4.0. Soluzioni:

  • Aggiornare a Android Gradle Plugin 4.0 o successivo
  • Oppure usare doNotStrip in packagingOptions per disabilitare stripping (non consigliato)

Limite di lunghezza del path su Windows

Su Windows, se la lunghezza assoluta del path di qualsiasi file nel progetto, inclusi i file temporanei generati durante il build, supera 260 caratteri, il build di Android Studio può fallire.

Soluzioni:

  • Posizionare il progetto in un path più breve, ad esempio C:\user\project
  • Evitare livelli di directory troppo profondi

Letture aggiuntive