Table of Contents

EasyAR-funktionen in Android-apps aktivieren

Dieses Kapitel erklärt, wie Sie ein EasyAR-Android-projekt in Android Studio konfigurieren, ohne 3D-engines wie Unity zu verwenden.

Vorbereitungen

Bevor Sie beginnen, benötigen Sie:

  • Die neueste Version von Android Studio
  • JDK 8/11/17
  • Android Gradle Plugin 4.0 oder höher
  • Android NDK r28 oder höher
  • Ein EasyAR-lizenzschlüssel
  • Wahl einer EasyAR Sense release-version und download
Anmerkung

Nicht alle Android-geräte unterstützen alle Funktionen von EasyAR Sense. Einige Funktionen benötigen zusätzliche hardware oder konfiguration. Konsultieren Sie die unterstützten gerätelisten für die jeweilige funktion.

EasyAR Sense für Android importieren

Dieser abschnitt erklärt, wie Sie das EasyAR Sense SDK in ein nicht-Unity Android-projekt importieren. EasyAR Sense bietet Java- und C++-APIs und unterstützt Kotlin. Sie können mit Ihrer bevorzugten sprache entwickeln.

Da die konfiguration zwischen verschiedenen IDEs variieren kann, wird hier nur die typische konfiguration mit Android Studio + Gradle beschrieben.

Auswahl der API-Nutzungsweise

EasyAR Sense für Android bietet zwei API-Nutzungsweisen:

  • Nur Java API verwenden
  • Java und C++ API verwenden

Bitte wählen Sie basierend auf Ihren Projektanforderungen eine der Konfigurationen aus.

Nur Java API verwenden

Bei ausschließlicher Verwendung der Java API von EasyAR ist keine NDK-Konfiguration erforderlich.

Platzieren Sie EasyAR.aar in app/libs/ oder im von Gradle festgelegten Verzeichnis.

Java und C++ API verwenden

Bei gleichzeitiger Nutzung der C++ API von EasyAR müssen sowohl Java-Abhängigkeiten als auch native Bibliotheken konfiguriert werden.

  • Java-Dateien

    Platzieren Sie EasyAR.jar in app/libs/ oder im von Gradle festgelegten Pfad.

  • Native Bibliotheken (.so)

    Platzieren Sie die nativen Bibliotheken von EasyAR nach ABI im folgenden Pfad oder im von Gradle festgelegten Pfad.

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

  • C++-Headerdateien

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

    app/src/main/jni/easyar/

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

Gradle-Konfigurationshinweise

Wenn Sie die C++ API verwenden, müssen Sie Native Build in Gradle aktivieren. Nur für Java API nicht erforderlich. Sie können ndk-build (Android.mk) zur Konfiguration verwenden.

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

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

Bei Verwendung von CMake konsultieren Sie bitte die offizielle Google-Dokumentation.

NDK-Konfiguration

Deklaration von EasyAR als vorkompilierte Bibliothek

include $(CLEAR_VARS)

# Sicherstellen, dass dieser Pfad zum aktuellen ABI-Verzeichnis in jniLibs zeigt
LOCAL_PATH := $(LOCAL_PATH_TOP)/../jniLibs/$(TARGET_ARCH_ABI)

LOCAL_MODULE := EasyAR
LOCAL_SRC_FILES := libEasyAR.so

include $(PREBUILT_SHARED_LIBRARY)

Verknüpfung von EasyAR mit Systembibliotheken

LOCAL_SHARED_LIBRARIES += EasyAR

# OpenGL ES (erforderlich)
LOCAL_LDLIBS += -lGLESv3

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

Festlegen der ABI-Architektur

Legen Sie ABI explizit in app/build.gradle fest, um das Paketieren inaktiver Architekturen zu vermeiden:

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

Wenn nur eine Architektur benötigt wird, können Sie die entsprechende Option beibehalten.

AndroidManifest-Berechtigungskonfiguration

EasyAR Sense benötigt folgende 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>

Initialisierung von EasyAR

Rufen Sie beim Start der Anwendung Engine.initialize zur Initialisierung auf.

Beispiel (Java):

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

Die Initialisierung muss vor der Verwendung von EasyAR-Funktionen abgeschlossen sein.

Zusätzliche konfiguration

Auf der Android-plattform können je nach systemversion und verwendeten funktionen zusätzliche konfigurationen und einschränkungen erforderlich sein.

Konfiguration und verwendung von ARCore

Wenn ARCore im Projekt verwendet wird, konsultieren Sie bitte die offizielle Dokumentation, um die entsprechende Konfiguration in AndroidManifest.xml und build.gradle abzuschließen.

Darüber hinaus muss die native Bibliothek von ARCore explizit geladen werden, bevor EasyAR initialisiert wird:

System.loadLibrary("arcore_sdk_c");
Anmerkung

Bei Verwendung von ARCore Versionen vor v1.19.0 wird es auf Android 11 nicht erkannt werden. Dies liegt an den eingeführten Einschränkungen der App-Sichtbarkeit ab Android 11, die eine Deklaration des ARCore-Paketnamens in AndroidManifest.xml erfordern.

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

Konfiguration von ProGuard

Wenn die Verschleierung (Obfuskation) von Java-Code aktiviert ist, muss der Namensraum cn.easyar ausgeschlossen werden.

EasyAR Sense verwendet zur Laufzeit über JNI Reflektion von Klassennamen, um Java-Typen zu erhalten. Wenn Klassen unter cn.easyar verschleiert oder umbenannt werden, kann dies zu undefiniertem Verhalten führen.

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

Diese ProGuard-Regeln sind bereits in der aar-Bibliothek von EasyAR enthalten und müssen normalerweise nicht erneut konfiguriert werden.

Scoped Storage

Der ab Android 10 eingeführte Mechanismus Scoped Storage (partitionierter Speicher) beeinflusst APIs, die von Dateipfaden abhängen. Grund ist, dass nicht-mediale Pfade unter /sdcard (wie benutzerdefinierte Verzeichnisse) auf Android 10 nicht direkt zugänglich sind. Dies betrifft EasyAR-APIs, die Dateipfade erwarten (z.B. Bildschirmaufzeichnung). Auf Android 10 unterstützen sie kein direktes Lesen/Schreiben in Medienpfaden, funktionieren aber auf Android 11.

Lösungsansätze:

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

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

  • Empfohlene Lösung

    • Nur internen App-Speicher verwenden
    • Oder Datenaustausch mit Medienpfaden über MediaStore

Android Gradle Plugin und NDK

Ab NDK r22 verwendet der Standard-Linker LLD und erfordert llvm-strip; dies ist inkompatibel mit dem in Android Gradle Plugin Versionen unter 4.0 integrierten strip-Tool. Lösungsansätze:

  • Upgrade auf Android Gradle Plugin 4.0 oder höher
  • Oder Deaktivieren des Stripings via doNotStrip in packagingOptions (nicht empfohlen)

Windows-Pfadlängenbeschränkung

Auf Windows-Systemen kann der Build in Android Studio fehlschlagen, wenn der absolute Pfad einer beliebigen Datei im Projekt (einschließlich temporärer Build-Dateien) 260 Zeichen überschreitet.

Lösungsansätze:

  • Projekt in einem kürzeren Pfad ablegen (z.B. C:\user\project)
  • Vermeiden übermäßig tiefer Verzeichnishierarchien

Weiterführende literatur