Table of Contents

Включение функций EasyAR в приложении для Android

В этой главе описывается, как настроить проект Android для EasyAR в Android Studio без использования 3D-движков, таких как Unity.

Подготовка

Перед началом вам потребуется:

Примечание

Не все устройства Android поддерживают все функции EasyAR Sense. Некоторые функции требуют дополнительного оборудования или конфигурации. Подробности см. в списках поддерживаемых устройств для соответствующих функций.

Импорт EasyAR Sense для Android

В этом разделе объясняется, как импортировать SDK EasyAR Sense в проект Android, не использующий Unity. EasyAR Sense предоставляет API на Java и C++, а также поддерживает Kotlin, что позволяет разрабатывать на наиболее удобном языке.

Поскольку настройка может отличаться в разных IDE, здесь описывается типичный способ настройки на основе Android Studio + Gradle.

Выбор способа использования API

EasyAR Sense for Android предоставляет два способа использования API:

  • Только Java API
  • Java и C++ API

Выберите один из вариантов настройки в зависимости от требований проекта.

Только Java API

При использовании только Java API от EasyAR настройка NDK не требуется.

Поместите EasyAR.aar в app/libs/ или каталог, указанный в Gradle.

Использование Java и C++ API

При необходимости использования C++ API от EasyAR требуется настроить зависимости Java и нативные библиотеки.

  • Файлы Java-уровня

    Поместите EasyAR.jar в app/libs/ или путь, указанный в Gradle.

  • Нативные библиотеки (.so)

    Поместите предоставленные нативные библиотеки EasyAR по ABI в следующий путь или путь, указанный в Gradle.

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

  • C++ заголовочные файлы

    Скопируйте папку easyar из каталога include в SDK EasyAR в следующий путь или путь, указанный в Android.mk/CMakeLists.txt.

    app/src/main/jni/easyar/

    Путь к заголовочным файлам должен быть явно указан в Android.mk или CMakeLists.txt.

Пояснение к настройке Gradle

При использовании C++ API необходимо включить Native Build в Gradle, для только Java API настройка не требуется. Вы можете использовать ndk-build (Android.mk) для настройки.

Добавьте в app/build.gradle:

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

При использовании CMake обратитесь к официальной документации Google.

Настройка NDK

Объявление EasyAR как предварительно скомпилированной библиотеки

include $(CLEAR_VARS)

# Убедитесь, что путь указывает на каталог текущей ABI в jniLibs
LOCAL_PATH := $(LOCAL_PATH_TOP)/../jniLibs/$(TARGET_ARCH_ABI)

LOCAL_MODULE := EasyAR
LOCAL_SRC_FILES := libEasyAR.so

include $(PREBUILT_SHARED_LIBRARY)

Связывание EasyAR с системными библиотеками

LOCAL_SHARED_LIBRARIES += EasyAR

# OpenGL ES (обязательно)
LOCAL_LDLIBS += -lGLESv3

EasyAR требует как минимум OpenGL ES 2.0, рекомендуется OpenGL ES 3.0 (GLESv3).

Указание архитектуры ABI

Явно укажите ABI в app/build.gradle, чтобы избежать включения неактивных архитектур:

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

Если требуется только одна архитектура, оставьте соответствующую запись.

Настройка разрешений в AndroidManifest

EasyAR Sense требует следующие разрешения, их отсутствие вызовет сбой инициализации или чёрный экран:

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

Полный пример:

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

Инициализация EasyAR

Вызовите Engine.initialize при запуске приложения для инициализации.

Пример (Java):

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Engine.initialize(this, key);
}
Примечание

Инициализация должна быть завершена до использования функций EasyAR.

Дополнительная настройка

На платформе Android, в зависимости от версии системы и используемых функций, могут потребоваться следующие настройки и ограничения.

Настройка использования ARCore

Если в проекте используется ARCore, обратитесь к его официальной документации для настройки AndroidManifest.xml и build.gradle.

Кроме того, перед инициализацией EasyAR необходимо явно загрузить нативную библиотеку ARCore:

System.loadLibrary("arcore_sdk_c");
Примечание

При использовании ARCore версии ниже v1.19.0 обнаружение на Android 11 будет невозможно. Это связано с ограничениями видимости приложений, введенными в Android 11. Требуется объявить имя пакета ARCore в AndroidManifest.xml.

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

Настройка обфускации (ProGuard)

Если включена обфускация Java-кода, необходимо исключить пространство имен cn.easyar.

EasyAR Sense во время выполнения использует отражение имен классов через JNI для получения Java-типов. Если классы в cn.easyar обфусцированы или переименованы, это может привести к неопределенному поведению.

Базовые правила

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

Рекомендуемые точные правила

-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

Эти правила ProGuard уже включены в aar-библиотеку EasyAR, и обычно не требуют повторной настройки.

Ограниченное хранилище (Scoped Storage)

Механизм ограниченного хранилища (Scoped Storage), представленный в Android 10, влияет на API, зависящие от путей к файлам. Это связано с тем, что не-медийные пути (например, пользовательские каталоги) в /sdcard становятся недоступны напрямую на Android 10. Для EasyAR это влияет на API, которым требуется передача пути к файлу (например, запись экрана). На Android 10 они не могут напрямую читать/писать в медийные пути, но на Android 11 работают нормально.

Способы решения:

  • Простой способ (Android 10) Отключите Scoped Storage в AndroidManifest.xml:

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

  • Рекомендуемый способ

    • Используйте только внутреннее хранилище приложения
    • Или обменивайтесь данными с медийными путями через MediaStore

Android Gradle Plugin и NDK

Начиная с NDK r22, по умолчанию используется линкер LLD, которому требуется llvm-strip; это несовместимо со встроенным инструментом strip в версиях Android Gradle Plugin ниже 4.0. Способы решения:

  • Обновитесь до Android Gradle Plugin 4.0 или выше
  • Или используйте doNotStrip в packagingOptions для отключения стриппинга (не рекомендуется)

Ограничение длины пути в Windows

В системе Windows, если абсолютный путь к любому файлу в проекте (включая временные файлы, созданные в процессе сборки) превышает 260 символов, это может привести к сбою сборки в Android Studio.

Способы решения:

  • Разместите проект в более коротком пути (например, C:\user\project)
  • Избегайте слишком глубокой вложенности каталогов

Дополнительные материалы