Android アプリで EasyAR 機能を有効化

この章では、Unity などの 3D エンジンを使用せずに、Android Studio で EasyAR の Android プロジェクトを設定する方法を説明します。

準備作業

開始前に、以下を準備する必要があります:

• Android Studio の最新バージョン
• JDK 8/11/17
• Android Gradle Plugin 4.0 以上
• Android NDK r28 以上
• EasyAR ライセンスキーの取得
• EasyAR Sense のリリースバージョンを選択してダウンロード

注記

すべての Android デバイスが EasyAR Sense の全機能をサポートしているわけではありません。一部の機能は追加のハードウェアや設定に依存します。詳細は各機能のサポートデバイスリストを参照してください。

EasyAR Sense for Android のインポート

このセクションでは、Unity を使用しない Android プロジェクトに EasyAR Sense SDK をインポートする方法を説明します。 EasyAR Sense は Java および C++ API を提供し、Kotlin をサポートしているため、慣れた言語で開発できます。

異なる IDE の設定方法は異なる可能性があるため、ここではAndroid Studio + Gradle ベースの典型的な設定方法のみを説明します。

API の使用方法を選択する

EasyAR Sense for Android では、API の使用法が 2 通り提供されています：

• Java API のみを使用
• Java と C++ API を併用

プロジェクトの要件に応じて、いずれかの方法を選択して設定してください。

Java API のみを使用

EasyAR の Java API のみを使用する場合、NDK の設定は不要です。

EasyAR.aar を app/libs/ または Gradle で指定されたディレクトリに配置します。

Java と C++ API を併用

EasyAR の C++ API を併用する必要がある場合、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 SDK の include ディレクトリにある easyar フォルダを、以下のパスまたは Android.mk/CMakeLists.txt で指定されたパスにコピーします。

  app/src/main/jni/easyar/
  

  ヘッダーファイルのパスは Android.mk または CMakeLists.txt で明示的に指定する必要があります。

Gradle 設定の説明

C++ API を使用する場合、Gradle で Native Build を有効にする必要があります。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)

# このパスが jniLibs 内の現在の ABI ディレクトリを指していることを確認
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 アーキテクチャの指定

無効なアーキテクチャがパッケージ化されるのを防ぐため、app/build.gradle で ABI を明示的に指定します：

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

必要なアーキテクチャが 1 つのみの場合は、対応する項目のみを保持してください。

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で導入されたアプリ可視性制限によるもので、AndroidManifest.xmlでARCoreのパッケージ名を宣言する必要があります。

<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ルールはEasyARのaarライブラリに含まれており、通常は重複して設定する必要はありません。

スコープストレージ

Android 10で導入されたスコープストレージメカニズムは、ファイルパスに依存する一部のAPIに影響を与えます。これは/sdcard以下の非メディアパス（カスタムディレクトリなど）がAndroid 10で直接アクセスできなくなるためです。EasyARへの影響は、ファイルパスを必要とするAPI（例：画面録画）がAndroid 10ではメディアパスへの直接読み書きをサポートしませんが、Android 11では正常に動作する点に現れます。

解決方法:

• 簡易的な方法（Android 10） AndroidManifest.xmlでスコープストレージを無効化：

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

• 推奨方法

  • アプリ内部ストレージのみを使用
  • またはMediaStoreを通じてメディアパスとデータ交換

Android Gradle PluginとNDK

NDK r22以降ではデフォルトでLLDリンカーを使用し、llvm-stripとの組み合わせが必要です。これはAndroid Gradle Plugin 4.0未満の組み込みstripツールと互換性がありません。 解決方法:

• Android Gradle Plugin 4.0以上にアップグレード
• またはpackagingOptionsでdoNotStripを使用してstrippingを無効化（非推奨）

Windowsのパス長制限

Windowsシステムでは、プロジェクト内の任意のファイル（ビルドプロセスで生成される一時ファイルを含む）の絶対パス長が260文字を超える場合、Android Studioのビルドが失敗する可能性があります。

解決方法：

• プロジェクトをより短いパスに配置（例：C:\user\project）
• 深すぎるディレクトリ階層を避ける

関連情報

• EasyAR Mega 対応デバイス
• 画像トラッキング対応デバイス
• モーショントラッキング対応デバイス
• 疎空間マッピング対応デバイス
• 密空間マッピング対応デバイス
• モーショントラッキングと EasyAR 他モジュールの関係