Bật thực tế tăng cường trong ứng dụng Android NDK

Bật công nghệ thực tế tăng cường (AR) để sử dụng các tính năng thực tế tăng cường trong ứng dụng mới hoặc ứng dụng hiện có.

Định cấu hình ứng dụng của bạn thành Bắt buộc phải sử dụng công nghệ thực tế tăng cường (AR) hoặc Không bắt buộc về công nghệ thực tế tăng cường

Để tiết kiệm dung lượng trên từng thiết bị, tất cả tính năng AR được lưu trữ trong một ứng dụng có tên là Dịch vụ Google Play cho AR. Ứng dụng này sẽ được Cửa hàng Play cập nhật riêng. Ứng dụng Android sử dụng tính năng thực tế tăng cường kết nối với Dịch vụ Google Play cho Thực tế tăng cường bằng SDK ARCore. 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 2 cách: Bắt buộc thực tế tăng cườngKhông bắt buộc đối với công nghệ thực tế tăng cường. Chỉ định này xác định cách ứng dụng tương tác với ứng dụng Dịch vụ Google Play cho thực tế tăng cường.

Ứng dụng Yêu cầu phải có AR không thể hoạt động nếu không có ARCore. Tính năng này yêu cầu thiết bị hỗ trợ ARCore đã cài đặt Dịch vụ Google Play cho Thực tế tăng cường.

  • Cửa hàng Google Play sẽ chỉ cung cấp các ứng dụng Yêu cầu liên quan đến AR trên thiết bị hỗ trợ ARCore.
  • Khi người dùng cài đặt một ứng dụng Yêu cầu về thực tế tăng cường (AR), Cửa hàng Google Play sẽ tự động cài đặt Dịch vụ Google Play cho thực tế tăng cường (AR) trên thiết bị của họ. Tuy nhiên, ứng dụng của bạn vẫn phải thực hiện các bước kiểm tra bổ sung trong thời gian chạy trong trường hợp Dịch vụ Google Play cho Thực tế tăng cường (AR) đã lỗi thời hoặc bị gỡ cài đặt theo cách thủ công.

Ứng dụng AR không bắt buộc sử dụng ARCore để cải thiện chức năng hiện có. Phiên bản này 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 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 trên thiết bị.
Bắt buộc phải có tính năng ARTuỳ chọn thực tế tăng cường (AR)
Mức sử dụng Tính năng thực tế tăng cường Ứng dụng của bạn cần ARCore cho 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ó 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ó trong Cửa hàng Play trên các thiết bị hỗ trợ ARCore. Ứng dụng của bạn tuân theo quy trình đăng thông tin 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 (AR) cùng với ứng dụng của bạn. Ứng dụng của bạn dùng ArCoreApk_requestInstall() để tải xuống và cài đặt ARCore.
Yêu cầu về Android minSdkVersion Android 7.0 (API cấp 24) Android 7.0 (API cấp 24)
Phải sử dụng ArCoreApk_checkAvailability() hoặc ArCoreApk_checkAvailabilityAsync() để kiểm tra trạng thái cài đặt và hỗ trợ ARCore
Phải dùng ArCoreApk_requestInstall() để cài đặt Dịch vụ Google Play cho Thực tế tăng cường

Để ứng dụng của bạn bắt buộc phải sử dụng tính năng thực tế tăng cường (AR), hãy cập nhật AndroidManifest.xml để thêm các mục sau:

Bắt buộc phải có tính năng 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>

Tuỳ chọn thực tế tăng cường (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>

Sau đó, hãy sửa đổi build.gradle của ứng dụng để chỉ định minSdkVersion có giá trị tối thiểu là 24:

 android {
     defaultConfig {
         …
         minSdkVersion 24
     }
 }

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

  1. Đảm bảo tệp build.gradle của dự án chứa kho lưu trữ Maven của Google.

    allprojects {
        repositories {
            google()
            …
        }
    }
    
  2. Thêm một tác vụ tuỳ chỉnh vào tệp build.gradle của mô-đun để trích xuất các thư viện gốc có trong tệp AAR của ARCore. Bằng cách này, bạn có thể tham chiếu trực tiếp các thuộc tính này trong dự án C hoặc C++.

  3. Trong thư mục app/build, hãy xác định một biến vào thư mục nơi các thư viện gốc sẽ được trích xuất.

  4. Tạo một cấu hình Gradle để lưu giữ các tác vụ trích xuất và dữ liệu.

    /*
    The ARCore AAR library contains native shared libraries that 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 }
    
  5. Tạo một tác vụ để sao chép thư viện gốc từ tệp AAR rồi thêm tác vụ đó vào phần phụ thuộc của bản dựng.

    // Extracts the shared libraries from AARs in the native configuration
    // 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)
        }
    }
    
  6. Định cấu hình cờ bản dựng gốc để chuyển vị trí đến các công cụ xây dựng bên ngoài.

    // From the sample app.
    externalNativeBuild {
        cmake {
            cppFlags "-std=c++11", "-Wall"
            arguments "-DANDROID_STL=c++_static",
                    "-DARCORE_LIBPATH=${arcore_libpath}/jni",
                    "-DARCORE_INCLUDE=${project.rootDir}/../../libraries/include"
        }
    }
    
  7. Thêm các phần phụ thuộc cho cả thư viện Java và thư viện gốc.

    dependencies {
         ...
         // Add Java and native dependencies to the ARCore library.
         implementation 'com.google.ar:core:1.33.0'
         natives 'com.google.ar:core:1.33.0'
         ...
    }
    
  8. 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}
    )
    

Kiểm tra thời gian chạy

Trong thời gian chạy, hãy thực hiện những việc sau để đảm bảo các tính năng thực tế tăng cường trên ứng dụng của bạn hoạt động trơn tru.

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

Cả ứng dụng Bắt buộc thực tế tăng cường (AR) và Không bắt buộc (AR) đều phải sử dụng ArCoreApk_checkAvailability() hoặc ArCoreApk_checkAvailabilityAsync() để 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, ứng dụng phải tắt chức năng liên quan đến AR và ẩn các thành phần liên quan đến giao diện người dùng.

Ứng dụng Android NDK có thể sử dụng lớp Java ArCoreApk để kiểm tra khả năng tương thích và quản lý việc cài đặt trong API phiên ARCore C gốc. Tuỳ thuộc vào cấu trúc của ứng dụng, việc này có thể dễ dàng hơn so với việc sử dụng các hàm ArCoreApk_ do phải xử lý rất nhiều lỗi và tương tác trên giao diện người dùng.

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 or enable the AR button.
  } else {
    // Hide or disable the AR button.
  }
}
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 Yêu cầu thực tế tăng cường (AR) của bạn, nhưng những người dùng có thiết bị không được hỗ trợ vẫn có thể cài đặt ứng dụng này qua một nguồn bên ngoài. Việc sử dụng ArCoreApk_checkAvailability() hoặc ArCoreApk_checkAvailabilityAsync() để kiểm tra khả năng hỗ trợ ARCore giúp đảm bảo trải nghiệm nhất quán.

ArCoreApk_checkAvailability() có thể cần truy vấn 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, thiết bị sẽ trả về AR_AVAILABILITY_UNKNOWN_CHECKING. Để giảm độ trễ dự kiến và cửa sổ bật lên, ứng dụng nên gọi ArCoreApk_checkAvailability() một lần đầu trong vòng đời để 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 hiển thị thành phần trên giao diện người dùng nhập vào AR.

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

Cả ứng dụng Bắt buộc thực tế tăng cường (AR) và Thực tế tăng cường (AR) đều phải gọi ArCoreApk_requestInstall() trước khi tạo phiên ARCore để kiểm tra xem phiên bản Dịch vụ Google Play cho Thực tế tăng cường tương thích đã được cài đặt hay chưa và để đảm bảo rằng mọi dữ liệu hồ sơ thiết bị ARCore cần thiết đều đã được tải xuống.

// Tracks if an installation request has already been triggered.
bool install_requested_;

void nativeOnCreate() {
  // Do other setup here.

  install_requested_ = false;
}

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

    ArInstallStatus install_status;
    // Ensure that 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 the ARCore session.
  }

  // Normal onResume behavior.
}

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

Để phát hành ứng dụng trên Cửa hàng Play, 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.

Bước tiếp theo