Table of Contents

Habilitar recursos EasyAR em aplicativos Android

Este capítulo explica como configurar o projeto Android do EasyAR no Android Studio, sem usar motores 3D como Unity.

Preparação

Antes de começar, você precisará de:

Nota

Nem todos os dispositivos Android suportam todos os recursos do EasyAR Sense. Alguns recursos dependem de hardware ou configurações adicionais. Consulte as listas de dispositivos suportados para cada recurso específico.

Importar o EasyAR Sense para Android

Esta seção descreve como importar o SDK do EasyAR Sense em um projeto Android não-Unity. O EasyAR Sense oferece APIs Java e C++ e suporta Kotlin, permitindo que você desenvolva na linguagem que preferir.

Como as configurações podem variar entre diferentes IDEs, aqui focaremos no método de configuração típico baseado em Android Studio + Gradle.

Escolhendo o método de uso da API

O EasyAR Sense for Android oferece dois métodos de uso da API:

  • Usar apenas a API Java
  • Usar as APIs Java e C++

Escolha um deles para configurar de acordo com os requisitos do seu projeto.

Usar apenas a API Java

Ao usar apenas a API Java do EasyAR, não é necessário configurar o NDK.

Coloque o EasyAR.aar em app/libs/ ou no diretório especificado pelo Gradle.

Usar as APIs Java e C++

Ao precisar usar a API C++ do EasyAR simultaneamente, é necessário configurar a dependência Java e a biblioteca nativa.

  • Arquivos da camada Java

    Coloque o EasyAR.jar em app/libs/ ou no caminho especificado pelo Gradle.

  • Bibliotecas nativas (.so)

    Coloque as bibliotecas nativas fornecidas pelo EasyAR por ABI no seguinte caminho ou no caminho especificado pelo Gradle.

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

  • Arquivos de cabeçalho C++

    Copie a pasta easyar do diretório include no SDK do EasyAR para o seguinte caminho ou para o caminho especificado pelo Android.mk/CMakeLists.txt.

    app/src/main/jni/easyar/

    O caminho dos arquivos de cabeçalho deve ser explicitamente especificado no Android.mk ou CMakeLists.txt.

Explicação da configuração do Gradle

Ao usar a API C++, é necessário habilitar o Native Build no Gradle, usar apenas a API Java não requer configuração. Você pode usar o ndk-build (Android.mk) para configurar.

Adicione em app/build.gradle:

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

Se usar o CMake, consulte a documentação oficial do Google para configurar.

Configuração do NDK

Declarando o EasyAR como biblioteca pré-compilada

include $(CLEAR_VARS)

# Garanta que este caminho aponte para o diretório ABI atual em jniLibs
LOCAL_PATH := $(LOCAL_PATH_TOP)/../jniLibs/$(TARGET_ARCH_ABI)

LOCAL_MODULE := EasyAR
LOCAL_SRC_FILES := libEasyAR.so

include $(PREBUILT_SHARED_LIBRARY)

Vinculando easyar com bibliotecas do sistema

LOCAL_SHARED_LIBRARIES += EasyAR

# OpenGL ES (obrigatório)
LOCAL_LDLIBS += -lGLESv3

O EasyAR requer pelo menos OpenGL ES 2.0, sendo OpenGL ES 3.0 (GLESv3) recomendado.

Especificando a arquitetura ABI

Especifique explicitamente a ABI em app/build.gradle para evitar o empacotamento de arquiteturas inválidas:

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

Se precisar de apenas uma arquitetura, mantenha apenas o item correspondente.

Configuração de permissões no AndroidManifest

O EasyAR Sense requer as seguintes permissões; a ausência resultará em falha de inicialização ou tela preta:

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

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

Inicializando o EasyAR

Chame Engine.initialize durante a inicialização do aplicativo.

Exemplo (Java):

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

A inicialização deve ser concluída antes de usar qualquer funcionalidade relacionada ao EasyAR.

Configurações adicionais

Na plataforma Android, dependendo da versão do sistema e dos recursos utilizados, as seguintes configurações e limitações também podem ser relevantes.

Configurar o uso do ARCore

Se o projeto usar ARCore, consulte a documentação oficial para completar as configurações relevantes no AndroidManifest.xml e build.gradle.

Além disso, antes de inicializar o EasyAR, é necessário carregar explicitamente a biblioteca nativa do ARCore:

System.loadLibrary("arcore_sdk_c");
Nota

Ao usar versões do ARCore anteriores à v1.19.0, o dispositivo Android 11 não será detectado. Isso ocorre devido às restrições de visibilidade de aplicativos introduzidas no Android 11, exigindo a declaração do nome do pacote do ARCore no AndroidManifest.xml.

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

Configurar ofuscação (ProGuard)

Se a ofuscação de código Java estiver ativada, é necessário excluir o namespace cn.easyar.

O EasyAR Sense usa reflexão de nomes de classe via JNI durante a execução para obter tipos Java. Se as classes em cn.easyar forem ofuscadas ou renomeadas, pode causar comportamento indefinido.

Regras básicas

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

Regras 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

Essas regras do ProGuard já estão incluídas na biblioteca aar do EasyAR, geralmente não sendo necessário reconfigurá-las.

Armazenamento com escopo

O mecanismo Scoped Storage (armazenamento particionado) introduzido no Android 10 afeta APIs que dependem de caminhos de arquivo. Isso ocorre porque caminhos não relacionados a mídia (como diretórios personalizados) em /sdcard não são diretamente acessíveis no Android 10. No EasyAR, isso impacta APIs que exigem caminhos de arquivo (como gravação de tela), que não funcionarão com caminhos de mídia diretos no Android 10, mas funcionarão no Android 11.

Soluções:

  • Solução simples (Android 10) Desative o Scoped Storage no AndroidManifest.xml:

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

  • Solução recomendada

    • Use apenas o armazenamento interno do aplicativo
    • Ou troque dados com caminhos de mídia via MediaStore

Android Gradle Plugin e NDK

A partir do NDK r22, o vinculador LLD é usado por padrão, exigindo llvm-strip; isso é incompatível com a ferramenta strip integrada em versões do Android Gradle Plugin abaixo de 4.0. Soluções:

  • Atualize para Android Gradle Plugin 4.0 ou superior
  • Ou use doNotStrip em packagingOptions para desativar o stripping (não recomendado)

Limite de comprimento de caminho no Windows

No Windows, se o caminho absoluto de qualquer arquivo (incluindo arquivos temporários gerados durante a compilação) exceder 260 caracteres, o Android Studio pode falhar na compilação.

Soluções:

  • Coloque o projeto em um caminho mais curto (ex: C:\user\project)
  • Evite hierarquias de diretórios muito profundas

Leitura adicional