Table of Contents

EasyAR-Funktionen in einer Android-Anwendung aktivieren

Dieses Kapitel beschreibt, wie ein Android-Projekt für EasyAR in Android Studio konfiguriert wird, ohne eine 3D engine wie Unity zu verwenden.

Vorbereitung

Bevor Sie beginnen, müssen Sie Folgendes vorbereiten:

  • Die neueste Version von Android Studio

  • JDK 8/11/17

  • Android Gradle Plugin 4.0 oder höher

  • Android NDK r28 oder höher

  • Eine EasyAR-Autorisierungslizenz erhalten

  • Eine EasyAR Sense Release-Version auswählen und herunterladen

Anmerkung

Nicht alle Android-Geräte unterstützen alle Funktionen von EasyAR Sense. Einige Funktionen hängen von zusätzlichem hardware oder zusätzlicher Konfiguration ab. Details finden Sie in der Liste der von der jeweiligen Funktion unterstützten Geräte.

EasyAR Sense for Android importieren

Dieser Abschnitt beschreibt, wie EasyAR Sense SDK in ein Android-Projekt ohne Unity importiert wird. EasyAR Sense bietet Java- und C++ API und unterstützt Kotlin, sodass Sie mit der Sprache entwickeln können, mit der Sie am vertrautesten sind.

Da sich Konfigurationsmethoden zwischen verschiedenen IDEs unterscheiden können, wird hier nur die typische Konfiguration auf Basis von Android Studio + Gradle beschrieben.

API-Verwendungsmethode auswählen

EasyAR Sense for Android bietet zwei Methoden zur API-Verwendung:

  • Nur die Java API verwenden
  • Java- und C++-APIs verwenden

Wählen Sie entsprechend den Projektanforderungen eine davon für die Konfiguration aus.

Nur die Java API verwenden

Wenn nur die Java API von EasyAR verwendet wird, ist keine NDK-Konfiguration erforderlich.

Legen Sie EasyAR.aar in app/libs/ oder im von Gradle angegebenen Verzeichnis ab.

Java- und C++-APIs verwenden

Wenn Sie gleichzeitig die C++ API von EasyAR verwenden müssen, müssen sowohl Java-Abhängigkeiten als auch native Bibliotheken konfiguriert werden.

  • Dateien der Java-Schicht

    Legen Sie EasyAR.jar in app/libs/ oder im von Gradle angegebenen Pfad ab.

  • Native Bibliotheken (.so)

    Legen Sie die von EasyAR bereitgestellten nativen Bibliotheken nach ABI unter dem folgenden Pfad oder im von Gradle angegebenen Pfad ab.

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

  • C++-Headerdateien

    Kopieren Sie den Ordner easyar aus dem Verzeichnis include im EasyAR SDK in den folgenden Pfad oder in den von Android.mk/CMakeLists.txt angegebenen Pfad.

    app/src/main/jni/easyar/

    Der Headerdateipfad muss in Android.mk oder CMakeLists.txt explizit angegeben werden.

Hinweise zur Gradle-Konfiguration

Wenn Sie die C++ API verwenden, müssen Sie Native Build in Gradle aktivieren. Wenn Sie nur die Java API verwenden, ist keine Konfiguration erforderlich. Sie können dies mit ndk-build (Android.mk) konfigurieren.

Fügen Sie in app/build.gradle Folgendes hinzu:

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

Wenn Sie CMake verwenden, lesen Sie zur Konfiguration die offizielle Google-Dokumentation.

NDK-Konfiguration

EasyAR als vorkompilierte Bibliothek deklarieren

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)

EasyAR und Systembibliotheken linken

LOCAL_SHARED_LIBRARIES += EasyAR

# OpenGL ES (required)
LOCAL_LDLIBS += -lGLESv3

EasyAR benötigt zur Laufzeit mindestens OpenGL ES 2.0. OpenGL ES 3.0 (GLESv3) wird empfohlen.

ABI-Architekturen angeben

Geben Sie ABI in app/build.gradle explizit an, um das Paketieren ungültiger Architekturen zu vermeiden:

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

Wenn nur eine Architektur benötigt wird, behalten Sie nur den entsprechenden Eintrag bei.

AndroidManifest-Berechtigungskonfiguration

EasyAR Sense benötigt die folgenden Berechtigungen. Fehlende Berechtigungen führen zu Initialisierungsfehlern oder schwarzem Bildschirm:

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

Vollständiges Beispiel:

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

Rufen Sie beim Start der Anwendung Engine.initialize auf, um zu initialisieren.

Beispiel (Java):

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

Die Initialisierung muss abgeschlossen sein, bevor EasyAR-bezogene Funktionen verwendet werden.

Zusätzliche Konfiguration

Auf der Android-Plattform müssen je nach Systemversion und verwendeten Funktionen möglicherweise auch die folgenden Konfigurationen und Einschränkungen beachtet werden.

ARCore-Verwendung konfigurieren

Wenn das Projekt ARCore verwendet, lesen Sie die offizielle Dokumentation, um die zugehörige Konfiguration von AndroidManifest.xml und build.gradle abzuschließen.

Außerdem muss vor der Initialisierung von EasyAR die native library von ARCore explizit geladen werden:

System.loadLibrary("arcore_sdk_c");
Anmerkung

Bei Verwendung von Versionen vor ARCore v1.19.0 kann ARCore unter Android 11 nicht erkannt werden. Dies liegt daran, dass Android 11 Einschränkungen der app visibility eingeführt hat und der ARCore-package-Name in AndroidManifest.xml deklariert werden muss.

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

Obfuscation konfigurieren (ProGuard)

Wenn obfuscation für Java-Code aktiviert ist, müssen Sie den namespace cn.easyar ausschließen.

EasyAR Sense verwendet zur Laufzeit über JNI class name reflection, um Java types zu erhalten. Wenn Klassen unter cn.easyar obfuscated oder umbenannt werden, kann undefined behavior auftreten.

Grundregeln

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

Empfohlene präzise Regeln

-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

Die obigen ProGuard-Regeln sind bereits in der aar library von EasyAR enthalten, daher ist eine wiederholte Konfiguration normalerweise nicht erforderlich.

Scoped Storage

Der ab Android 10 eingeführte Mechanismus Scoped Storage wirkt sich auf einige APIs aus, die von file paths abhängen. Dies liegt daran, dass non-media paths unter /sdcard, etwa benutzerdefinierte Verzeichnisse, unter Android 10 nicht direkt zugänglich sind. Die Auswirkung auf EasyAR besteht darin, dass einige APIs, die file paths benötigen, etwa screen recording, unter Android 10 das direkte Lesen und Schreiben von media paths nicht unterstützen, unter Android 11 jedoch normal funktionieren.

Lösungen:

  • Einfache Lösung (Android 10) Scoped Storage in AndroidManifest.xml deaktivieren:

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

  • Empfohlene Lösung

    • Nur app internal storage verwenden
    • Oder Daten über MediaStore mit media paths austauschen

Android Gradle Plugin und NDK

Seit NDK r22 wird standardmäßig der LLD linker verwendet und muss zusammen mit llvm-strip genutzt werden; dies ist nicht kompatibel mit dem integrierten strip tool in Android Gradle Plugin-Versionen unter 4.0. Lösungen:

  • Auf Android Gradle Plugin 4.0 oder höher aktualisieren
  • Oder doNotStrip in packagingOptions verwenden, um stripping zu deaktivieren (nicht empfohlen)

Windows-Pfadlängenbeschränkung

Unter Windows kann der Android Studio build fehlschlagen, wenn die absolute Pfadlänge einer beliebigen Datei im Projekt, einschließlich während des build erzeugter temporärer Dateien, 260 Zeichen überschreitet.

Lösungen:

  • Das Projekt in einem kürzeren Pfad ablegen, z. B. C:\user\project
  • Zu tiefe Verzeichnisebenen vermeiden

Weiterführende Informationen