Table of Contents

Ativar recursos EasyAR em uma aplicação Android

Este capítulo apresenta como configurar um projeto Android do EasyAR no Android Studio sem usar um 3D engine como Unity.

Preparação

Antes de começar, você precisa preparar:

  • A versão mais recente do Android Studio

  • JDK 8/11/17

  • Android Gradle Plugin 4.0 ou superior

  • Android NDK r28 ou superior

  • Obter uma licença de autorização EasyAR

  • Selecionar uma versão de lançamento e baixar EasyAR Sense

Nota

Nem todos os dispositivos Android suportam todos os recursos do EasyAR Sense. Alguns recursos dependem de hardware ou configuração adicional. Para detalhes, consulte a lista de dispositivos suportados pelo recurso correspondente.

Importar EasyAR Sense for Android

Esta seção apresenta como importar EasyAR Sense SDK em um projeto Android que não usa Unity. EasyAR Sense fornece API Java e C++ e suporta Kotlin, então você pode desenvolver com a linguagem com que estiver mais acostumado.

Como os métodos de configuração podem diferir entre IDEs, aqui é descrito apenas o método típico de configuração baseado em Android Studio + Gradle.

Escolher o método de uso da API

EasyAR Sense for Android fornece dois métodos de uso de API:

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

Escolha uma delas para configurar de acordo com os requisitos do projeto.

Usar apenas a Java API

Ao usar apenas a Java API do EasyAR, a configuração do NDK não é necessária.

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

Usar as APIs Java e C++

Quando for necessário usar também a C++ API do EasyAR, você deve configurar tanto as dependências Java quanto as bibliotecas nativas.

  • Arquivos da camada Java

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

  • Bibliotecas nativas (.so)

    Coloque as bibliotecas nativas fornecidas pelo EasyAR por ABI no caminho abaixo, 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 sob o diretório include no EasyAR SDK para o caminho abaixo, ou para o caminho especificado por Android.mk/CMakeLists.txt.

    app/src/main/jni/easyar/

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

Notas de configuração do Gradle

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

Adicione o seguinte em app/build.gradle:

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

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

Configuração do NDK

Declarar EasyAR como biblioteca prebuilt

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)

Vincular EasyAR e bibliotecas do sistema

LOCAL_SHARED_LIBRARIES += EasyAR

# OpenGL ES (required)
LOCAL_LDLIBS += -lGLESv3

EasyAR requer pelo menos OpenGL ES 2.0 em runtime. OpenGL ES 3.0 (GLESv3) é recomendado.

Especificar arquiteturas ABI

Especifique ABI explicitamente em app/build.gradle para evitar empacotar 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 do AndroidManifest

EasyAR Sense requer as seguintes permissões. Permissões ausentes causarão 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>

Inicializar EasyAR

Chame Engine.initialize quando a aplicação iniciar para inicializar.

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 recursos relacionados ao EasyAR.

Configuração adicional

Na plataforma Android, dependendo da versão do sistema e dos recursos usados, pode ser necessário prestar atenção também às seguintes configurações e limitações.

Configurar uso do ARCore

Se o projeto usar ARCore, consulte a documentação oficial para concluir a configuração relacionada de AndroidManifest.xml e build.gradle.

Além disso, antes de inicializar EasyAR, é necessário carregar explicitamente a native library do ARCore:

System.loadLibrary("arcore_sdk_c");
Nota

Ao usar versões anteriores ao ARCore v1.19.0, ARCore não poderá ser detectado no Android 11. Isso ocorre porque Android 11 introduziu restrições de app visibility, e o nome do package ARCore precisa ser declarado em AndroidManifest.xml.

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

Configurar obfuscation (ProGuard)

Se obfuscation estiver ativado para código Java, você precisa excluir o namespace cn.easyar.

EasyAR Sense usa em runtime class name reflection para obter Java types por JNI. Se classes sob cn.easyar forem obfuscated ou renomeadas, undefined behavior pode ocorrer.

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

As regras ProGuard acima já estão incluídas na aar library do EasyAR, então normalmente não é necessário configurar novamente.

Scoped Storage

O mecanismo Scoped Storage introduzido a partir do Android 10 afeta algumas APIs que dependem de file paths. Isso ocorre porque non-media paths sob /sdcard, como diretórios personalizados, não podem ser acessados diretamente no Android 10. O impacto no EasyAR aparece em algumas APIs que precisam receber file paths, como screen recording, que no Android 10 não suportam leitura e escrita direta de media paths, mas funcionam normalmente no Android 11.

Soluções:

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

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

  • Solução recomendada

    • Usar apenas app internal storage
    • Ou trocar dados com media paths por meio do MediaStore

Android Gradle Plugin e NDK

A partir do NDK r22, o linker LLD é usado por padrão e precisa ser usado com llvm-strip; isso é incompatível com a ferramenta strip integrada em versões do Android Gradle Plugin anteriores à 4.0. Soluções:

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

Limite de comprimento de path no Windows

No Windows, se o comprimento absoluto do path de qualquer arquivo no projeto, incluindo arquivos temporários gerados durante o build, exceder 260 caracteres, o build do Android Studio pode falhar.

Soluções:

  • Colocar o projeto em um path mais curto, como C:\user\project
  • Evitar níveis de diretório profundos demais

Leitura adicional