在 Android 應用程式中啟用 AR

啟用 AR 功能，即可在新的或現有應用程式中使用擴增實境功能。

將應用程式設為「必須使用 AR」或「選用 AR」

為節省個別裝置的空間，所有 AR 功能都會儲存在名為「Google Play 服務 - AR 適用」的應用程式中，而該應用程式會由 Play 商店個別更新。使用 AR 功能的 Android 應用程式會透過 ARCore SDK 與「Google Play 服務 - AR 適用」通訊。支援 AR 功能的應用程式可透過兩種方式進行設定：必需使用 AR 和選用 AR。這項指定會決定應用程式與 Google Play 服務 - AR 適用應用程式的互動方式。

AR 功能為必備條件的應用程式必須搭配 ARCore 才能運作。需要支援 ARCore 的裝置，且已安裝「Google Play 服務 - AR 適用」。

  • Google Play 商店只會在支援 ARCore 的裝置上提供 AR 必要應用程式。
  • 使用者安裝 AR 專用應用程式時，Google Play 商店會自動在裝置上安裝「Google Play 服務 - AR 適用」應用程式。不過，如果 Google Play 擴增實境服務已過時或已手動解除安裝，您的應用程式仍必須執行額外的執行階段檢查。

AR 選用應用程式會使用 ARCore 強化現有功能。這項服務提供選用的 AR 功能，但只有在已安裝 Google Play 服務 - AR 適用的 ARCore 支援裝置上才能啟用。

  • 即使裝置不支援 ARCore，您也可以在裝置上安裝及執行 AR 選用應用程式。
  • 使用者安裝 AR 選用應用程式時，「Google Play 商店」不會在裝置上自動安裝 Google Play 服務 - AR 適用。
必須使用 ARAR 選用
AR 功能使用情形 應用程式需要 ARCore 才能提供基本功能。 ARCore 可增強應用程式的功能。應用程式不必支援 ARCore 也能執行。
Play 商店顯示設定 您的應用程式只會在支援 ARCore 的裝置上架至 Play 商店。 您的應用程式遵循一般商店資訊程序。
「Google Play 服務 - AR 適用」安裝方式 Play 商店會一併安裝「Google Play 服務 - AR 適用」和應用程式。 您的應用程式會使用 ArCoreApk.requestInstall() 下載及安裝 ARCore。
Android minSdkVersion 規定 Android 7.0 (API 級別 24) Android 4.4 (API 級別 19)，不過執行任何 AR 功能至少需要 Android 7.0 (API 級別 24)
必須使用 ArCoreApk.checkAvailability() 或 ArCoreApk.checkAvailabilityAsync() 檢查 ARCore 支援和安裝狀態
必須使用 ArCoreApk.requestInstall() 安裝「Google Play 服務 - AR 適用」

如要將應用程式設為 AR 必備或 AR 選用，請更新 AndroidManifest.xml，加入下列項目：

必須使用 ARAR 選用
<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>

<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 至少為 24：

 android {
     defaultConfig {
         …
         minSdkVersion 24
     }
 }

新增建構依附元件

如要將 ARCore 新增至 Android Studio 專案，請按照下列步驟操作：

  1. 請確認專案的 build.gradle 檔案包含 Google 的 Maven 存放區。

    allprojects {
    repositories {
        google()
        …
    }
}

  2. 在應用程式的 build.gradle 檔案中，將最新的 ARCore 程式庫新增為依附元件。

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

執行執行階段檢查

在執行階段期間，請執行下列操作，確保應用程式中的 AR 功能順利執行。

檢查是否支援 ARCore

無論是 AR 必備應用程式還是 AR 選用應用程式，都應使用 ArCoreApk.checkAvailability() 或 ArCoreApk.checkAvailabilityAsync() 判斷目前裝置是否支援 ARCore。在不支援 ARCore 的裝置上，應用程式應停用 AR 相關功能，並隱藏相關的 UI 元素。
KotlinJava
override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)

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

fun maybeEnableArButton() {
  ArCoreApk.getInstance().checkAvailabilityAsync(this) { availability ->
    if (availability.isSupported) {
      mArButton.visibility = View.VISIBLE
      mArButton.isEnabled = true
    } else { // The device is unsupported or unknown.
      mArButton.visibility = View.INVISIBLE
      mArButton.isEnabled = false
    }
  }
}

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

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

void maybeEnableArButton() {
  ArCoreApk.getInstance().checkAvailabilityAsync(this, availability -> {
    if (availability.isSupported()) {
      mArButton.setVisibility(View.VISIBLE);
      mArButton.setEnabled(true);
    } else { // The device is unsupported or unknown.
      mArButton.setVisibility(View.INVISIBLE);
      mArButton.setEnabled(false);
    }
  });
}
即使 Google Play 服務 - AR 適用已與 AR 必要應用程式一併安裝，使用者仍可能透過外部來源安裝這項服務，前提是他們所使用的裝置不受支援。使用 ArCoreApk.checkAvailability() 或 ArCoreApk.checkAvailabilityAsync() 檢查 ARCore 支援情形，可確保提供一致的體驗。

ArCoreApk.checkAvailability() 可能需要查詢網路資源，以判斷裝置是否支援 ARCore。在這段期間，系統會傳回 UNKNOWN_CHECKING。為減少延遲和彈出情形，應用程式應在生命週期初期呼叫 ArCoreApk.checkAvailability()，藉此啟動查詢，並忽略傳回的值。這樣一來，當 AR 輸入 UI 元素可能顯示時，快取結果就會立即顯示。

檢查是否已安裝「Google Play 服務 - AR 適用」

無論是 AR 必備應用程式還是 AR 選用應用程式，都必須在建立 ARCore 工作階段前使用 ArCoreApk.requestInstall() ，以便檢查是否 (仍) 安裝相容版本的 Google Play 服務 - AR 適用，並確保已下載所有必要的 ARCore 裝置設定檔資料。

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

// requestInstall(Activity, true) will trigger 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.
  }
  …
}

要求相機權限

無論是 AR 選用型應用程式還是 AR 必用型應用程式，都必須在建立 AR 工作階段前，確認已授予相機權限。

KotlinJava
override fun onResume() {
  super.onResume()

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

  …
}

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

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

  …
}

AR 活動也必須實作 onRequestPermissionsResult()。

KotlinJava
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()
  }
}

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

遵守使用者隱私權規定

如要在 Play 商店發布應用程式，請確認您的應用程式符合 ARCore 的使用者隱私權規定。

後續步驟