在 Android 应用中启用 AR

启用 AR 功能，以便在新应用或现有应用中使用增强现实功能。

将您的应用配置为 AR 必备或 AR 可选

为了节省个别设备上的空间，所有 AR 功能都存储在一款名为面向 AR 的 Google Play 服务的应用中，该应用由 Play 商店单独更新。使用 AR 功能的 Android 应用使用 ARCore SDK 与面向 AR 的 Google Play 服务进行通信。支持 AR 功能的应用可以通过两种方式进行配置：AR 必备和 AR 可选。此指定决定了应用如何与“面向 AR 的 Google Play 服务”应用交互。

如果没有 ARCore，AR 必备应用将无法运行。它需要安装了“面向 AR 的 Google Play 服务”的支持 ARCore 的设备。

• Google Play 商店只会在支持 ARCore 的设备上提供 AR 必备应用。
• 当用户安装 AR 必备应用时，Google Play 商店会自动在其设备上安装“面向 AR 的 Google Play 服务”。不过，如果面向 AR 的 Google Play 服务已过时或已被手动卸载，您的应用仍必须执行额外的运行时检查。

AR 可选应用使用 ARCore 增强现有功能。它具有可选的 AR 功能，这些功能仅在安装了面向 AR 的 Google Play 服务的支持 ARCore 的设备上激活。

• AR 可选应用可在不支持 ARCore 的设备上安装和运行。
• 当用户安装 AR 可选应用时，Google Play 商店不会在设备上安装面向 AR 的 Google Play 服务。

	AR 必备	AR 可选
AR 功能使用情况	您的应用需要使用 ARCore 来实现基本功能。	ARCore 可以增强应用的功能。您的应用可以在不支持 ARCore 的情况下运行。
Play 商店公开范围	您的应用仅在支持 ARCore 的设备上的 Play 商店中上架。	您的应用遵循常规的上架流程。
“面向 AR 的 Google Play 服务”安装方法	Play 商店会在您的应用旁边安装“面向 AR 的 Google Play 服务”。	您的应用使用 ArCoreApk.requestInstall() 下载并安装 ARCore。
Android minSdkVersion 要求	Android 7.0（API 级别 24）	Android 7.0（API 级别 24）
必须使用 ArCoreApk.checkAvailability() 或 ArCoreApk.checkAvailabilityAsync() 检查 ARCore 支持和安装状态
必须使用 ArCoreApk.requestInstall() 才能安装“面向 AR 的 Google Play 服务”

如需将应用设为 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
     }
 }

添加 build 依赖项

要将 ARCore 添加到您的 Android Studio 项目中，请执行以下操作：

1. 确保您项目的 build.gradle 文件包含 Google 的 Maven 制品库。

   allprojects {
       repositories {
           google()
           …
       }
   }
   

2. 将最新的 ARCore 库作为依赖项添加到应用的 build.gradle 文件中。

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

执行运行时检查

在运行时，请执行以下操作以确保应用中的 AR 功能顺畅运行。

检查是否支持 ARCore

AR 必备应用和 AR 可选应用都应使用 ArCoreApk.checkAvailability() 或 ArCoreApk.checkAvailabilityAsync() 来确定当前设备是否支持 ARCore。在不支持 ARCore 的设备上，应用应停用 AR 相关功能并隐藏关联的界面元素。

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

虽然“面向 AR 的 Google Play 服务”是与 AR 必备应用一起安装的，但使用不受支持的设备的用户仍可能会从外部来源安装该应用。使用 ArCoreApk.checkAvailability() 或 ArCoreApk.checkAvailabilityAsync() 检查是否支持 ARCore 可确保一致的体验。

ArCoreApk.checkAvailability() 可能需要查询网络资源以确定设备是否支持 ARCore。在此期间，它会返回 UNKNOWN_CHECKING。为了缩短感知延迟时间和减少感知延迟时间，应用应在其生命周期早期调用一次 ArCoreApk.checkAvailability() 以启动查询，并忽略返回值。这样一来，在可能显示进入 AR 的界面元素时，便可立即提供缓存的结果。

检查是否已安装“面向 AR 的 Google Play 服务”

AR 必备应用和 AR 可选应用必须先调用 ArCoreApk.requestInstall()，然后再创建 ARCore 会话，以检查是否（仍然）安装了面向 AR 的兼容版本的 Google Play 服务，并确保所有必需的 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 activity 还必须实现 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 会话。