Android NDK アプリで AR を有効にする

AR を有効にすると、新規または既存のアプリで拡張現実機能を利用できます。

AR 対応を必須または AR オプションにアプリを設定する

個々のデバイスの容量を節約するため、すべての AR 機能は Google Play 開発者サービス（AR）というアプリに保存されます。このアプリは Google Play ストアで別途更新されます。AR 機能を使用する Android アプリは、ARCore SDK を使用して Google Play 開発者サービス（AR）と通信します。AR 機能をサポートするアプリは、[AR 対応が必要] と [AR オプション] の 2 つの方法で設定できます。この指定により、アプリが AR 用 Google Play 開発者サービス アプリとどのようにやり取りするかが決まります。

[AR 必須] アプリは ARCore なしでは機能しません。Google Play 開発者サービス（AR）がインストールされた ARCore 対応デバイスが必要です。

• Google Play ストアでは、ARCore をサポートするデバイスでのみ AR 対応アプリを利用できます。
• ユーザーが AR 必須アプリをインストールすると、Google Play ストアからユーザーのデバイスに Google Play 開発者サービス（AR）が自動的にインストールされます。ただし、Google Play 開発者サービス（AR）が古い場合や手動でアンインストールした場合は、アプリで追加のランタイム チェックを行う必要があります。

AR Optional アプリは、ARCore を使用して既存の機能を強化しています。これには、Google Play 開発者サービス（AR）がインストールされている ARCore 対応デバイスでのみ有効になる、オプションの AR 機能があります。

• AR Optional アプリは、ARCore をサポートしていないデバイスにインストールして実行できます。
• ユーザーが AR Optional アプリをインストールしても、Google Play ストアからデバイスに AR 用 Google Play 開発者サービスが自動的にインストールされることはありません。

	AR が必要	AR（オプション）
AR 機能の使用	アプリの基本機能には ARCore が必要です。	ARCore はアプリの機能を強化します。ARCore サポートなしでもアプリを実行できます。
Google Play ストアの公開設定	Google Play ストアに、ARCore をサポートするデバイスでのみアプリが掲載されている。	アプリは通常の掲載手順に沿っています。
AR 用 Google Play 開発者サービスのインストール方法	Google Play ストアにより、アプリとともに Google Play 開発者サービス（AR）がインストールされます。	アプリは ArCoreApk.requestInstall() を使用して ARCore をダウンロードしてインストールします。
Android の minSdkVersion の要件	Android 7.0（API レベル 24）	Android 4.4（API レベル 19）。AR 機能を実行するには、Android 7.0（API レベル 24）以上が必要です。
ARCore のサポートとインストールのステータスを確認するには、ArCoreApk_checkAvailability() または ArCoreApk_checkAvailabilityAsync() を使用する必要があります
Google Play 開発者サービス（AR）をインストールするには、 ArCoreApk.requestInstall() を使用する必要があります。

アプリを AR 必須または AR オプションにするには、AndroidManifest.xml を更新して次のエントリを追加します。

AR が必要

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

<!-- Limits app visibility in the Google Play Store to ARCore supported devices
     (https://developers.google.com/ar/devices). -->
<uses-feature android:name="android.hardware.camera.ar" />

<application …>
    …

    <!-- "AR Required" app, requires "Google Play Services for AR" (ARCore)
         to be installed, as the app does not include any non-AR features. -->
    <meta-data android:name="com.google.ar.core" android:value="required" />
</application>

AR（オプション）

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

<!-- If your app was previously AR Required, don't forget to remove the
     `<uses-feature android:name="android.hardware.camera.ar" />` entry, as
     this would limit app visibility in the Google Play Store to only
     ARCore supported devices. -->

<application …>
    …

    <!-- "AR Optional" app, contains non-AR features that can be used when
         "Google Play Services for AR" (ARCore) is not available. -->
    <meta-data android:name="com.google.ar.core" android:value="optional" />
</application>

次に、アプリの build.gradle を変更して、24 以上の minSdkVersion を指定します。

 android {
     defaultConfig {
         …
         minSdkVersion 24
     }
 }

ビルド依存関係を追加する

1. プロジェクトの build.gradle ファイルに Google の Maven リポジトリが含まれていることを確認します。

   allprojects {
       repositories {
           google()
           …
       }
   }
   

2. モジュールの build.gradle ファイルにカスタムタスクを追加して、ARCore AAR ファイルからインクルードされたネイティブ ライブラリを抽出します。これにより、C または C++ プロジェクトで直接参照できます。

3. app/build ディレクトリで、ネイティブ ライブラリの抽出先となるディレクトリを示す変数を定義します。

4. データと抽出タスクを保持する Gradle 構成を作成します。

   /*
   The ARCore AAR library contains native shared libraries that are
   extracted before building to a temporary directory.
   */
   def arcore_libpath = "${buildDir}/arcore-native"
   
   // Create a configuration to mark which aars to extract .so files from
   configurations { natives }
   

5. AAR ファイルからネイティブ ライブラリをコピーするタスクを作成し、ビルドの依存関係に追加します。

   // Extracts the shared libraries from AARs in the native configuration
   // so that NDK builds can access these libraries.
   task extractNativeLibraries() {
      // Extract every time.
      outputs.upToDateWhen { false }
   
      doFirst {
           configurations.natives.files.each { f ->
               copy {
                   from zipTree(f)
                   into arcore_libpath
                   include "jni/**/*"
               }
           }
       }
   }
   
   tasks.whenTaskAdded {
       task-> if (task.name.contains("external") && !task.name.contains("Clean")) {
           task.dependsOn(extractNativeLibraries)
       }
   }
   

6. その場所を外部ビルドツールに渡すようにネイティブ ビルドフラグを構成します。

   // From the sample app.
   externalNativeBuild {
       cmake {
           cppFlags "-std=c++11", "-Wall"
           arguments "-DANDROID_STL=c++_static",
                   "-DARCORE_LIBPATH=${arcore_libpath}/jni",
                   "-DARCORE_INCLUDE=${project.rootDir}/../../libraries/include"
       }
   }
   

7. Java ライブラリとネイティブ ライブラリの両方の依存関係を追加します。

   dependencies {
        ...
        // Add Java and native dependencies to the ARCore library.
        implementation 'com.google.ar:core:1.33.0'
        natives 'com.google.ar:core:1.33.0'
        ...
   }
   

8. CMakeLists.txt でネイティブ ライブラリを参照します。

   # Import the ARCore library.
   add_library(arcore SHARED IMPORTED)
   set_target_properties(arcore PROPERTIES IMPORTED_LOCATION
                 ${ARCORE_LIBPATH}/${ANDROID_ABI}/libarcore_sdk_c.so
                 INTERFACE_INCLUDE_DIRECTORIES ${ARCORE_INCLUDE}
   )
   

ランタイム チェックを実行する

アプリの AR 機能がスムーズに実行されるように、実行時に以下を行います。

ARCore がサポートされているかどうかを確認する

AR 必須アプリと AR オプションアプリの両方で、ArCoreApk_checkAvailability() または ArCoreApk_checkAvailabilityAsync() を使用して、現在のデバイスが ARCore をサポートしているかどうかを判断する必要があります。ARCore をサポートしていないデバイスでは、アプリは AR 関連の機能を無効にし、関連する UI 要素を非表示にする必要があります。

Android NDK アプリでは、Java ArCoreApk クラスを使用して、ネイティブ C ARCore Session API で互換性を確認し、インストールを管理できます。アプリの構造によっては、大量のエラー処理とユーザー インターフェース操作が関係するため、この方法は ArCoreApk_ 関数を使用するよりも簡単な場合があります。

void maybeEnableArButton(JNIEnv env, jobject context) {
  // Likely called from Activity.onCreate() of an activity with AR buttons.
  ArAvailability availability
  ArCoreApk_checkAvailability(env, context, &availability);
  if (availability == AR_AVAILABILITY_UNKNOWN_CHECKING) {
    // Set a timer to call maybeEnableArButton() again after about 200ms.
  }
  if (availability == AR_AVAILABILITY_SUPPORTED_NOT_INSTALLED ||
      availability == AR_AVAILABILITY_SUPPORTED_APK_TOO_OLD ||
      availability == AR_AVAILABILITY_SUPPORTED_INSTALLED) {
    // Show or enable the AR button.
  } else {
    // Hide or disable the AR button.
  }
}

Google Play 開発者サービス（AR）が AR 必須アプリと一緒にインストールされていても、サポートされていないデバイスを使用しているユーザーが外部ソースからインストールする可能性があります。ArCoreApk_checkAvailability() または ArCoreApk_checkAvailabilityAsync() を使用して ARCore に対応しているかどうかを確認し、一貫性のあるエクスペリエンスを実現します。

ArCoreApk_checkAvailability() は、デバイスが ARCore をサポートしているかどうかを判断するために、ネットワーク リソースへのクエリが必要になることがあります。この期間中は AR_AVAILABILITY_UNKNOWN_CHECKING が返されます。認識されるレイテンシとポップインを減らすには、アプリはライフサイクルの早い段階で ArCoreApk_checkAvailability() を 1 回呼び出してクエリを開始する必要があります。戻り値は無視されます。このようにして、AR 入力の UI 要素が表示される可能性があるときに、キャッシュされた結果をすぐに利用できます。

Google Play 開発者サービス（AR）がインストールされているかどうかを確認する

AR 必須アプリと AR オプションアプリはどちらも、ARCore セッションを作成する前に ArCoreApk.requestInstall() を使用して、互換性のあるバージョンの Google Play 開発者サービス（AR）が（まだ）インストールされていることを確認し、必要な ARCore デバイス プロファイル データがすべてダウンロードされていることを確認する必要があります。

// Tracks if an installation request has already been triggered.
bool install_requested_;

void nativeOnCreate() {
  // Do other setup here.

  install_requested_ = false;
}

void nativeOnResume(JNIEnv env, jobject activity) {
  if (ar_session_ == null) {
    bool user_requested_install = !install_requested_;

    ArInstallStatus install_status;
    // Ensure that Google Play Services for AR and ARCore device profile data are
    // installed and up to date.
    ArStatus error = ArCoreApk_requestInstall(
        env, activity, user_requested_install, &install_status);
    if (error != AR_SUCCESS) {
      // Inform user of error.
      return;
    }

    switch (install_status) {
      case AR_INSTALL_STATUS_INSTALLED:
        break;
      case AR_INSTALL_STATUS_INSTALL_REQUESTED:
        // When this method returns AR_INSTALL_STATUS_INSTALL_REQUESTED:
        // 1. This activity will be paused.
        // 2. The user is prompted to install or update Google Play
        //    Services for AR (market://details?id=com.google.ar.core).
        // 3. ARCore downloads the latest device profile data.
        // 4. This activity is resumed. The next invocation of
        //    ArCoreApk_requestInstall() will either return
        //    AR_INSTALL_STATUS_INSTALLED or throw an exception if the
        //    installation or update did not succeed.
        install_requested_ = true;
        return;
    }

    // Request camera permissions.

    error = ArSession_create(env, context, &ar_session_);
    if (error != AR_SUCCESS) {
      // Inform user of error.
      return;
    }

    // Configure the ARCore session.
  }

  // Normal onResume behavior.
}

ユーザーのプライバシー要件を遵守する

Play ストアでアプリを公開するには、アプリが ARCore のユーザー プライバシー要件を遵守していることをご確認ください。

次のステップ

• ARCore セッションを構成する方法を確認する。