啟用 ARCore

本頁面說明如何在 Android NDK 專案中啟用 ARCore 功能。步驟如下:

  1. 在資訊清單中加入 AR 或 AR 選用功能
  2. 在專案中新增建構依附元件
  3. 執行執行階段檢查,確保裝置支援 ARCore,且已安裝 AR 適用的 Google Play 服務
  4. 確認您的應用程式符合 ARCore 的使用者隱私權規定

Google Play 服務 - AR 適用

ARCore SDK 會在已安裝 AR Google Play 服務 AR (ARCore) 的支援 ARCore 的裝置上提供 AR 功能。

Google Play 服務 - AR 適用會在大多數支援的裝置上自動安裝及更新。

開始 AR 工作階段前,應用程式必須:

  1. 呼叫 ArCoreApk_checkAvailability,確認系統支援 ARCore。
  2. 呼叫 ArCoreApk_requestInstall,檢查是否已安裝並安裝最新的 ARCore 裝置 Google Play 服務,且已下載必要的 ARCore 裝置設定檔資料。

在資訊清單中新增 AR 或 AR 選用

應用程式支援 AR 功能,有以下兩種設定:AR 需要AR 選用

必須提供 AR

如要使用 AR 必要功能,而且已安裝 ARCore 支援的裝置,且必須安裝 ARGoogle Play 服務才能使用 ARCore 應用程式。

詳情請參閱在 Google Play 商店中發布 AR 應用程式一文。

如要宣告應用程式是否為 AR 規定,請修改您的 AndroidManifest.xml,以納入下列項目:

<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" android:required="true"/>

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

然後,修改應用程式的 build.gradle,以指定至少 24 的 minSdkVersion

android {
    defaultConfig {
        …
        minSdkVersion 24
    }
}

AR 選用

AR 非必要 應用程式提供選用的 AR 功能,只會在 ARCore 支援的裝置 AR 適用的 Google Play 服務 上啟用。

  • AR 非必要應用程式可安裝在不支援 ARCore 的裝置上,並執行。

  • 使用者安裝 AR 選擇性應用程式時,Google Play 商店「不會」自動安裝應用程式。AR 適用 Google Play 服務

如要宣告應用程式為 AR 選用,請修改 AndroidManifest.xml 以納入以下項目:

<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,以指定至少 14 的 minSdkVersion

android {
    defaultConfig {
        …
        minSdkVersion 14
    }
}

新增版本相依性

如要在 Android Studio 專案中新增 ARCore 程式庫,請執行下列步驟:

  1. 請確認您的 project's build.gradle 檔案包含 Google 的 Maven 存放區。

    allprojects {
    repositories {
        google()
            ...
    
  2. 從 ARCore aar 中擷取原生程式庫。

    原生程式庫已納入 ARCore aar 檔案中。要做為 C/C++ 專案的一部分使用,就必須從封存檔案中擷取這些項目,以便直接參照。如要這麼做,請將自訂工作新增至模組的 build.gradle 檔案 (例如 app/build.gradle)。

    ARCore 的標頭檔案 arcore_c_api.h 包含在 GitHub SDK 專案中:

    定義變數至 app/build 目錄中的目錄。系統會將原生程式庫解壓縮至這個目錄。此外,您也可以建立 gradle 設定來存放擷取工作和資料。

    /*
    The ARCore aar library contains the native shared libraries. These 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 }
    
    

    建立工作以從 aar 檔案複製原生程式庫,並將其新增至建構依附元件

      // Extracts the shared libraries from aars in the natives configuration.
      // This is done 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)
          }
      }
    
  3. 設定原生建構標記,將位置傳送至外部建構工具。

    這個範例來自 GitHub 專案中的範例。

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

  4. 新增 Java 和原生程式庫的依附元件。

     dependencies {
          ...
          // Add java and native dependencies on the ARCore library
          implementation 'com.google.ar:core:1.31.0'
          natives 'com.google.ar:core:1.31.0'
          ...
     }
    
  5. 參照 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}
    )
    

執行執行階段檢查

檢查是否已安裝 ARCore

所有 AR 應用程式都必須呼叫 ArCoreApk_requestInstall(),才能建立 ARCore 工作階段。ArCoreApk_requestInstall() 會檢查已安裝的 Google Play 服務 AR 適用版本 (可能是版本過舊,或已由使用者手動移除),並在使用者沒有安裝服務時提示使用者安裝該服務。

// Tracks if we have already triggered an installation request.
bool install_requested_;

void nativeOnCreate() {
  // other setup

  install_requested_ = false;
}

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

    ArInstallStatus install_status;
    // Ensure 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 session
  }

  // Normal onResume behavior
}

如果 ArCoreApk_requestInstall() 傳回 AR_INSTALL_STATUS_INSTALL_REQUESTED,系統就會暫停目前的活動,並提示使用者安裝或更新服務。活動 onResume() 會在使用者返回活動時再次執行。

檢查是否支援 ARCore (僅限 AR 選用)

AR 選用應用程式可使用 ArCoreApk_checkAvailability() 來判斷目前的裝置是否支援 ARCore。在不支援 ARCore 的裝置上,應用程式應停用 AR 相關功能並隱藏相關的 UI 元素。

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/enable AR button.
  } else {
    // Hide/disable AR button.
  }
}

接著,當使用者想要使用 AR 功能時,應用程式就應該確認已安裝 AR 適用的 Google Play 服務。最簡單的做法是啟動符合上述 AR 模式模式的活動。

遵守使用者隱私規定

確認您的應用程式符合 ARCore 的使用者隱私權規定

後續步驟

閱讀範例應用程式的程式碼和註解,以及 C API 參考資料