Table of Contents

Activer les fonctions EasyAR dans une application Android

Ce chapitre présente comment configurer un projet Android EasyAR dans Android Studio sans utiliser de 3D engine comme Unity.

Préparation

Avant de commencer, vous devez préparer:

  • La dernière version de Android Studio

  • JDK 8/11/17

  • Android Gradle Plugin 4.0 ou supérieur

  • Android NDK r28 ou supérieur

  • Obtenir une licence d'autorisation EasyAR

  • Sélectionner une version de publication et télécharger EasyAR Sense

Note

Tous les appareils Android ne prennent pas en charge toutes les fonctions de EasyAR Sense. Certaines fonctions dépendent de hardware ou configurations supplémentaires. Pour les détails, consultez la liste des appareils pris en charge par la fonction correspondante.

Importer EasyAR Sense for Android

Cette section présente comment importer EasyAR Sense SDK dans un projet Android non Unity. EasyAR Sense fournit des API Java et C++ et prend en charge Kotlin, vous pouvez donc développer avec le langage que vous maîtrisez le mieux.

Comme les méthodes de configuration peuvent varier selon les IDE, seule la méthode de configuration typique basée sur Android Studio + Gradle est décrite ici.

Choisir le mode d'utilisation de l'API

EasyAR Sense for Android fournit deux modes d'utilisation de l'API :

  • Utiliser uniquement la Java API
  • Utiliser les API Java et C++

Choisissez l'une des deux configurations selon les besoins du projet.

Utiliser uniquement la Java API

Lorsque seule la Java API d'EasyAR est utilisée, aucune configuration NDK n'est requise.

Placez EasyAR.aar dans app/libs/ ou dans le répertoire spécifié par Gradle.

Utiliser les API Java et C++

Lorsque vous devez également utiliser la C++ API d'EasyAR, vous devez configurer à la fois les dépendances Java et les bibliothèques natives.

  • Fichiers de la couche Java

    Placez EasyAR.jar dans app/libs/ ou dans le chemin spécifié par Gradle.

  • Bibliothèques natives (.so)

    Placez les bibliothèques natives fournies par EasyAR selon l'ABI dans le chemin suivant ou dans le chemin spécifié par Gradle.

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

  • Fichiers d'en-tête C++

    Copiez le dossier easyar situé sous le répertoire include dans EasyAR SDK vers le chemin suivant, ou vers le chemin spécifié par Android.mk/CMakeLists.txt.

    app/src/main/jni/easyar/

    Le chemin des fichiers d'en-tête doit être explicitement spécifié dans Android.mk ou CMakeLists.txt.

Notes de configuration Gradle

Lorsque vous utilisez la C++ API, vous devez activer Native Build dans Gradle. Si vous utilisez uniquement la Java API, aucune configuration n'est requise. Vous pouvez configurer cela avec ndk-build (Android.mk).

Ajoutez ce qui suit dans app/build.gradle :

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

Si vous utilisez CMake, consultez la documentation officielle de Google pour la configuration.

Configuration NDK

Déclarer EasyAR comme bibliothèque précompilée

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)

Lier EasyAR et les bibliothèques système

LOCAL_SHARED_LIBRARIES += EasyAR

# OpenGL ES (required)
LOCAL_LDLIBS += -lGLESv3

EasyAR nécessite au minimum OpenGL ES 2.0 à l'exécution. OpenGL ES 3.0 (GLESv3) est recommandé.

Spécifier les architectures ABI

Spécifiez explicitement ABI dans app/build.gradle afin d'éviter d'empaqueter des architectures invalides :

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

Si une seule architecture est nécessaire, conservez uniquement l'élément correspondant.

Configuration des permissions AndroidManifest

EasyAR Sense nécessite les permissions suivantes. Leur absence entraînera un échec d'initialisation ou un écran noir :

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

Exemple complet :

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

Initialiser EasyAR

Appelez Engine.initialize au démarrage de l'application pour effectuer l'initialisation.

Exemple (Java) :

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

L'initialisation doit être terminée avant d'utiliser les fonctionnalités liées à EasyAR.

Configuration supplémentaire

Sur la plateforme Android, selon la version du système et les fonctions utilisées, il peut également être nécessaire de prêter attention aux configurations et limitations suivantes.

Configurer l'utilisation d'ARCore

Si le projet utilise ARCore, consultez sa documentation officielle pour terminer la configuration liée à AndroidManifest.xml et build.gradle.

De plus, avant d'initialiser EasyAR, vous devez charger explicitement la native library d'ARCore :

System.loadLibrary("arcore_sdk_c");
Note

Lors de l'utilisation de versions antérieures à ARCore v1.19.0, ARCore ne pourra pas être détecté sur Android 11. Cela est dû au fait qu'Android 11 a introduit des restrictions d'app visibility, et le nom du package ARCore doit être déclaré dans AndroidManifest.xml.

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

Configurer obfuscation (ProGuard)

Si obfuscation est activée pour le code Java, vous devez exclure le namespace cn.easyar.

EasyAR Sense utilise à runtime class name reflection pour obtenir Java types via JNI. Si les classes sous cn.easyar sont obfuscated ou renommées, undefined behavior peut se produire.

Règles de base

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

Règles précises recommandées

-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

Les règles ProGuard ci-dessus sont déjà incluses dans la aar library d'EasyAR, il n'est donc généralement pas nécessaire de les configurer à nouveau.

Scoped Storage

Le mécanisme Scoped Storage introduit à partir d'Android 10 affecte certaines API qui dépendent des file paths. Cela est dû au fait que les non-media paths sous /sdcard, comme les répertoires personnalisés, ne peuvent pas être accessibles directement sur Android 10. L'impact sur EasyAR se manifeste par le fait que certaines API nécessitant des file paths, comme screen recording, ne prennent pas en charge la lecture et l'écriture directes des media paths sur Android 10, mais fonctionnent normalement sur Android 11.

Solutions :

  • Solution simple (Android 10) Désactiver Scoped Storage dans AndroidManifest.xml :

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

  • Solution recommandée

    • Utiliser uniquement app internal storage
    • Ou échanger les données avec les media paths via MediaStore

Android Gradle Plugin et NDK

Depuis NDK r22, le linker LLD est utilisé par défaut et doit être utilisé avec llvm-strip ; cela est incompatible avec l'outil strip intégré dans Android Gradle Plugin avant la version 4.0. Solutions :

  • Mettre à niveau vers Android Gradle Plugin 4.0 ou supérieur
  • Ou utiliser doNotStrip dans packagingOptions pour désactiver stripping (non recommandé)

Limite de longueur des chemins Windows

Sous Windows, si la longueur absolue du chemin de n'importe quel fichier du projet, y compris les fichiers temporaires générés pendant le build, dépasse 260 caractères, le build Android Studio peut échouer.

Solutions :

  • Placer le projet dans un chemin plus court, par exemple C:\user\project
  • Éviter les niveaux de répertoires trop profonds

Lecture complémentaire