Google致力於提高黑人社區的種族平等。 怎麼看。
本頁面由 Cloud Translation API 翻譯而成。
Switch to English

啟用ARCore

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

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

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

可以通過兩種方式配置支持AR功能的應用程序: AR必需AR可選

沒有ARCore, AR必需的應用程序將無法運行。要使用,需要AR的應用需要安裝了支持AR的Google Play服務ARCore支持的設備

AR Optional應用程序使用ARCore來增強其他功能。 AR可選應用程序具有可選的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 4.0(API級別14)
必須使用ArCoreApk.checkAvailability()來檢查ARCore支持和安裝狀態
必須使用ArCoreApk.requestInstall()來安裝適用於AR的Google Play服務

有關更多信息,請參閱在Google Play商店中發布AR Apps

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

修改您的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>

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

必須填寫AR

android {
    defaultConfig {
        …
        minSdkVersion 24
    }
}

AR可選

android {
    defaultConfig {
        …
        minSdkVersion 14
    }
}

添加構建依賴項

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

  • 確保您項目的build.gradle文件包含Google的Maven存儲庫:

    allprojects {
        repositories {
            google()
            …
        }
    }
    
  • 將最新的ARCore庫作為依賴項添加到應用程序的build.gradle文件中:

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

執行運行時檢查

檢查是否支持ARCore

AR RequiredAR Optional應用程序均應使用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
  }
}

即使將AR的Google Play服務與您的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()
  }
}

檢查是否安裝了適用於AR的Google Play服務

要檢查(仍然)是否安裝了兼容的Google Play AR版兼容版本,並確保已下載所有必需的ARCore設備配置文件數據,AR必需和AR可選應用都必須在創建ARCore之前調用ArCoreApk.requestInstall()會議。這會提示用戶在需要時安裝或更新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的用戶隱私要求

下一步