Bật ARCore

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Trang này mô tả cách bật chức năng ARCore trong các dự án Android Studio. Để làm điều này, bạn cần phải:

  1. Chọn giữa Yêu cầu thực tế tăng cường và Thực tế tăng cường không bắt buộc cho ứng dụng của bạn
  2. Thêm các mục bắt buộc AR hoặc AR (không bắt buộc) vào tệp kê khai của ứng dụng
  3. Thêm các phần phụ thuộc của bản dựng vào dự án
  4. Kiểm tra thời gian chạy để đảm bảo rằng:
    • Thiết bị hỗ trợ ARCore,
    • Dịch vụ Google Play cho Thực tế tăng cường được cài đặt trên nền tảng đó,
    • Đã cấp quyền sử dụng máy ảnh.
  5. Đảm bảo ứng dụng của bạn tuân thủ Các yêu cầu về quyền riêng tư của người dùng của ARCore

Chọn giữa AR AR bắt buộc hoặc AR (không bắt buộc)

Bạn có thể định cấu hình một ứng dụng hỗ trợ các tính năng thực tế tăng cường theo hai cách: Yêu cầu thực tế tăng cườngKhông bắt buộc thực tế tăng cường.

Ứng dụng Yêu cầu AR không thể hoạt động nếu không có ARCore. Để có thể sử dụng, ứng dụng AR AR bắt buộc phải có Thiết bị hỗ trợ ARCore đã cài đặt Dịch vụ Google Play cho AR.

  • Cửa hàng Google Play chỉ cung cấp các ứng dụng Bắt buộc thực tế tăng cường trên các thiết bị hỗ trợ ARCore.

  • Khi người dùng cài đặt một ứng dụng AR bắt buộc, Cửa hàng Google Play sẽ tự động cài đặt Dịch vụ Google Play dành cho AR. Tuy nhiên, ứng dụng vẫn phải thực hiện các bước kiểm tra thời gian chạy bổ sung trong trường hợp Dịch vụ Google Play cho Thực tế tăng cường phải được cập nhật hoặc đã được gỡ cài đặt theo cách thủ công.

Ứng dụng AROptional sử dụng ARCore để tăng cường chức năng khác. Ứng dụng AR (không bắt buộc) có các tính năng thực tế tăng cường không bắt buộc, chỉ được kích hoạt trên các thiết bị hỗ trợ ARCore đã cài đặt Dịch vụ Google Play cho AR.

  • Bạn có thể cài đặt và chạy các ứng dụng AR (không bắt buộc) trên các thiết bị không hỗ trợ ARCore.

  • Khi người dùng cài đặt một ứng dụng AR (không bắt buộc), Cửa hàng Google Play sẽ không tự động cài đặt Dịch vụ Google Play cho AR bằng ứng dụng đó.

Yêu cầu ARAR (không bắt buộc)
Sử dụng tính năng thực tế tăng cường Ứng dụng của bạn cần có ARCore để có chức năng cơ bản. ARCore tăng cường chức năng của ứng dụng. Ứng dụng của bạn có thể chạy mà không cần hỗ trợ ARCore.
Chế độ hiển thị trên Cửa hàng Play Ứng dụng của bạn chỉ được liệt kê trong Cửa hàng Play trên các thiết bị có hỗ trợ ARCore. Ứng dụng của bạn tuân theo quy trình liệt kê thông thường.
Phương thức cài đặt Dịch vụ Google Play cho Thực tế tăng cường Cửa hàng Play cài đặt Dịch vụ Google Play cho Thực tế tăng cường cùng với ứng dụng của bạn. Ứng dụng sẽ dùng ArCoreApk.requestInstall() để tải xuống và cài đặt ARCore.
Yêu cầu của Android minSdkVersion Android 7.0 (API cấp 24) Android 4.4 (API cấp 19)
Phải dùng ArCoreApk.checkAvailability() để kiểm tra trạng thái hỗ trợ và cài đặt ARCore
Phải dùng ArCoreApk.requestInstall() để cài đặt Dịch vụ Google Play cho Thực tế tăng cường

Để biết thêm thông tin, hãy xem bài viết Phát hành ứng dụng thực tế tăng cường trong Cửa hàng Google Play.

Thêm mục nhập vào tệp kê khai của ứng dụng

Sửa đổi AndroidManifest.xml của bạn để bao gồm các mục nhập sau:

Yêu cầu 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 (không bắt buộc)

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

Sau đó, đảm bảo rằng ứng dụng của bạn có ít nhất minSdkVersion bắt buộc trong ứng dụng\39;s build.gradle:

Yêu cầu AR

android {
    defaultConfig {
        …
        minSdkVersion 24
    }
}

AR (không bắt buộc)

android {
    defaultConfig {
        …
        minSdkVersion 19
    }
}

Thêm phần phụ thuộc của bản dựng

Để thêm ARCore vào dự án Android Studio, hãy thực hiện các bước sau:

  • Hãy đảm bảo tệp build.gradle dự án của bạn có chứa kho lưu trữ Maven của Google:

    allprojects {
        repositories {
            google()
            …
        }
    }
    
  • Thêm thư viện ARCore mới nhất làm phần phụ thuộc trong tệp app\39;s build.gradle:

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

Thực hiện kiểm tra thời gian chạy

Kiểm tra xem ARCore có được hỗ trợ hay không

Cả ứng dụng Yêu cầu ARKhông bắt buộc AR đều phải dùng ArCoreApk.checkAvailability() để xác định xem thiết bị hiện tại có hỗ trợ ARCore hay không. Trên các thiết bị không hỗ trợ ARCore, các ứng dụng nên tắt chức năng liên quan đến AR và ẩn các thành phần trên giao diện người dùng được liên kết.

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

Mặc dù Dịch vụ Google Play cho Thực tế tăng cường được cài đặt cùng với ứng dụng bắt buộc AR của bạn, nhưng người dùng có thiết bị không được hỗ trợ có thể cài đặt ứng dụng đó từ một nguồn bên ngoài. Việc sử dụng checkAvailability() để kiểm tra xem có hỗ trợ ARCore hay không giúp đảm bảo người dùng có trải nghiệm nhất quán.

checkAvailability() có thể cần truy vấn các tài nguyên mạng để xác định xem thiết bị có hỗ trợ ARCore hay không. Trong thời gian này, phương thức trả về sẽ là UNKNOWN_CHECKING. Để giảm độ trễ và cửa sổ bật lên theo cảm nhận, các ứng dụng nên gọi checkAvailability() một lần trong vòng đời của nó để bắt đầu truy vấn, bỏ qua giá trị được trả về. Bằng cách này, kết quả đã lưu vào bộ nhớ đệm sẽ có sẵn ngay khi gọi maybeEnableArButton().

Yêu cầu quyền truy cập vào máy ảnh

Cả ứng dụng AR Không bắt buộcYêu cầu AR đều phải đảm bảo đã cấp quyền sử dụng máy ảnh trước khi tạo Phiên AR. Mẫu hello_ar_java bao gồm một lớp CameraPermissionHelper có thể được sao chép vào dự án và được gọi từ phương thức onResume() hoạt động thực tế tăng cường của bạn:

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
  }

  …
}

Hoạt động thực tế tăng cường của bạn cũng phải triển khai onRequestPermissionsResult(), như đã thấy trong 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()
  }
}

Kiểm tra xem Dịch vụ Google Play cho Thực tế tăng cường đã được cài đặt hay chưa

Để kiểm tra xem phiên bản tương thích của Dịch vụ Google Play cho AR (vẫn) có được cài đặt hay không, và để đảm bảo rằng bạn đã tải mọi dữ liệu hồ sơ thiết bị ARCore bắt buộc xuống, thì cả ứng dụng bắt buộc AR và AR (không bắt buộc) đều phải gọi ArCoreApk.requestInstall() trước khi tạo phiên ARCore. Thao tác này sẽ nhắc người dùng cài đặt hoặc cập nhật ARCore nếu cần và đảm bảo rằng dữ liệu hồ sơ thiết bị ARCore cần thiết đã được tải xuống.

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

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

Tuân thủ Yêu cầu về quyền riêng tư của người dùng

Hãy đảm bảo ứng dụng của bạn tuân thủ Các yêu cầu về quyền riêng tư của người dùng của ARCore.

Các bước tiếp theo