Android 앱에서 AR 사용 설정

새로운 앱이나 기존 앱에서 증강 현실 기능을 사용하려면 AR을 사용 설정하세요.

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

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

AR 필수 앱은 ARCore가 없으면 작동할 수 없습니다. AR용 Google Play 서비스를 설치한 ARCore 지원 기기가 필요합니다.

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

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

  • AR 선택적 앱은 ARCore를 지원하지 않는 기기에 설치하고 실행할 수 있습니다.
  • 사용자가 AR 옵션 앱을 설치할 때 Google Play 스토어에서 기기에 AR용 Google Play 서비스를 자동으로 설치하지 않습니다.
AR 필요AR(선택사항)
AR 기능 사용 앱에 기본 기능을 사용하려면 ARCore가 필요합니다. ARCore는 앱의 기능을 강화합니다. ARCore 지원 없이 앱을 실행할 수 있습니다.
Play 스토어 공개 상태 앱이 ARCore를 지원하는 기기의 Play 스토어에만 표시됩니다. 앱이 일반 등록정보 절차를 따릅니다.
Google Play AR 서비스 설치 방법 Play 스토어에서는 앱과 함께 Google Play AR 서비스를 설치합니다. 앱에서 ArCoreApk.requestInstall()를 사용하여 ARCore를 다운로드하고 설치합니다.
Android minSdkVersion 요구사항 Android 7.0 (API 수준 24) Android 7.0 (API 수준 24)
ArCoreApk.checkAvailability()를 사용하여 ARCore 지원 및 설치 상태를 확인해야 합니다.
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을 수정하여 24 이상의 minSdkVersion를 지정합니다.

 android {
     defaultConfig {
         …
         minSdkVersion 24
     }
 }

빌드 종속 항목 추가

Android 스튜디오 프로젝트에 ARCore를 추가하려면 다음 단계를 따르세요.

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

    allprojects {
        repositories {
            google()
            …
        }
    }
    
  2. 최신 ARCore 라이브러리를 앱의 build.gradle 파일에 종속 항목으로 추가합니다.

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

런타임 검사 실행

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

ARCore 지원 여부 확인

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

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

자바

@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);
  }
}

Google Play AR 서비스는 AR 필수 앱과 함께 설치되지만 지원되지 않는 기기를 사용하는 사용자는 외부 소스에서 설치할 수도 있습니다. ArCoreApk.checkAvailability()를 사용하여 ARCore 지원을 확인하는 경우 일관된 환경을 보장합니다.

ArCoreApk.checkAvailability()에서 기기가 ARCore를 지원하는지 확인하기 위해 네트워크 리소스를 쿼리해야 할 수 있습니다. 이 시간 동안 UNKNOWN_CHECKING이 반환됩니다. 인지되는 지연 시간과 팝인을 줄이려면 앱이 수명 주기 초기에 ArCoreApk.checkAvailability()를 호출하여 쿼리를 시작하고 반환된 값을 무시해야 합니다. 이렇게 하면 AR 입력 UI 요소가 표시될 때 캐시된 결과가 즉시 제공됩니다.

Google Play AR 서비스 설치 여부 확인

AR 필수 앱 및 AR 선택사항 앱은 모두 ARCore 세션을 만들기 전에 ArCoreApk.requestInstall()를 호출하여 AR용 Google Play 서비스 버전이 (아직) 설치되었는지 확인하고 모든 필수 ARCore 기기 프로필 데이터가 다운로드되었는지 확인해야 합니다.

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

자바

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

카메라 권한 요청

AR(선택사항) 앱과 AR 필수 앱은 모두 AR 세션을 만들기 전에 카메라 권한이 부여되었는지 확인해야 합니다.

Kotlin

override fun onResume() {
  super.onResume()

  // ARCore requires camera permission to operate.
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    CameraPermissionHelper.requestCameraPermission(this)
    return
  }

  …
}

자바

@Override
protected void onResume() {
  super.onResume();

  // ARCore requires camera permission to operate.
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    CameraPermissionHelper.requestCameraPermission(this);
    return;
  }

  …
}

AR 활동에서도 onRequestPermissionsResult()를 구현해야 합니다.

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

자바

@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();
  }
}

사용자 개인 정보 보호 요구사항 준수

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

다음 단계