本頁面由 Cloud Translation API 翻譯而成。

Switch to English

啟用 ARCore

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

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

Google Play 服務 - AR 適用

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

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

開始 AR 工作階段前，應用程式必須：

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

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

應用程式支援 AR 功能，有以下兩種設定：AR 需要和 AR 選用。

必須提供 AR

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

Google Play 商店只能在支援 ARCore 的裝置中使用 AR 適用的應用程式。
當使用者安裝 AR 需要的應用程式時，Google Play 商店會自動安裝 AR 適用的 Google Play 服務。不過，您的應用程式仍須執行額外的執行階段檢查，以更新 AR 適用的 Google Play 服務，或是手動解除安裝。

詳情請參閱在 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 程式庫，請執行下列步驟：

請確認您的 project's build.gradle 檔案包含 Google 的 Maven 存放區。
```
allprojects {
repositories {
    google()
        ...
```

從 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)
      }
  }

設定原生建構標記，將位置傳送至外部建構工具。

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

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

新增 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'
      ...
 }

參照 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 參考資料。