Android NDK 앱에서 AR 사용 설정

새 앱 또는 기존 앱에서 증강 현실 기능을 사용하도록 AR을 사용 설정합니다.

앱을 AR 필수 또는 AR 선택사항으로 구성

개별 기기의 공간을 절약하기 위해 모든 AR 기능은 Play 스토어에서 별도로 업데이트되는 Google Play AR 서비스라는 앱에 저장됩니다. AR 기능을 사용하는 Android 앱은 ARCore SDK를 사용하여 Google Play AR 서비스와 통신합니다. AR 기능을 지원하는 앱은 AR 필수 및 AR 선택사항이라는 두 가지 방법으로 구성할 수 있습니다. 이 지정에 따라 앱이 Google Play AR 서비스 앱과 상호작용하는 방식이 결정됩니다.

AR 필요 앱은 ARCore 없이 작동할 수 없습니다. Google Play AR 서비스가 설치된 ARCore 지원 기기가 필요합니다.

  • Google Play 스토어에서는 ARCore를 지원하는 기기에서만 AR 필수 앱을 사용할 수 있도록 합니다.
  • 사용자가 AR 필수 앱을 설치하면 Google Play 스토어에서 기기에 Google Play AR 서비스를 자동으로 설치합니다. 그러나 AR용 Google Play 서비스가 오래되었거나 수동으로 제거된 경우 앱은 여전히 추가 런타임 검사를 실행해야 합니다.

AR 선택사항 앱은 ARCore를 사용하여 기존 기능을 개선합니다. Google Play AR 서비스가 설치된 ARCore 지원 기기에서만 활성화되는 AR 기능(선택사항)이 있습니다.

  • AR 선택적 앱은 ARCore를 지원하지 않는 기기에 설치하고 실행할 수 있습니다.
  • 사용자가 AR 선택적 앱을 설치하면 Google Play 스토어에서 기기에 Google Play AR 서비스를 자동으로 설치하지 않습니다.
AR 필요AR 선택사항
AR 기능 사용 앱의 기본 기능을 사용하려면 ARCore가 필요합니다. ARCore는 앱의 기능을 보강합니다. ARCore 지원 없이 앱을 실행할 수 있습니다.
Play 스토어 공개 상태 앱이 ARCore를 지원하는 기기의 Play 스토어에만 표시됩니다. 앱이 일반적인 등록 절차를 따릅니다.
Google Play AR 서비스 설치 방법 Play 스토어에서는 앱과 함께 Google Play AR 서비스를 설치합니다. 앱에서 <ph type="x-smartling-placeholder"></ph> ArCoreApk.requestInstall() 를 실행하여 ARCore를 다운로드하고 설치합니다.
Android minSdkVersion 요구사항 Android 7.0 (API 수준 24) Android 4.4 (API 수준 19) 단, AR 기능을 실행하려면 Android 7.0 (API 수준 24) 이상이 필요합니다.
ArCoreApk_checkAvailability() 또는 ArCoreApk_checkAvailabilityAsync()를 사용하여 ARCore 지원 및 설치 상태를 확인해야 합니다.
필수 사용 <ph type="x-smartling-placeholder"></ph> ArCoreApk.requestInstall() Google Play AR 서비스 설치

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

빌드 종속 항목 추가

  1. 프로젝트의 build.gradle 파일에 Google의 Maven 저장소가 포함되어 있는지 확인합니다.

    allprojects {
    repositories {
        google()
        …
    }
}

  2. 모듈의 build.gradle 파일에 맞춤 작업을 추가하여 ARCore AAR 파일에서 포함된 네이티브 라이브러리를 추출합니다. 이렇게 하면 C 또는 C++ 프로젝트에서 직접 참조할 수 있습니다.

  3. app/build 디렉터리에서 네이티브 라이브러리가 추출될 디렉터리에 변수를 정의합니다.

  4. 데이터 및 추출 작업을 저장할 Gradle 구성을 만듭니다.

    /*
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. AAR 파일에서 네이티브 라이브러리를 복사하는 작업을 만들고 빌드 종속 항목에 추가합니다.

    // 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. 네이티브 빌드 플래그를 구성하여 위치를 외부 빌드 도구에 전달합니다.

    // 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. Java 및 네이티브 라이브러리 모두에 대한 종속 항목을 추가합니다.

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

런타임 검사 실행

런타임 중에 다음을 실행하여 앱의 AR 기능이 원활하게 실행되는지 확인합니다.

ARCore 지원 여부 확인

AR 필수 앱과 AR 선택 앱은 모두 ArCoreApk_checkAvailability() 또는 ArCoreApk_checkAvailabilityAsync()를 사용하여 현재 기기가 ARCore를 지원하는지 확인해야 합니다. ARCore를 지원하지 않는 기기에서는 앱이 AR 관련 기능을 사용 중지하고 연결된 UI 요소를 숨겨야 합니다.

Android NDK 앱은 Java ArCoreApk 클래스를 사용하여 호환성을 확인하고 네이티브 C ARCore Session API에서 설치를 관리할 수 있습니다. 앱의 구조에 따라 ArCoreApk_ 함수를 사용하는 것보다 더 쉬울 수 있습니다. 발생하는 오류 처리와 사용자 인터페이스 상호작용이 많기 때문입니다.

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.
  }
}
Google Play AR 서비스는 AR 필수 앱과 함께 설치되지만 지원되지 않는 기기를 사용하는 사용자는 외부 소스를 통해 앱을 설치할 수도 있습니다. ArCoreApk_checkAvailability() 또는 ArCoreApk_checkAvailabilityAsync()를 사용하여 ARCore 지원 여부를 확인하면 일관된 환경을 보장할 수 있습니다.

ArCoreApk_checkAvailability()는 기기가 ARCore를 지원하는지 확인하기 위해 네트워크 리소스를 쿼리해야 할 수 있습니다. 이 기간에는 AR_AVAILABILITY_UNKNOWN_CHECKING가 반환됩니다. 인지된 지연 시간과 팝인을 줄이려면 앱은 라이프사이클 초기에 한 번 ArCoreApk_checkAvailability()를 호출하여 쿼리를 시작하고 반환된 값을 무시해야 합니다. 이렇게 하면 AR로 들어가는 UI 요소가 표시될 수 있을 때 캐시된 결과를 즉시 사용할 수 있습니다.

Google Play AR 서비스가 설치되어 있는지 확인하기

AR 필수 및 AR 선택 앱은 모두 <ph type="x-smartling-placeholder"></ph> ArCoreApk.requestInstall() ARCore 세션을 생성하기 전에 호환되는 Google Play AR 서비스 버전이 아직 설치되어 있는지 확인하고 필요한 모든 ARCore 기기 프로필 데이터가 다운로드되었는지 확인하세요.

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

사용자 개인 정보 보호 요건 준수

Play 스토어에 앱을 게시하려면 앱이 ARCore의 사용자 개인 정보 보호 요구사항을 준수하는지 확인해야 합니다.

다음 단계