Table of Contents

Activer les fonctionnalités EasyAR dans les applications Android

Ce chapitre explique comment configurer un projet Android EasyAR dans Android Studio sans utiliser de moteur 3D comme Unity.

Préparation

Avant de commencer, vous aurez besoin de :

Note

Tous les appareils Android ne prennent pas en charge toutes les fonctionnalités d'EasyAR Sense. Certaines fonctionnalités nécessitent du matériel supplémentaire ou des configurations spécifiques. Consultez les listes d'appareils compatibles pour chaque fonction.

Importer EasyAR Sense pour Android

Cette section explique comment importer le SDK EasyAR Sense dans un projet Android non-Unity. EasyAR Sense fournit des API Java et C++, et prend en charge Kotlin. Vous pouvez développer dans la langue de votre choix.

Étant donné que les configurations varient selon les IDE, seules les méthodes typiques basées sur Android Studio + Gradle sont expliquées ici.

Choisir le mode d'utilisation de l'API

EasyAR Sense pour Android offre deux modes d'utilisation de l'API :

  • Utiliser uniquement l'API Java
  • Utiliser les API Java et C++

Veuillez choisir l'un d'eux pour la configuration en fonction des besoins de votre projet.

Utiliser uniquement l'API Java

Lorsque vous utilisez uniquement l'API Java d'EasyAR, il n'est pas nécessaire de configurer NDK.

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

Utiliser les API Java et C++

Lorsque vous avez besoin d'utiliser à la fois l'API C++ d'EasyAR, vous devez configurer à la fois la dépendance Java et la bibliothèque native.

  • 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 par 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 du répertoire include dans le SDK EasyAR vers le chemin suivant ou vers le chemin spécifié dans 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.

Explication de la configuration Gradle

Lorsque vous utilisez l'API C++, vous devez activer Native Build dans Gradle, l'utilisation de l'API Java uniquement ne nécessite pas de configuration. Vous pouvez utiliser ndk-build (Android.mk) pour la configuration.

Ajoutez dans app/build.gradle :

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

Si vous utilisez CMake, veuillez vous référer à la documentation officielle de Google pour la configuration.

Configuration NDK

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

include $(CLEAR_VARS)

# Assurez-vous que ce chemin pointe vers le répertoire ABI actuel dans jniLibs
LOCAL_PATH := $(LOCAL_PATH_TOP)/../jniLibs/$(TARGET_ARCH_ABI)

LOCAL_MODULE := EasyAR
LOCAL_SRC_FILES := libEasyAR.so

include $(PREBUILT_SHARED_LIBRARY)

Lier EasyAR avec les bibliothèques système

LOCAL_SHARED_LIBRARIES += EasyAR

# OpenGL ES (requis)
LOCAL_LDLIBS += -lGLESv3

EasyAR nécessite au minimum OpenGL ES 2.0, mais OpenGL ES 3.0 (GLESv3) est recommandé.

Spécifier l'architecture ABI

Spécifiez explicitement l'ABI dans app/build.gradle pour éviter que des architectures invalides ne soient empaquetées :

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

Si vous n'avez besoin que d'une seule architecture, vous ne pouvez conserver que l'entrée correspondante.

Configuration des permissions dans 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 l'initialisation.

Exemple (Java) :

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

L'initialisation doit être effectuée avant d'utiliser toute fonctionnalité liée à EasyAR.

Configuration supplémentaire

Sur Android, selon la version du système et les fonctionnalités utilisées, les configurations et limitations suivantes peuvent s'appliquer.

Configuration de l'utilisation de ARCore

Si vous utilisez ARCore dans votre projet, reportez-vous à sa documentation officielle pour compléter la configuration de AndroidManifest.xml et build.gradle.

En outre, avant d'initialiser EasyAR, vous devez charger explicitement la bibliothèque native d'ARCore :

System.loadLibrary("arcore_sdk_c");
Note

Lorsque vous utilisez ARCore version antérieure à v1.19.0, il ne sera pas détectable sur Android 11. Cela est dû aux restrictions de visibilité des applications introduites dans Android 11, nécessitant la déclaration du nom du package ARCore dans AndroidManifest.xml.

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

Configuration de l'obfuscation (ProGuard)

Si vous activez l'obfuscation pour le code Java, vous devez exclure l'espace de noms cn.easyar.

EasyAR Sense utilise la réflexion des noms de classes pour obtenir les types Java via JNI lors de l'exécution. Si les classes sous cn.easyar sont obfusquées ou renommées, cela peut entraîner un comportement indéfini.

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 incluses dans la bibliothèque aar d'EasyAR et ne nécessitent généralement pas de configuration répétée.

Stockage délimité (Scoped Storage)

Le mécanisme Scoped Storage (stockage partitionné) introduit à partir d'Android 10 affecte certaines API qui dépendent des chemins de fichiers. Cela est dû au fait que les chemins non médias sous /sdcard (comme les répertoires personnalisés) ne sont pas accessibles directement sur Android 10. L'impact sur EasyAR se manifeste dans certaines API nécessitant un chemin de fichier (comme l'enregistrement d'écran) qui ne prennent pas en charge la lecture/écriture directe des chemins médias sur Android 10, mais fonctionnent normalement sur Android 11.

Solutions :

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

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

  • Solution recommandée

    • Utiliser uniquement le stockage interne de l'application
    • ou échanger des données avec les chemins médias via MediaStore

Plugin Android Gradle et NDK

Depuis NDK r22, le linker LLD est utilisé par défaut et nécessite llvm-strip, ce qui est incompatible avec l'outil strip intégré dans les versions d'Android Gradle Plugin inférieures à 4.0. Solution:

  • Mettez à niveau vers Android Gradle Plugin 4.0 ou supérieur
  • ou désactivez stripping avec doNotStrip dans packagingOptions (non recommandé)

Limitation de la longueur des chemins sous Windows

Sous Windows, si le chemin absolu de n'importe quel fichier dans le projet (y compris les fichiers temporaires générés pendant la construction) dépasse 260 caractères, cela peut entraîner l'échec de la construction dans Android Studio.

Solutions :

  • Placez le projet dans un chemin plus court (par exemple C:\user\project)
  • Évitez une hiérarchie de répertoires trop profonde

Pour aller plus loin