Bật ARCore

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

  1. Thêm AR bắt buộc hoặc AR (không bắt buộc) vào tệp kê khai
  2. Thêm các phần phụ thuộc bản dựng vào dự án
  3. Thực hiện quá trình kiểm tra thời gian chạy để đảm bảo thiết bị hỗ trợ ARCore và đã cài đặt Dịch vụ Google Play cho Thực tế tăng cường
  4. Đả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

Dịch vụ Google Play cho Thực tế tăng cường

Các SDK ARCore cung cấp các tính năng AR trên các thiết bị hỗ trợ ARCore đã cài đặt Dịch vụ Google Play cho AR (ARCore).

Dịch vụ Google Play cho Thực tế tăng cường được tự động cài đặt và cập nhật trên phần lớn các thiết bị được hỗ trợ.

Trước khi bắt đầu một phiên AR, ứng dụng phải:

  1. Kiểm tra để đảm bảo rằng ARCore được hỗ trợ bằng cách gọi ArCoreApk_checkAvailability.
  2. Kiểm tra để đảm bảo bạn đã cài đặt và cập nhật Dịch vụ Google Play cho Thực tế tăng cường, đồng thời đã tải dữ liệu hồ sơ thiết bị ARCore bắt buộc xuống bằng cách gọi ArCoreApk_requestInstall.

Thêm tính năng AR bắt buộc hoặc AR (không bắt buộc) vào tệp kê khai

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: Bắt buộc thực tế tăng cườngKhông bắt buộc thực tế tăng cường.

Cần có AR

Để sử dụng được, ứng dụng Cần có AR yêu cầu phải có Thiết bị hỗ trợ ARCore đã cài đặt Dịch vụ Google Play cho AR.

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

Để khai báo ứng dụng của bạn là Bắt buộc thực hiện AR, hãy sửa đổi AndroidManifest.xml để bao gồm các mục sau:

<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" android:required="true"/>

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

Sau đó, sửa đổi build.gradle của ứng dụng để chỉ định minSdkVersion ít nhất là 24:

android {
    defaultConfig {
        …
        minSdkVersion 24
    }
}

Không bắt buộc AR

Ứng dụng Không bắt buộc thực tế tăng cường có các tính năng thực tế tăng cường không bắt buộc và 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 Thực tế tăng cường.

  • 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 Thực tế tăng cường bằng ứng dụng đó.

Để khai báo ứng dụng của bạn là Không bắt buộc AR, hãy sửa đổi AndroidManifest.xml để bao gồm các mục sau:

<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 đó, sửa đổi build.gradle của ứng dụng để chỉ định minSdkVersion tối thiểu là 14:

android {
    defaultConfig {
        …
        minSdkVersion 14
    }
}

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

Để thêm thư viện ARCore vào dự án Android Studio của bạn, hãy làm theo các bước sau:

  1. Đả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()
            ...
    
  2. Trích xuất thư viện gốc từ ARCore aar.

    Các thư viện gốc nằm trong tệp ARCore aar. Để sử dụng chúng như một phần của dự án C/C++, chúng phải được trích xuất từ kho lưu trữ để chúng có thể được tham chiếu trực tiếp. Để làm việc này, hãy thêm một việc cần làm tùy chỉnh vào tệp build.gradle của mô-đun (ví dụ: app/build.gradle).

    Tệp tiêu đề cho ARCore, arcore_c_api.h được bao gồm trong dự án SDK GitHub:

    Xác định một biến cho thư mục trong thư mục app/build. Các thư viện gốc sẽ được trích xuất vào thư mục này. Đồng thời tạo cấu hình gradle để lưu giữ các tác vụ và dữ liệu trích xuất.

    /*
    The ARCore aar library contains the native shared libraries. These are
    extracted before building to a temporary directory.
    */
    def arcore_libpath = "${buildDir}/arcore-native"
    
    // Create a configuration to mark which aars to extract .so files from
    configurations { natives }
    
    

    Tạo một nhiệm vụ để sao chép các thư viện gốc từ tệp aar và thêm vào các phần phụ thuộc bản dựng

      // Extracts the shared libraries from aars in the natives configuration.
      // This is done so that NDK builds can access these libraries.
      task extractNativeLibraries() {
         // Extract every time.
         outputs.upToDateWhen { false }
    
         doFirst {
              configurations.natives.files.each { f ->
                  copy {
                      from zipTree(f)
                      into arcore_libpath
                      include "jni/**/*"
                  }
              }
          }
      }
    
      tasks.whenTaskAdded {
          task-> if (task.name.contains("external") && !task.name.contains("Clean")) {
              task.dependsOn(extractNativeLibraries)
          }
      }
    
  3. Định cấu hình cờ bản dựng gốc để chuyển các vị trí đến các công cụ bản dựng bên ngoài.

    Đây là ví dụ về các mẫu trong dự án GitHub.

          externalNativeBuild {
              cmake {
                  cppFlags "-std=c++11", "-Wall"
                  arguments "-DANDROID_STL=c++_static",
                          "-DARCORE_LIBPATH=${arcore_libpath}/jni",
                          "-DARCORE_INCLUDE=${project.rootDir}/../../libraries/include"
              }
          }
    

  4. Thêm các phần phụ thuộc cho cả Java và thư viện gốc.

     dependencies {
          ...
          // Add java and native dependencies on the ARCore library
          implementation 'com.google.ar:core:1.32.0'
          natives 'com.google.ar:core:1.32.0'
          ...
     }
    
  5. Tham chiếu các thư viện gốc trong CMakeLists.txt

    # Import the ARCore library.
    add_library(arcore SHARED IMPORTED)
    set_target_properties(arcore PROPERTIES IMPORTED_LOCATION
                  ${ARCORE_LIBPATH}/${ANDROID_ABI}/libarcore_sdk_c.so
                  INTERFACE_INCLUDE_DIRECTORIES ${ARCORE_INCLUDE}
    )
    

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

Kiểm tra xem ARCore đã được cài đặt hay chưa

Tất cả các ứng dụng AR phải gọi ArCoreApk_requestInstall() trước khi tạo một phiên ARCore. ArCoreApk_requestInstall() kiểm tra xem một phiên bản tương thích của Dịch vụ Google Play cho Thực tế tăng cường được cài đặt hay chưa (có thể phiên bản này đã lỗi thời hoặc người dùng đã xóa theo cách thủ công) và sẽ nhắc người dùng cài đặt dịch vụ nếu phiên bản đó không có.

// Tracks if we have already triggered an installation request.
bool install_requested_;

void nativeOnCreate() {
  // other setup

  install_requested_ = false;
}

void nativeOnResume(JNIEnv env, jobject activity) {
  if (ar_session_ == null) {
    bool user_requested_install = !install_requested_;

    ArInstallStatus install_status;
    // Ensure Google Play Services for AR and ARCore device profile data are
    // installed and up to date.
    ArStatus error = ArCoreApk_requestInstall(
        env, activity, user_requested_install, &install_status);
    if (error != AR_SUCCESS) {
      // Inform user of error.
      return;
    }

    switch (install_status) {
      case AR_INSTALL_STATUS_INSTALLED:
        break;
      case AR_INSTALL_STATUS_INSTALL_REQUESTED:
        // When this method returns `AR_INSTALL_STATUS_INSTALL_REQUESTED`:
        // 1. This activity will be paused.
        // 2. The user is prompted 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. This activity is resumed. The next invocation of
        //    ArCoreApk_requestInstall will either return
        //    `AR_INSTALL_STATUS_INSTALLED` or throw an exception if the
        //    installation or update did not succeed.
        install_requested_ = true;
        return;
    }

    // Request camera permissions.

    error = ArSession_create(env, context, &ar_session_);
    if (error != AR_SUCCESS) {
      // Inform user of error.
      return;
    }

    // Configure session
  }

  // Normal onResume behavior
}

Nếu ArCoreApk_requestInstall() trả về AR_INSTALL_STATUS_INSTALL_REQUESTED, hoạt động hiện tại sẽ tạm dừng và người dùng được nhắc cài đặt hoặc cập nhật dịch vụ. onResume() hoạt động sẽ thực thi lại khi người dùng quay lại hoạt động.

Kiểm tra xem ARCore có được hỗ trợ hay không (Chỉ dành cho AR (Không bắt buộc))

Các ứng dụng tùy chọn thực tế tăng cường có thể sử dụng ArCoreApk_checkAvailability() để xác định xem thiết bị hiện tại có hỗ trợ ARCore hay không. Trên một 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 phần tử giao diện người dùng được liên kết.

void maybeEnableArButton(JNIEnv env, jobject context) {
  // Likely called from Activity.onCreate() of an activity with AR buttons.
  ArAvailability availability
  ArCoreApk_checkAvailability(env, context, &availability);
  if (availability == AR_AVAILABILITY_UNKNOWN_CHECKING) {
    // Set a timer to call maybeEnableArButton() again after about 200ms.
  }
  if (availability == AR_AVAILABILITY_SUPPORTED_NOT_INSTALLED ||
      availability == AR_AVAILABILITY_SUPPORTED_APK_TOO_OLD ||
      availability == AR_AVAILABILITY_SUPPORTED_INSTALLED) {
    // Show/enable AR button.
  } else {
    // Hide/disable AR button.
  }
}

Sau đó, khi người dùng muốn sử dụng tính năng AR, ứng dụng của bạn phải đảm bảo rằng Dịch vụ Google Play cho AR được cài đặt. Một cách dễ dàng để thực hiện việc này là chạy một hoạt động theo mẫu Yêu cầu thực tế tăng cường như mô tả ở trên.

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

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

Đọc mã và nhận xét trong ứng dụng mẫu, cũng như Tài liệu tham khảo API C.