啟用 ARCore

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

  1. 選擇應用程式的 AR 選項或 AR 選用功能
  2. 在應用程式的資訊清單中新增 AR 必要項目或 AR 選用項目
  3. 在專案中新增建構依附元件
  4. 執行執行階段檢查,確保:
    • 裝置支援 ARCore
    • 已安裝 Google Play 服務 - AR 適用
    • 已授予相機權限。
  5. 確認您的應用程式符合 ARCore 的使用者隱私權規定

選擇 AR 或 AR 選用

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

AR 要求應用程式必須搭配 ARCore 才能運作。如要使用 AR 應用程式,您必須擁有支援 ARCore 支援的裝置,且該程式中已安裝 AR Google Play 服務 AR 適用功能。

AR 非必要應用程式會使用 ARCore 來擴充其他功能。AR 選擇性應用程式提供選用的 AR 功能,只會在 ARCore 支援的裝置 已安裝 AR 適用的 Google Play 服務 上啟用。

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

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

必須提供 ARAR 選用
AR 功能使用情形 應用程式需要 ARCore 才能提供基本功能。 ARCore 可強化應用程式的功能。您的應用程式可在沒有 ARCore 支援的情況下執行。
Play 商店顯示設定 您的應用程式只能在支援 ARCore 的裝置上的 Play 商店中上架。 您的應用程式必須遵守一般商家資訊程序
Google Play 服務 - AR 安裝安裝方法 Play 商店會安裝 AR 適用的 Google Play 服務以及您的應用程式。 您的應用程式會使用 ArCoreApk.requestInstall() 下載並安裝 ARCore。
Android minSdkVersion需求 Android 7.0 (API 等級 24) Android 4.0 (API 等級 14)
必須使用 ArCoreApk.checkAvailability() 檢查 ARCore 支援及安裝狀態
必須使用 ArCoreApk.requestInstall() 才能安裝 AR 適用的 Google Play 服務

詳情請參閱在 Google Play 商店中發布 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 中至少有需要的 minSdkVersion

必須提供 AR

android {
    defaultConfig {
        …
        minSdkVersion 24
    }
}

AR 選用

android {
    defaultConfig {
        …
        minSdkVersion 14
    }
}

新增版本相依性

如要在 Android Studio 專案中新增 ARCore,請按照下列步驟操作:

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

    allprojects {
        repositories {
            google()
            …
        }
    }
    
  • 將最新的 ARCore 程式庫新增為 app's build.gradle 檔案的依附元件:

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

執行執行階段檢查

查看是否支援 ARCore

AR 必要AR 非必要應用程式都應使用 ArCoreApk.checkAvailability() 來判斷目前的裝置是否支援 ARCore。在不支援 ARCore 的裝置上,應用程式應停用 AR 相關功能並隱藏相關的 UI 元素。

Java

@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);
  }
}

Kotlin

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

雖然 AR 適用的 Google Play 服務會與 AR 需要的應用程式一併安裝,但不支援裝置的使用者可以從外部來源安裝該應用程式。使用 checkAvailability() 來檢查 ARCore 支援可確保一致的體驗。

checkAvailability() 可能需要查詢網路資源,判斷裝置是否支援 ARCore。這段期間會傳回 UNKNOWN_CHECKING。為降低感知延遲與彈出現象,應用程式應在生命週期的初期階段呼叫 checkAvailability(),以啟動查詢,並忽略傳回的值。如此一來,呼叫 maybeEnableArButton() 時,就能立即提供快取結果。

要求相機權限

AR 非必要AR 必要應用程式都必須先確認已授予相機權限,才能建立 AR 工作階段。hello_ar_java 範例包含 CameraPermissionHelper 類別,您可以將其複製到您的專案中,並透過 AR 活動 (onResume()) 方法呼叫:

Java

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

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

  …
}

Kotlin

override fun onResume() {
  super.onResume()

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

  …
}

您的 AR 活動也必須實作 onRequestPermissionsResult(),如 HelloArActivity 中所述:

Java

@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();
  }
}

Kotlin

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 服務 - AR 功能

如要確認是否已安裝 (仍在) 的 Google Play 服務相容版本,並確保所有必要的 ARCore 裝置設定檔資料已下載完成,在建立 ARCore 工作階段前,都必須呼叫 ArCoreApk.requestInstall()。這會提示使用者視需要安裝或更新 ARCore,並確保已下載必要的 ARCore 裝置設定檔資料。

Java

// 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.
  }
  …
}

Kotlin

// 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 的使用者隱私權規定

後續步驟