이전 ARCore Cloud Anchor API는 지원 중단되었으며 2023년 8월 31일 이후에는 지원되지 않습니다. 앱에서 이 API를 사용하는 경우 최대한 빨리 새로운 ARCore API 엔드포인트를 사용하도록 업데이트해야 합니다.

Android용 클라우드 앵커 개발자 가이드 (Kotlin/자바)

내 앱에서 클라우드 앵커를 사용하는 방법을 알아봅니다.

기본 요건

계속하기 전에 기본 AR 개념ARCore 세션을 구성하는 방법을 이해해야 합니다.

클라우드 앵커를 처음 사용하는 경우 다음 안내를 따르세요.

ARCore API 사용 설정

앱에서 클라우드 앵커를 사용하려면 먼저 신규 또는 기존 Google Cloud Platform 프로젝트에서 ARCore API를 사용 설정해야 합니다. 이 서비스는 클라우드 앵커의 호스팅, 저장, 확인을 담당합니다.

앱에서 ARCore API를 호출하도록 승인

클라우드 앵커를 호스팅하고 확인하려면 ARCore API를 호출하도록 앱을 승인해야 합니다. TTL이 1일보다 큰 클라우드 앵커를 호스팅하고 확인하는 앱은 키 없는 승인을 사용해야 합니다.

키 없는 승인

키 없는 승인을 사용하여 1~365일의 TTL로 클라우드 앵커를 호스팅하고 확인합니다.

  1. 신규 또는 기존 Google Cloud Platform 프로젝트에 ARCore API를 사용 설정합니다.
  2. Google Cloud Console에서 앱의 애플리케이션 ID 및 서명 인증서 SHA-1 디지털 지문을 사용하여 Android 앱의 OAuth 클라이언트 ID를 만듭니다. 그러면 Android 앱이 Google Cloud Platform 프로젝트와 연결됩니다.

    디버그 서명 인증서 디지털 지문을 가져오는 방법은 다음과 같습니다.

    • Android 스튜디오 프로젝트에서 Gradle 도구창을 엽니다.
    • <project-name> > Tasks &gtandroid로 이동합니다.
    • signingReport 태스크를 실행합니다.

    • debug 대안의 SHA-1 디지털 지문을 Google Cloud Console의 SHA-1 인증서 디지털 지문 필드에 복사합니다.
  3. 앱의 종속 항목에 com.google.android.gms:play-services-auth:16+를 포함합니다.

  4. ProGuard를 사용하는 경우 다음을 사용하여 앱의 build.gradle 파일에 추가합니다.

    buildTypes {
      release {
        ...
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
      }
    }
    

    앱의 proguard-rules.pro 파일에 다음을 추가합니다.

    -keep class com.google.android.gms.common.** { *; }
    -keep class com.google.android.gms.auth.** { *; }
    -keep class com.google.android.gms.tasks.** { *; }
    

API 키 승인

API 키 승인을 사용하여 최대 24시간 (1일)의 TTL로 클라우드 앵커를 호스팅하고 확인합니다.

  1. 신규 또는 기존 Google Cloud Platform 프로젝트에 ARCore API를 사용 설정합니다.
  2. Google Cloud Console에서 이 프로젝트의 API 키를 가져옵니다.
  3. Android 스튜디오에서 프로젝트에 새 API 키를 추가합니다. 앱의 app/manifests/AndroidManifest.xml에 있는 <application> 요소의 <meta-data> 요소에 API 키를 포함합니다.

    <meta-data
       android:name="com.google.android.ar.API_KEY"
       android:value="API_KEY"/>
    

세션 구성에서 클라우드 앵커 기능 사용 설정

앱에서 지리정보 기능이 사용 설정되면 앱의 AR 세션 구성에서 지리정보 기능을 사용 설정하여 ARCore API와 통신할 수 있도록 합니다.

자바

Config config = new Config(session);
config.setCloudAnchorMode(Config.CloudAnchorMode.ENABLED);
session.configure(config);

Kotlin

val config = Config(session)
config.cloudAnchorMode = Config.CloudAnchorMode.ENABLED
session.configure(config)

클라우드 앵커 호스팅

호스팅은 hostCloudAnchorWithTtl() 호출로 시작합니다. ARCore는 시각적 데이터, 기기 포즈, 앵커 포즈를 ARCore API에 업로드합니다. 그런 다음 API가 이 정보를 처리하여 3D 특성 맵을 생성하고 최종적으로 앵커의 고유한 클라우드 앵커 ID를 기기에 반환합니다.

hostCloudAnchor()를 호출하여 TTL을 최대 24시간(1일)으로 앵커를 호스팅하거나 ARCore Cloud Anchor Management API를 사용하여 호스팅된 앵커의 전체 기간을 연장할 수도 있습니다.

클라우드 앵커 호스팅을 완료하려면 앱에서 다음 단계를 따라야 합니다.

  1. hostCloudAnchorWithTtl()을 호출합니다.
  2. 상태가 SUCCESS가 될 때까지 Anchor.CloudAnchorState를 사용하여 새 앵커의 상태를 계속 확인합니다.
  3. getCloudAnchorId()가 문자열 식별자를 반환하는지 확인합니다.
  4. 식별자를 다른 클라이언트와 공유하고 resolveCloudAnchor()로 클라우드 앵커를 확인하는 데 사용합니다.

특성 포인트의 매핑 품질 확인

Session.FeatureMapQuality은 특정 카메라 포즈에서 처음 몇 초 동안 ARCore에서 보이는 특징 지점의 품질을 나타냅니다. 고품질 기능을 사용하여 호스팅되는 클라우드 앵커는 일반적으로 더 정확하게 해결됩니다. Session.estimateFeatureMapQualityForHosting()을 사용하여 특정 카메라 포즈의 특성 지도 품질을 추정합니다.

설명
INSUFFICIENT 지난 몇 초 동안 자세에서 식별된 특성 포인트의 품질이 낮습니다. 이 상태는 ARCore가 클라우드 앵커 확인에 더 많은 어려움이 있을 수 있음을 나타냅니다. 사용자에게 호스팅하려는 클라우드 앵커의 원하는 위치를 다양한 각도로 볼 수 있도록 기기를 이동하도록 권합니다.
SUFFICIENT 이전 몇 초 동안 포즈에서 식별된 특징 지점의 품질은 ARCore가 클라우드 앵커를 성공적으로 해결하는 데 충분할 수 있지만 확인된 포즈의 정확성은 낮아질 수 있습니다. 사용자에게 호스팅하려는 클라우드 앵커의 원하는 위치를 다양한 각도로 볼 수 있도록 기기를 이동하도록 권합니다.
GOOD 이전 몇 초 동안 포즈에서 식별된 특성 지점의 품질은 ARCore가 높은 정확도로 클라우드 앵커를 확인하는 데 충분할 가능성이 높습니다.

이전에 호스팅된 앵커 확인

호스팅된 클라우드 앵커를 확인하려면 resolveCloudAnchor()을 호출합니다. ARCore API는 정기적으로 장면의 시각적 특징을 앵커의 3D 특성 맵과 비교하여 앵커를 기준으로 사용자의 위치와 방향을 정확히 찾아냅니다. 일치하는 항목을 찾으면 API가 호스팅된 클라우드 앵커의 자세를 반환합니다.

여러 클라우드 앵커에 대한 확인을 순서대로 시작할 수 있습니다. 동시에 최대 40개의 클라우드 앵커를 변환할 수 있습니다.

클라우드 앵커 취소 또는 삭제

detach()를 호출하여 확인 요청을 취소하거나 앱에서 클라우드 앵커를 삭제합니다.

클라우드 앵커의 상태 확인

Anchor.CloudAnchorState를 사용하여 오류를 포함한 호스팅된 앵커 또는 확인 요청의 상태를 확인합니다.

설명
ERROR_CLOUD_ID_NOT_FOUND ARCore API에서 제공된 클라우드 앵커 ID를 찾을 수 없어 해결할 수 없습니다.
ERROR_HOSTING_DATASET_PROCESSING_FAILED 서버가 특정 앵커의 데이터 세트를 성공적으로 처리할 수 없어 호스팅에 실패했습니다. 기기가 환경에서 더 많은 데이터를 수집한 후 다시 시도하세요.
ERROR_HOSTING_SERVICE_UNAVAILABLE ARCore API에 연결할 수 없습니다. 다운로드할 수 없는 원인으로는 여러 가지가 있습니다. 기기가 비행기 모드이거나 인터넷에 연결되어 있지 않을 수 있습니다. 서버로 전송된 요청이 응답 없이 타임아웃되었을 수 있습니다. 네트워크 연결 불량, DNS 사용 불가, 방화벽 문제 또는 기기의 ARCore API 연결 기능에 영향을 미칠 수 있는 기타 문제가 있을 수 있습니다.
ERROR_INTERNAL 이 앵커의 호스팅 또는 확인 작업이 내부 오류로 완료되었습니다. 앱은 이 오류를 복구하려고 시도해서는 안 됩니다.
ERROR_NOT_AUTHORIZED 애플리케이션에서 제공한 승인이 유효하지 않습니다.
  • Google Cloud 프로젝트에서 ARCore API가 사용 설정되지 않았거나 수행하려는 작업이 허용되지 않습니다.
  • API 키 인증을 사용하는 경우: 매니페스트의 API 키가 잘못되었거나 승인되지 않았거나 누락되었습니다. API 키가 현재 앱을 포함하지 않는 앱 세트로 제한된 경우에도 실패할 수 있습니다.
  • 키 없는 승인을 사용하는 경우 OAuth 클라이언트를 만들지 못했습니다.
  • Google Play 서비스가 설치되어 있지 않거나, 너무 오래되었거나, 어떤 이유로든 오작동합니다 (예: 메모리 압력으로 인해 서비스가 중단됨).
ERROR_RESOLVING_SDK_VERSION_TOO_NEW 앵커를 확인하는 데 사용된 SDK 버전이 최신 버전이므로 호스팅하는 데 사용된 버전보다 호환되지 않으므로 클라우드 앵커를 확인할 수 없습니다.
ERROR_RESOLVING_SDK_VERSION_TOO_OLD 앵커를 확인하는 데 사용되는 SDK 버전이 오래되어 보안 앵커를 호스팅하는 데 사용된 버전보다 호환되지 않으므로 클라우드 앵커를 확인할 수 없습니다.
ERROR_RESOURCE_EXHAUSTED 애플리케이션이 지정된 Google Cloud 프로젝트에 할당된 요청 할당량을 소진했습니다. Google Developers Console에서 프로젝트의 ARCore API에 관한 추가 할당량을 요청해야 합니다.
NONE 앵커는 완전히 로컬입니다. hostCloudAnchor()를 사용하여 호스팅된 적이 없으며 resolveCloudAnchor()를 사용하여 해결되지 않았습니다.
SUCCESS 이 앵커에 대한 호스팅 또는 해결 작업이 완료되었습니다.
TASK_IN_PROGRESS 앵커의 호스팅 또는 확인 작업이 진행 중입니다. 작업이 백그라운드에서 완료되면 Session.update()에 대한 다음 호출 후 앵커가 새 클라우드 상태를 얻습니다.

호스트 및 확인 요청에 대한 API 할당량

ARCore API에는 요청 대역폭에 대한 다음과 같은 할당량이 있습니다.

할당량 유형 최대 시간 적용 대상
앵커 수 unlimited 해당 사항 없음 프로젝트
앵커 호스트 요청 30 IP 주소 및 프로젝트
앵커 확인 요청 300 IP 주소 및 프로젝트

우수한 사용자 경험을 위한 권장사항

사용자에게 다음 단계에 따라 앱의 우수한 사용자 환경을 제공하도록 안내하세요.

  • 객체를 호스팅하기 전에 세션을 호스팅하기 전에 몇 초 정도 기다린 후 앵커 호스팅을 시도합니다. 그러면 추적이 안정화될 때까지 시간이 걸립니다.
  • 앵커를 호스팅할 위치를 선택할 때 서로 쉽게 구분할 수 있는 시각적 특징이 있는 영역을 찾으세요. 최상의 결과를 얻으려면 반사되는 표면이나 빈 벽과 같이 시각적인 특징이 없는 표면을 사용하지 마세요.
  • 카메라를 중심에 맞춰 두고 기기를 중앙에서 움직여 다양한 각도에서 환경을 매핑하여 대략 동일한 물리적 거리를 유지합니다. 이렇게 하면 더 많은 시각적 데이터를 포착하여 더 확실하게 해결할 수 있습니다.

  • 클라우드 앵커를 호스팅하고 확인하는 동안 실제 조명이 충분한지 확인합니다.

지원 중단 정책

  • ARCore SDK 1.12.0 이상으로 빌드된 앱에는 Cloud Anchor API 지원 중단 정책이 적용됩니다.
  • ARCore SDK 1.11.0 이하로 빌드된 앱은 SDK가 이전의 지원 중단된 ARCore API를 사용하기 때문에 클라우드 앵커를 호스팅하거나 변환할 수 없습니다.

다음 단계