啟用 ARCore

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

  1. 為您的應用選擇 AR 必需和 AR 可選
  2. 將 AR 必需或 AR 可選條目添加到您的應用清單
  3. 添加構建依賴關係到項目
  4. 執行運行時檢查,以確保:
    • 該設備支持ARCORE
    • 上面安裝了用於 AR 的 Google Play 服務,
    • 已授予相機權限。
  5. 請確保您的應用符合ARCORE的用戶隱私要求

在 AR 必需或 AR 可選之間進行選擇

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

一個AR應用要求無法正常工作且不ARCORE。要使用,一個AR必需的應用程序需要ARCORE支持設備谷歌播放服務AR安裝就可以了。

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

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

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

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

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

需要 AR AR 可選
AR功能使用您的應用需要 ARCore 來實現基本功能。 ARCore 增強了您的應用程序的功能。您的應用可以在沒有 ARCore 支持的情況下運行。
Play 商店可見性您的應用僅在支持 ARCore 的設備上的 Play 商店中列出。您的應用程序如下正常上市程序
谷歌播放服務AR安裝方法Play 商店會在您的應用程序旁邊安裝適用於 AR 的 Google Play 服務。應用程序使用ArCoreApk.requestInstall()來下載並安裝ARCORE。
安卓minSdkVersion要求Android 7.0(API 級別 24) Android 4.0(API 級別 14)
必須使用ArCoreApk.checkAvailability()檢查ARCORE支持和安裝狀態
必須使用ArCoreApk.requestInstall()來安裝谷歌播放服務AR

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

將條目添加到您的應用程序清單

修改您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" />

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

然後,請確保您的應用程序有至少所需minSdkVersion應用程序的build.gradle

需要 AR

android {
    defaultConfig {
        …
        minSdkVersion 24
    }
}

AR 可選

android {
    defaultConfig {
        …
        minSdkVersion 14
    }
}

添加構建依賴項

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

  • 請確保您的項目build.gradle文件包括谷歌的Maven倉庫:

    allprojects {
        repositories {
            google()
            …
        }
    }
    
  • 加入最新的ARCORE庫為您的應用程序的依賴關係build.gradle文件:

    dependencies {
        …
        implementation 'com.google.ar:core:1.29.0'
    }
    

執行運行時檢查

檢查是否支持 ARCore

無論AR必AR可選的應用程序應該使用ArCoreApk.checkAvailability()來確定當前的設備支持ARCORE。在不支持 ARCore 的設備上,應用應禁用 AR 相關功能並隱藏關聯的 UI 元素。

爪哇

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);

  // Enable AR-related functionality on ARCore supported devices only.
  maybeEnableArButton();
  …
}

void maybeEnableArButton() {
  ArCoreApk.Availability availability = ArCoreApk.getInstance().checkAvailability(this);
  if (availability.isTransient()) {
    // Continue to query availability at 5Hz while compatibility is checked in the background.
    new Handler().postDelayed(new Runnable() {
      @Override
      public void run() {
        maybeEnableArButton();
      }
    }, 200);
  }
  if (availability.isSupported()) {
    mArButton.setVisibility(View.VISIBLE);
    mArButton.setEnabled(true);
  } else { // The device is unsupported or unknown.
    mArButton.setVisibility(View.INVISIBLE);
    mArButton.setEnabled(false);
  }
}

科特林

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)

  // Enable AR-related functionality on ARCore supported devices only.
  maybeEnableArButton()
  …
}

fun maybeEnableArButton() {
  val availability = ArCoreApk.getInstance().checkAvailability(this)
  if (availability.isTransient) {
    // Continue to query availability at 5Hz while compatibility is checked in the background.
    Handler().postDelayed({
      maybeEnableArButton()
    }, 200)
  }
  if (availability.isSupported) {
    mArButton.visibility = View.VISIBLE
    mArButton.isEnabled = true
  } else { // The device is unsupported or unknown.
    mArButton.visibility = View.INVISIBLE
    mArButton.isEnabled = false
  }
}

即使 Google Play Services for AR 與您的 AR 必備應用程序一起安裝,使用不受支持的設備的用戶也可能從外部來源安裝它。使用checkAvailability()來檢查ARCORE支持,確保一致的體驗。

checkAvailability()可能需要查詢網絡資源,以確定該設備是否支持ARCORE。在此期間,它將返回UNKNOWN_CHECKING 。為了減少感知延遲和卡扣式,應用程序應該調用checkAvailability()曾在其生命週期的早期發起查詢,忽略返回值。這樣一個緩存的結果將立即生效,當maybeEnableArButton()被調用。

請求相機許可

無論AR可選AR應用要求必須確保相機許可已創建一個AR會議之前得到批准。該hello_ar_java樣本包括CameraPermissionHelper可以複製到你的項目,並要求從AR活性的類onResume()方法:

爪哇

@Override
protected void onResume() {
  super.onResume();

  // ARCore requires camera permission to operate.
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    CameraPermissionHelper.requestCameraPermission(this);
    return;
  }

  …
}

科特林

override fun onResume() {
  super.onResume()

  // ARCore requires camera permission to operate.
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    CameraPermissionHelper.requestCameraPermission(this)
    return
  }

  …
}

您的AR活性也必須實現onRequestPermissionsResult()如看到HelloArActivity

爪哇

@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] results) {
  super.onRequestPermissionsResult(requestCode, permissions, results);
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    Toast.makeText(this, "Camera permission is needed to run this application", Toast.LENGTH_LONG)
        .show();
    if (!CameraPermissionHelper.shouldShowRequestPermissionRationale(this)) {
      // Permission denied with checking "Do not ask again".
      CameraPermissionHelper.launchPermissionSettings(this);
    }
    finish();
  }
}

科特林

override fun onRequestPermissionsResult(
  requestCode: Int,
  permissions: Array<String>,
  results: IntArray
) {
  super.onRequestPermissionsResult(requestCode, permissions, results)
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    Toast.makeText(this, "Camera permission is needed to run this application", Toast.LENGTH_LONG)
      .show()
    if (!CameraPermissionHelper.shouldShowRequestPermissionRationale(this)) {
      // Permission denied with checking "Do not ask again".
      CameraPermissionHelper.launchPermissionSettings(this)
    }
    finish()
  }
}

檢查是否安裝了 Google Play Services for AR

要檢查谷歌播放服務,為AR兼容的版本是否是(仍然)安裝,並確保所有必需ARCORE設備配置文件數據已被下載,無論是要求AR和AR可選的應用程序必須調用ArCoreApk.requestInstall()創建前的Arcore會議。如果需要,這會提示用戶安裝或更新 ARCore,並確保下載所需的 ARCore 設備配置文件數據。

爪哇

// requestInstall(Activity, true) will triggers installation of
// Google Play Services for AR if necessary.
private boolean mUserRequestedInstall = true;

@Override
protected void onResume() {
  super.onResume();

  // Check camera permission.
  …

  // Ensure that Google Play Services for AR and ARCore device profile data are
  // installed and up to date.
  try {
    if (mSession == null) {
      switch (ArCoreApk.getInstance().requestInstall(this, mUserRequestedInstall)) {
        case INSTALLED:
          // Success: Safe to create the AR session.
          mSession = new Session(this);
          break;
        case INSTALL_REQUESTED:
          // When this method returns `INSTALL_REQUESTED`:
          // 1. ARCore pauses this activity.
          // 2. ARCore prompts the user 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. ARCore resumes this activity. The next invocation of
          //    requestInstall() will either return `INSTALLED` or throw an
          //    exception if the installation or update did not succeed.
          mUserRequestedInstall = false;
          return;
      }
    }
  } catch (UnavailableUserDeclinedInstallationException e) {
    // Display an appropriate message to the user and return gracefully.
    Toast.makeText(this, "TODO: handle exception " + e, Toast.LENGTH_LONG)
        .show();
    return;
  } catch (…) {
    …
    return;  // mSession remains null, since session creation has failed.
  }
  …
}

科特林

// requestInstall(Activity, true) will triggers installation of
// Google Play Services for AR if necessary.
var mUserRequestedInstall = true

override fun onResume() {
  super.onResume()

  // Check camera permission.
  …

  // Ensure that Google Play Services for AR and ARCore device profile data are
  // installed and up to date.
  try {
    if (mSession == null) {
      when (ArCoreApk.getInstance().requestInstall(this, mUserRequestedInstall)) {
        ArCoreApk.InstallStatus.INSTALLED -> {
          // Success: Safe to create the AR session.
          mSession = Session(this)
        }
        ArCoreApk.InstallStatus.INSTALL_REQUESTED -> {
          // When this method returns `INSTALL_REQUESTED`:
          // 1. ARCore pauses this activity.
          // 2. ARCore prompts the user 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. ARCore resumes this activity. The next invocation of
          //    requestInstall() will either return `INSTALLED` or throw an
          //    exception if the installation or update did not succeed.
          mUserRequestedInstall = false
          return
        }
      }
    }
  } catch (e: UnavailableUserDeclinedInstallationException) {
    // Display an appropriate message to the user and return gracefully.
    Toast.makeText(this, "TODO: handle exception " + e, Toast.LENGTH_LONG)
        .show()
    return
  } catch (…) {
    …
    return  // mSession remains null, since session creation has failed.
  }
  …
}

遵守用戶隱私要求

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

下一步