Table of Contents

Abilitare le funzionalità EasyAR nell'app Android

Questo capitolo spiega come configurare un progetto Android per EasyAR in Android Studio, senza utilizzare motori 3D come Unity.

Preparazione

Prima di iniziare, è necessario:

  • Ultima versione di Android Studio
  • JDK 8/11/17
  • Android Gradle Plugin 4.0 o superiore
  • Android NDK r28 o superiore
  • Ottenere una licenza EasyAR
  • Scegliere una versione di EasyAR Sense e scaricarla
Nota

Non tutti i dispositivi Android supportano tutte le funzionalità di EasyAR Sense. Alcune funzioni richiedono hardware o configurazioni aggiuntive. Consultare gli elenchi dei dispositivi supportati per le funzioni specifiche.

Importare EasyAR Sense per Android

Questa sezione spiega come importare l'SDK EasyAR Sense in un progetto Android non basato su Unity. EasyAR Sense offre API Java e C++ e supporta Kotlin, consentendo di sviluppare con il linguaggio preferito.

Poiché le configurazioni possono variare tra IDE, qui viene descritta solo la configurazione tipica basata su Android Studio + Gradle.

Scegliere la modalità di utilizzo dell'API

EasyAR Sense per Android offre due modalità di utilizzo dell'API:

  • Utilizzo esclusivo dell'API Java
  • Utilizzo combinato di API Java e C++

Scegliere una delle due configurazioni in base alle esigenze del progetto.

Utilizzo esclusivo dell'API Java

Quando si utilizzano esclusivamente le API Java di EasyAR, non è necessario configurare l'NDK.

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

Utilizzo combinato di API Java e C++

Quando è necessario utilizzare sia le API C++ che Java di EasyAR, è richiesta la configurazione delle dipendenze Java e delle librerie native.

  • File a livello Java

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

  • Librerie native (.so)

    Posizionare le librerie native fornite da EasyAR per ABI nel seguente percorso o nel percorso specificato da Gradle.

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

  • File di intestazione C++

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

    app/src/main/jni/easyar/

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

Configurazione gradle

Quando si utilizzano le API C++, è necessario abilitare Native Build in Gradle, non richiesto per l'utilizzo esclusivo dell'API Java. È possibile configurare utilizzando ndk-build (Android.mk).

Aggiungere in app/build.gradle:

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

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

Configurazione NDK

Dichiarare EasyAR come libreria precompilata

include $(CLEAR_VARS)

# Verificare che il percorso punti alla directory ABI corrente 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 con le librerie di sistema

LOCAL_SHARED_LIBRARIES += EasyAR

# OpenGL ES (obbligatorio)
LOCAL_LDLIBS += -lGLESv3

EasyAR richiede almeno OpenGL ES 2.0 per funzionare, è consigliato OpenGL ES 3.0 (GLESv3).

Specificare l'architettura ABI

Specificare esplicitamente l'ABI in app/build.gradle per evitare l'inclusione di architetture non supportate:

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

Se è necessaria solo un'architettura, mantenere solo la voce corrispondente.

Configurazione dei permessi in AndroidManifest

EasyAR Sense richiede i seguenti permessi, la loro assenza causerà un'inizializzazione fallita o uno 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 durante l'avvio dell'app per 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 utilizzare qualsiasi funzionalità correlata a EasyAR.

Configurazioni aggiuntive

Su piattaforma Android, a seconda della versione del sistema e delle funzionalità utilizzate, potrebbero essere necessarie ulteriori configurazioni o sussistono limitazioni.

Configurazione dell'utilizzo di ARCore

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

Inoltre, prima di inizializzare EasyAR, è necessario caricare esplicitamente la libreria nativa di ARCore:

System.loadLibrary("arcore_sdk_c");
Nota

Quando si utilizza ARCore versione precedente a v1.19.0, su Android 11 non verrà rilevato. Ciò è dovuto alle restrizioni sulla visibilità delle app introdotte da Android 11, che richiedono la dichiarazione del nome del pacchetto ARCore in AndroidManifest.xml.

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

Configurazione dell'offuscamento (ProGuard)

Se si abilita l'offuscamento del codice Java, è necessario escludere lo spazio dei nomi cn.easyar.

EasyAR Sense utilizza la riflessione dei nomi delle classi per ottenere i tipi Java tramite JNI durante l'esecuzione. Se le classi sotto cn.easyar vengono offuscate o rinominate, potrebbe causare comportamenti non definiti.

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

Queste regole ProGuard sono già incluse nella libreria aar di EasyAR, generalmente non è necessario configurarle nuovamente.

Archiviazione con ambito

Il meccanismo Scoped Storage (archiviazione con ambito) introdotto a partire da Android 10 influisce su alcune API che dipendono dai percorsi dei file. Ciò è dovuto al fatto che i percorsi non multimediali (ad esempio directory personalizzate) sotto /sdcard non sono direttamente accessibili su Android 10. L'impatto su EasyAR si manifesta in alcune API che richiedono percorsi di file (come la registrazione dello schermo) che su Android 10 non supportano l'accesso diretto ai percorsi multimediali, ma funzionano correttamente su Android 11.

Soluzioni:

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

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

  • Soluzione consigliata

    • Utilizzare solo l'archiviazione interna dell'app
    • Oppure scambiare dati con percorsi multimediali tramite MediaStore

Plugin Android Gradle e NDK

A partire da NDK r22, viene utilizzato per impostazione predefinita il linker LLD e richiede l'uso di llvm-strip; ciò non è compatibile con lo strumento strip integrato nelle versioni di Android Gradle Plugin inferiori alla 4.0. Soluzioni:

  • Aggiornare a Android Gradle Plugin 4.0 o superiore
  • Oppure disabilitare lo stripping con doNotStrip in packagingOptions (non consigliato)

Limite di lunghezza percorso windows

Su sistemi Windows, se il percorso assoluto di qualsiasi file nel progetto (inclusi i file temporanei generati durante la compilazione) supera i 260 caratteri, potrebbe causare un errore di compilazione in Android Studio.

Soluzioni:

  • Posizionare il progetto in un percorso più breve (ad esempio C:\user\project)
  • Evitare gerarchie di directory troppo profonde

Approfondimenti