Table of Contents

Activar funciones EasyAR en una aplicación Android

Este capítulo presenta cómo configurar un proyecto Android de EasyAR en Android Studio sin usar un 3D engine como Unity.

Preparación

Antes de empezar, debe preparar:

  • La versión más reciente de Android Studio

  • JDK 8/11/17

  • Android Gradle Plugin 4.0 o superior

  • Android NDK r28 o superior

  • Obtener una licencia de autorización EasyAR

  • Seleccionar una versión de lanzamiento y descargar EasyAR Sense

Nota

No todos los dispositivos Android admiten todas las funciones de EasyAR Sense. Algunas funciones dependen de hardware o configuración adicional. Para más detalles, consulte la lista de dispositivos compatibles con la función correspondiente.

Importar EasyAR Sense for Android

Esta sección presenta cómo importar EasyAR Sense SDK en un proyecto Android que no usa Unity. EasyAR Sense proporciona API Java y C++ y admite Kotlin, por lo que puede desarrollar con el lenguaje con el que se sienta más cómodo.

Como los métodos de configuración pueden variar entre IDE, aquí solo se describe el método de configuración típico basado en Android Studio + Gradle.

Elegir el método de uso de la API

EasyAR Sense for Android proporciona dos métodos de uso de API:

  • Usar solo la Java API
  • Usar las API de Java y C++

Elija una de ellas para configurarla según los requisitos del proyecto.

Usar solo la Java API

Cuando solo se usa la Java API de EasyAR, no se requiere configurar NDK.

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

Usar las API de Java y C++

Cuando necesite usar también la C++ API de EasyAR, debe configurar tanto las dependencias Java como las bibliotecas nativas.

  • Archivos de la 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 según 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 de EasyAR SDK en la siguiente ruta o en 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.

Notas de configuración de Gradle

Cuando usa la C++ API, debe habilitar Native Build en Gradle. Si solo usa la Java API, no se requiere configuración. Puede configurarlo con ndk-build (Android.mk).

Agregue lo siguiente en app/build.gradle:

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

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

Configuración de NDK

Declarar EasyAR como biblioteca precompilada

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)

Enlazar EasyAR y bibliotecas del sistema

LOCAL_SHARED_LIBRARIES += EasyAR

# OpenGL ES (required)
LOCAL_LDLIBS += -lGLESv3

EasyAR requiere al menos OpenGL ES 2.0 en tiempo de ejecución. Se recomienda OpenGL ES 3.0 (GLESv3).

Especificar arquitecturas ABI

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

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

Si solo necesita una arquitectura, conserve solo el elemento correspondiente.

Configuración de permisos de AndroidManifest

EasyAR Sense requiere los siguientes permisos. La ausencia de permisos provocará fallo 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 al iniciar 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 funciones relacionadas con EasyAR.

Configuración adicional

En la plataforma Android, según la versión del sistema y las funciones utilizadas, también puede ser necesario prestar atención a las siguientes configuraciones y restricciones.

Configurar el uso de ARCore

Si el proyecto usa ARCore, consulte su documentación oficial para completar la configuración relacionada de AndroidManifest.xml y build.gradle.

Además, antes de inicializar EasyAR, debe cargar explícitamente la native library de ARCore:

System.loadLibrary("arcore_sdk_c");
Nota

Al usar versiones anteriores a ARCore v1.19.0, ARCore no se podrá detectar en Android 11. Esto se debe a que Android 11 introdujo restricciones de app visibility, y es necesario declarar el nombre de package de ARCore en AndroidManifest.xml.

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

Configurar obfuscation (ProGuard)

Si se habilita obfuscation para el código Java, debe excluir el namespace cn.easyar.

EasyAR Sense usa reflection de nombres de clase para obtener Java types mediante JNI en runtime. Si las clases bajo cn.easyar se obfuscate o renombran, puede producirse undefined behavior.

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

Las reglas ProGuard anteriores ya están incluidas en la aar library de EasyAR, por lo que normalmente no es necesario configurarlas de nuevo.

Scoped Storage

El mecanismo Scoped Storage introducido a partir de Android 10 afecta a algunas API que dependen de file paths. Esto se debe a que las rutas non-media bajo /sdcard, como directorios personalizados, no pueden accederse directamente en Android 10. En EasyAR, el impacto se refleja en que algunas API que requieren file paths, como screen recording, no soportan lectura y escritura directa de media paths en Android 10, pero funcionan normalmente en Android 11.

Soluciones:

  • Solución simple (Android 10) Deshabilite Scoped Storage en AndroidManifest.xml:

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

  • Solución recomendada

    • Usar solo app internal storage
    • O intercambiar datos con media paths mediante MediaStore

Android Gradle Plugin y NDK

Desde NDK r22, se usa por defecto el linker LLD y debe trabajar con llvm-strip; esto no es compatible con la herramienta strip integrada en Android Gradle Plugin anterior a 4.0. Soluciones:

  • Actualizar a Android Gradle Plugin 4.0 o superior
  • O usar doNotStrip en packagingOptions para deshabilitar stripping (no recomendado)

Límite de longitud de ruta en Windows

En Windows, si la longitud absoluta de la ruta de cualquier archivo del proyecto, incluidos archivos temporales generados durante el build, supera 260 caracteres, el build de Android Studio puede fallar.

Soluciones:

  • Colocar el proyecto en una ruta más corta, como C:\user\project
  • Evitar niveles de directorio demasiado profundos

Lectura adicional