只要啟用 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 適用。
| 必須使用 AR | AR 選用 | |
|---|---|---|
| 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 加入下列項目：
支援 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 至少為 24：
android {
defaultConfig {
…
minSdkVersion 24
}
}
新增建構依附元件
如要將 ARCore 新增到 Android Studio 專案，請按照下列步驟操作：
請確認專案的
build.gradle檔案包含 Google 的 Maven 存放區。allprojects { repositories { google() … } }在應用程式的
build.gradle檔案中，將最新的 ARCore 程式庫新增為依附元件。dependencies { … implementation 'com.google.ar:core:1.33.0' }
執行執行階段檢查
在執行階段期間，請執行下列操作，確保應用程式中的 AR 功能順利執行。
檢查是否支援 ARCore
需要 AR 和 AR 選用應用程式應使用ArCoreApk.checkAvailability() 或 ArCoreApk.checkAvailabilityAsync()，判斷目前的裝置是否支援 ARCore。在不支援 ARCore 的裝置上，應用程式應停用 AR 相關功能，並隱藏相關的 UI 元素。
Kotlin
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
}
}
}
Java
@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);
}
});
}
ArCoreApk.checkAvailability() 或 ArCoreApk.checkAvailabilityAsync() 檢查 ARCore 支援情形，可確保提供一致的體驗。ArCoreApk.checkAvailability() 可能需要查詢網路資源，才能判斷裝置是否支援 ARCore。在這段期間，它會傳回 UNKNOWN_CHECKING。為減少感知延遲時間和彈出式視窗，應用程式應在生命週期的早期呼叫 ArCoreApk.checkAvailability() 一次，忽略傳回的值來啟動查詢。這樣一來，系統就能在 AR 進入 UI 元素時顯示快取結果。
檢查是否已安裝「Google Play 服務 - AR 適用」
需要 AR 和 AR 選用應用程式都必須使用
ArCoreApk.requestInstall()
，再建立 ARCore 工作階段，檢查是否已安裝相容的「Google Play 服務 - AR 適用」版本，並確保已下載所有必要的 ARCore 裝置設定檔資料。
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.
}
…
}
Java
// 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 工作階段。
Kotlin
override fun onResume() {
super.onResume()
// ARCore requires camera permission to operate.
if (!CameraPermissionHelper.hasCameraPermission(this)) {
CameraPermissionHelper.requestCameraPermission(this)
return
}
…
}
Java
@Override
protected void onResume() {
super.onResume();
// ARCore requires camera permission to operate.
if (!CameraPermissionHelper.hasCameraPermission(this)) {
CameraPermissionHelper.requestCameraPermission(this);
return;
}
…
}
您的 AR 活動也必須實作 onRequestPermissionsResult()。
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()
}
}
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();
}
}
遵守使用者隱私權規定
如要在 Play 商店發布應用程式，請確認您的應用程式符合 ARCore 的使用者隱私權規定。
後續步驟
- 瞭解如何設定 ARCore 工作階段。