Table of Contents

Habilitar EasyAR en aplicaciones de Android

Este capítulo explica cómo configurar un proyecto de Android para EasyAR en Android Studio, sin utilizar motores 3D como Unity.

Preparativos

Antes de comenzar, necesitarás:

  • La última versión de Android Studio
  • JDK 8/11/17
  • Android Gradle Plugin 4.0 o superior
  • Android NDK r28 o superior
  • Obtener una licencia de EasyAR
  • Seleccionar una versión de EasyAR Sense y descargarla
Nota

No todos los dispositivos Android admiten todas las funciones de EasyAR Sense. Algunas características requieren hardware adicional o configuraciones específicas. Consulta las listas de dispositivos compatibles para cada función.

Importar EasyAR Sense para Android

Esta sección explica cómo importar el SDK de EasyAR Sense en un proyecto de Android sin Unity. EasyAR Sense ofrece APIs en Java y C++, además de soporte para Kotlin, permitiéndote desarrollar en el lenguaje que prefieras.

Dado que la configuración puede variar entre IDEs, aquí solo se describe el método típico basado en Android Studio + Gradle.

Selección del modo de uso de API

EasyAR Sense para Android ofrece dos modos de uso de API:

  • Usar solo Java API
  • Usar Java y C++ API

Seleccione uno para configurar según los requisitos del proyecto.

Usar solo Java API

Cuando se usa solo Java API de EasyAR, no es necesario configurar NDK.

Coloque EasyAR.aar en app/libs/ o en el directorio especificado por Gradle.

Usar Java y C++ API

Cuando se requiere usar tanto C++ API como Java API de EasyAR, es necesario configurar la dependencia Java y las bibliotecas nativas.

  • Archivos de capa Java

    Coloque EasyAR.jar en app/libs/ o en la ruta especificada por Gradle.

  • Bibliotecas nativas (.so)

    Coloque las bibliotecas nativas proporcionadas por EasyAR por ABI en la siguiente ruta o en la ruta especificada por Gradle.

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

  • Archivos de cabecera C++

    Copie la carpeta easyar del directorio include en el SDK de EasyAR a la siguiente ruta o a la ruta especificada por Android.mk/CMakeLists.txt.

    app/src/main/jni/easyar/

    La ruta de los archivos de cabecera debe especificarse explícitamente en Android.mk o CMakeLists.txt.

Explicación de configuración de Gradle

Cuando use C++ API, debe habilitar Native Build en Gradle, no se requiere configuración si solo usa Java API. Puede usar ndk-build (Android.mk) para configurar.

Agregue en app/build.gradle:

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

Si usa CMake, consulte la documentación oficial de Google para configurar.

Configuración de NDK

Declarar EasyAR como biblioteca precompilada

include $(CLEAR_VARS)

# Asegúrese de que esta ruta apunte al directorio ABI actual en jniLibs
LOCAL_PATH := $(LOCAL_PATH_TOP)/../jniLibs/$(TARGET_ARCH_ABI)

LOCAL_MODULE := EasyAR
LOCAL_SRC_FILES := libEasyAR.so

include $(PREBUILT_SHARED_LIBRARY)

Vincular EasyAR con bibliotecas del sistema

LOCAL_SHARED_LIBRARIES += EasyAR

# OpenGL ES (requerido)
LOCAL_LDLIBS += -lGLESv3

EasyAR requiere al menos OpenGL ES 2.0, se recomienda OpenGL ES 3.0 (GLESv3).

Especificar arquitectura ABI

Especifique explícitamente ABI en app/build.gradle para evitar empaquetar arquitecturas inválidas:

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

Si solo necesita una arquitectura, mantenga únicamente la correspondiente.

Configuración de permisos en AndroidManifest

EasyAR Sense requiere los siguientes permisos; su ausencia causará fallos de inicialización o pantalla negra:

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

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

Inicializar EasyAR

Llame a Engine.initialize durante el inicio de la aplicación para inicializar.

Ejemplo (Java):

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

La inicialización debe completarse antes de usar cualquier función relacionada con EasyAR.

Configuración adicional

En la plataforma Android, dependiendo de la versión del sistema y las funciones utilizadas, podrían requerirse las siguientes configuraciones y restricciones.

Configuración de uso de ARCore

Si usas ARCore en tu proyecto, consulta la documentación oficial para completar la configuración relacionada en AndroidManifest.xml y build.gradle.

Además, antes de inicializar EasyAR, debes cargar explícitamente la biblioteca nativa de ARCore:

System.loadLibrary("arcore_sdk_c");
Nota

Al usar versiones de ARCore anteriores a v1.19.0, no se podrá detectar en Android 11. Esto se debe a las restricciones de visibilidad de aplicaciones introducidas en Android 11, que requieren declarar el nombre del paquete de ARCore en AndroidManifest.xml.

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

Configuración de ofuscación (ProGuard)

Si habilitas la ofuscación de código Java, debes excluir el espacio de nombres cn.easyar.

EasyAR Sense utiliza reflexión de nombres de clase para obtener tipos Java a través de JNI durante el tiempo de ejecución. Si las clases bajo cn.easyar se ofuscan o renombran, puede provocar un comportamiento indefinido.

Reglas básicas

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

Reglas precisas recomendadas

-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

Estas reglas de ProGuard ya están incluidas en la biblioteca aar de EasyAR, por lo que generalmente no es necesario configurarlas nuevamente.

Almacenamiento delimitado

El mecanismo Scoped Storage (Almacenamiento delimitado) introducido desde Android 10 afecta a algunas API que dependen de rutas de archivos. Esto se debe a que las rutas no multimedia (como directorios personalizados) en /sdcard no son directamente accesibles en Android 10. En EasyAR, esto afecta a las API que requieren pasar rutas de archivos (como la grabación de pantalla), las cuales no pueden acceder directamente a rutas multimedia en Android 10, pero funcionan correctamente en Android 11.

Soluciones:

  • Opción simple (Android 10) Deshabilita Scoped Storage en AndroidManifest.xml:

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

  • Opción recomendada

    • Usar solo el almacenamiento interno de la aplicación
    • O intercambiar datos con rutas multimedia a través de MediaStore

Android Gradle Plugin y NDK

Desde NDK r22, se usa el enlazador LLD por defecto y requiere la herramienta llvm-strip; esto es incompatible con la herramienta strip integrada en versiones de Android Gradle Plugin inferiores a 4.0. Soluciones:

  • Actualizar a Android Gradle Plugin 4.0 o superior
  • O usar doNoStrip en packagingOptions para deshabilitar el striping (no recomendado)

Límite de longitud de ruta en Windows

En sistemas Windows, si la longitud de la ruta absoluta de cualquier archivo en el proyecto (incluyendo archivos temporales generados durante la construcción) supera los 260 caracteres, puede causar fallos en la construcción de Android Studio.

Soluciones:

  • Ubicar el proyecto en una ruta más corta (por ejemplo, C:\user\project)
  • Evitar niveles de directorios excesivamente profundos

Lecturas adicionales