啟用 ARCore

本頁面介紹瞭如何在您的 Android NDK 項目中啟用 ARCore 功能。為此,您需要:

  1. 向清單添加 AR 必需或 AR 可選
  2. 添加構建依賴關係到項目
  3. 執行運行時檢查,以確保設備是ARCORE支持對AR谷歌遊戲服務被安裝在其上
  4. 確保您的應用符合ARCORE的用戶隱私要求

面向 AR 的 Google Play 服務

ARCORE的SDK使得可在AR功能ARCORE支持的設備谷歌播放服務AR安裝(ARCORE)。

適用於 AR 的 Google Play 服務會在絕大多數受支持的設備上自動安裝並保持最新狀態。

在開始 AR 會話之前,應用程序必須:

  1. 檢查ARCORE支持,通過調用ArCoreApk_checkAvailability
  2. 檢查谷歌播放服務AR的安裝和更新,並且需要ARCORE設備配置文件數據已被下載,通過調用ArCoreApk_requestInstall

向清單添加 AR 必需或 AR 可選

AR必AR可選:支持AR功能,應用程序可以通過兩種方式進行配置。

需要 AR

要使用,一個AR必需的應用程序需要ARCORE支持設備谷歌播放服務AR安裝就可以了。

  • 該谷歌Play商店使得AR只需要上的哪些應用提供設備的支持ARCORE

  • 當用戶安裝一個AR應用程序所需的谷歌Play商店會自動安裝谷歌播放服務AR 。然而,你的應用程序仍必須執行額外的運行時檢查的情況下,谷歌播放服務AR必須更新或已被手動卸載。

欲了解更多信息,請參閱發布AR應用在谷歌Play商店

要聲明你的應用程序是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指定minSdkVersion至少24:

android {
    defaultConfig {
        …
        minSdkVersion 24
    }
}

AR 可選

一個AR可選的應用程序具有可選的AR功能,這些功能僅激活在ARCORE支持的設備谷歌播放服務AR安裝。

  • AR 可選應用程序可以在不支持 ARCore 的設備上安裝和運行。

  • 當用戶安裝一個AR可選的應用程序,谷歌的Play商店也不會自動安裝谷歌播放服務AR與應用。

要聲明你的應用程序是AR可選,修改您AndroidManifest.xml包括以下項目:

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

<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指定minSdkVersion至少14:

android {
    defaultConfig {
        …
        minSdkVersion 14
    }
}

添加構建依賴項

要將 ARCore 庫添加到您的 Android Studio 項目,請執行以下步驟:

  1. 請確保您的項目build.gradle文件包括谷歌的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.29.0'
          natives 'com.google.ar:core:1.29.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()檢查是否安裝了谷歌播放服務,為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 Optional)

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安裝。一種簡單的方法是啟動一個遵循上述 AR 必需模式的活動。

遵守用戶隱私要求

確保您的應用符合ARCORE的用戶隱私要求

下一步

讀取在示例應用程序代碼和註釋,以及所述C API參考