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

iOS를 타겟팅하는 ARCore 확장 프로그램용 클라우드 앵커 개발자 가이드

자체 앱에서 클라우드 앵커를 사용하는 방법을 알아보세요.

기본 요건

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

클라우드 앵커를 처음 사용하는 경우 앵커클라우드 앵커의 작동 방식을 이해해야 합니다.

ARCore API 사용 설정

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

ARCore API를 호출하도록 앱 승인

ARCore API를 호출하여 클라우드 앵커를 호스팅하고 확인할 수 있도록 앱을 승인해야 합니다. TTL이 1일보다 큰 클라우드 앵커를 호스팅하고 확인하는 앱은 토큰 (서명된 JWT) 승인을 사용해야 합니다.

토큰 (서명된 JWT) 승인

1에서 365일 사이의 TTL로 클라우드 앵커를 호스팅하고 확인하려면 토큰 (서명된 JWT) 승인을 사용합니다. 현재 유일하게 지원되는 토큰 유형은 서명된 JSON 웹 토큰(JWT)입니다. 이 토큰은 Google 서비스 계정으로 서명되어야 합니다.

  1. 수정 > 프로젝트 설정 > XR 플러그인 관리 > ARCore 확장 프로그램으로 이동하여 iOS 지원 사용 설정을 선택합니다.

  2. iOS Authentication Strategy(iOS 인증 전략) 드롭다운 메뉴에서 Authentication Token(인증 토큰) 옵션을 선택합니다.

서버 엔드포인트 요구사항

iOS용 토큰을 생성하려면 서버에 다음 요구사항을 충족하는 엔드포인트가 있어야 합니다.

  1. 자체 승인 메커니즘으로 엔드포인트를 보호합니다.
  2. 각 사용자가 고유한 토큰을 가져오고 토큰이 즉시 만료되지 않도록 엔드포인트에서 매번 새 토큰을 생성해야 합니다.

서비스 계정 및 서명 키 만들기

Google 서비스 계정 및 서명 키를 만들려면 다음 단계를 따르세요.

  1. Google Cloud Platform Console의 탐색 메뉴에서 API 및 서비스 & gt; 사용자 인증 정보로 이동합니다.
  2. 원하는 프로젝트를 선택하고 사용자 인증 정보 만들기 > 서비스 계정을 클릭합니다.
  3. 서비스 계정 세부정보에서 새 계정의 이름을 입력하고 만들기를 클릭합니다.
  4. 서비스 계정 권한 페이지에서 역할 선택 드롭다운 메뉴로 이동합니다. 서비스 계정 > 서비스 계정 토큰 생성자를 선택하고 계속을 클릭합니다.
  5. 사용자에게 이 서비스 계정에 대한 액세스 권한 부여 페이지에서 완료를 클릭합니다. 그러면 API 및 서비스 & gt; 사용자 인증 정보로 돌아갑니다.
  6. 사용자 인증 정보 페이지에서 서비스 계정 섹션까지 아래로 스크롤하고 방금 만든 계정의 이름을 클릭합니다.
  7. 서비스 계정 세부정보 페이지에서 섹션까지 아래로 스크롤하고 키 추가 > 새 키 만들기를 선택합니다.
  8. 키 유형으로 JSON을 선택하고 만들기를 클릭합니다. 그러면 비공개 키가 포함된 JSON 파일이 머신에 다운로드됩니다. 다운로드한 JSON 키 파일을 안전한 위치에 저장합니다.

JSON 파일에는 공개되지 않아야 하는 비공개 키가 포함되어 있습니다. GitHub와 같은 소스 코드 저장소에 커밋하지 마세요.

서버에서 토큰 만들기

서버에서 새 토큰 (JWT)을 만들려면 표준 JWT 라이브러리와 새 서비스 계정에서 안전하게 다운로드한 JSON 파일을 사용합니다.

개발 머신에 토큰 만들기

개발 머신에서 JWT를 생성하려면 다음 oauth2l 명령어를 사용합니다.

// "oauth2l" uses a lowercase L, not a 1, as the last character.
// Specifying an empty cache location using the --cache flag is necessary
// to ensure that a different token is produced each time.
oauth2l fetch --cache "" --jwt --json $KEYFILE --audience "https://arcore.googleapis.com/"

결과로 나오는 문자열을 자릅니다. 공백이나 줄바꿈 문자를 사용하면 API가 토큰을 거부합니다.

토큰에 서명

JWT에 서명하려면 RS256 알고리즘과 다음 클레임을 사용합니다.

  • iss - 서비스 계정 이메일 주소입니다.
  • sub - 서비스 계정 이메일 주소입니다.
  • iat - 토큰이 생성된 Unix 시간(초)입니다.
  • exp: iat + 3600 (1시간) 토큰이 만료되는 Unix 시간(초)입니다.
  • aud - 잠재고객 https://arcore.googleapis.com/로 설정해야 합니다.

JWT 페이로드에서는 비표준 클레임이 필요하지 않지만 uid 클레임이 대응하는 사용자를 식별하는 데 유용할 수 있습니다.

JWT를 생성하는 데 다른 접근 방식(예: Google 관리 환경에서 Google API 사용)을 사용하는 경우 이 섹션의 클레임으로 JWT에 서명해야 합니다. 무엇보다도 잠재고객이 올바른지 확인해야 합니다.

ARCore 세션에 토큰 전달

토큰을 받으면 ARAnchorManager.SetAuthToken()를 사용하여 ARCore 세션에 전달합니다.

// Designate the token to use when authorizing with the ARCore API
// on the iOS platform. The API should be called each time the application's token is refreshed.
ARAnchorManager.SetAuthToken(string authToken);

토큰을 세션에 전달할 때 다음 사항에 유의하세요.

  • 앵커를 호스팅하거나 결정하려고 하기 전에 유효한 승인 토큰을 전달해야 합니다.
  • ARCore에서는 공백 또는 특수문자가 포함된 승인 토큰을 무시합니다.
  • 유효한 API 키로 세션이 생성되면 ARCore가 제공된 승인 토큰을 무시합니다. 이전에 사용했지만 더 이상 필요하지 않은 API 키는 Google Cloud Platform Console에서 삭제하고 사용자를 최신 버전으로 이전한 후 앱에서 삭제하는 것이 좋습니다.
  • 토큰은 일반적으로 1시간 후에 만료됩니다. 사용 중에 토큰이 만료될 가능성이 있는 경우 새 토큰을 가져오고 새 토큰으로 ARAnchorManager.SetAuthToken(string authToken)를 호출합니다.

API 키 승인

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

ARCore SDK 1.24.0 이상으로 빌드된 새 Unity 프로젝트의 기본 승인 전략은 DoNotUse입니다. 이는 불필요한 라이브러리로 앱이 빌드되는 것을 방지하기 위함입니다. 앱이 클라우드 앵커를 사용하고 ARCore SDK 1.24.0 이상을 사용하여 빌드된 경우 프로젝트 설정 > XR 플러그인 관리 > ARCore 확장 프로그램에서 수동으로 승인을 사용 설정해야 합니다.

  1. 수정 > 프로젝트 설정 > XR 플러그인 관리 > ARCore 확장 프로그램으로 이동하여 iOS 지원 사용 설정을 선택합니다.

  2. iOS 인증 전략 드롭다운 메뉴에서 API 키 옵션을 선택합니다.

  3. Google Cloud Console에서 이 프로젝트의 API 키를 가져옵니다.

  4. 수정 > 프로젝트 설정 > XR 플러그인 관리 > ARCore 확장 프로그램으로 이동하여 클라우드 앵커 API 키 필드에 API 키를 추가합니다.

앱에서 클라우드 앵커 기능 사용 설정

앱이 ARCore API를 호출하도록 승인한 후 앱에서 클라우드 앵커 기능을 사용 설정해야 합니다.

  1. 수정 > 프로젝트 설정 > XR 플러그인 관리 > ARCore 확장 프로그램으로 이동합니다. iOS 지원 사용이 선택되어 있는지 확인합니다.
  2. 선택적 기능에서 클라우드 앵커를 선택합니다.

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

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

  1. 프로젝트 Assets 폴더에 ARCoreExtensionsConfig 스크립트 가능 객체가 포함되어 있는지 확인하세요. 확장 프로그램을 만들려면 Assets 창을 마우스 오른쪽 버튼으로 클릭하고 Create > XR > ARCore Extensions Config를 선택합니다.
  2. Assets(애셋) 폴더에서 ARCoreExtensionsConfig 스크립트 가능 객체를 선택하고 Cloud Anchor Mode(클라우드 앵커 모드)를 Enabled(사용)로 설정합니다.

  3. ARCoreExtensionsConfig 구성을 사용하도록 ARCore Extensions 게임 객체를 구성합니다. Hierarchy 계층 구조에서 ARCore 확장 프로그램을 처음 설정할 때 만든 ARCore Extensions 게임 객체를 찾고 ARCore Extensions Config 입력란을 Assets 폴더의 ARCoreExtensionsConfig 스크립트 가능 객체에 연결합니다.

클라우드 앵커 호스팅

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

ARCore Cloud Anchor Management API를 사용하여 호스팅된 앵커의 전체 기간을 연장할 수도 있습니다.

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

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

지형지물 지점의 매핑 품질 확인

ARCoreExtensions.FeatureMapQuality는 특정 카메라 포즈에서 지난 몇 초 동안 ARCore에 표시된 지형지물의 품질을 나타냅니다. 고품질 기능을 사용하여 호스팅되는 클라우드 앵커는 일반적으로 더 정확하게 해결됩니다. ARAnchorManagerExtensions.EstimateFeatureMapQualityForHosting()를 사용하여 특정 카메라 포즈의 특징 지도 품질에 대한 추정치를 얻습니다.

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

이전에 호스팅된 앵커 확인

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

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

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

ARCloudAnchor.OnDestroy()ARCloudAnchor 구성요소가 포함된 게임 객체에서 이 구성요소를 삭제하면 자동으로 호출됩니다. 그러면 기본 네이티브 클라우드 앵커 객체가 분리되고 해제됩니다.

클라우드 앵커의 상태 확인

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

설명
ErrorResolvingCloudIdNotFound ARCore API에서 제공된 클라우드 앵커 ID를 찾을 수 없어 해결에 실패했습니다.
ErrorHostingDatasetProcessingFailed 서버가 지정된 앵커의 데이터 세트를 처리할 수 없어 호스팅에 실패했습니다. 기기가 환경에서 데이터를 더 수집한 후에 다시 시도하세요.
ErrorHostingServiceUnavailable ARCore API에 연결할 수 없습니다. 다운로드할 수 없는 원인으로는 여러 가지가 있습니다. 기기가 비행기 모드이거나 인터넷에 연결되어 있지 않을 수 있습니다. 서버로 전송된 요청이 응답 없이 타임아웃되었을 수 있습니다. 네트워크 연결 불량, DNS 사용 불가, 방화벽 문제 또는 기기의 ARCore API 연결 기능에 영향을 줄 수 있는 다른 모든 문제가 있을 수 있습니다.
ErrorInternal 이 앵커의 호스팅 또는 확인 작업이 내부 오류로 완료되었습니다. 앱이 이 오류에서 복구를 시도해서는 안 됩니다.
ErrorNotAuthorized 잘못된 승인으로 인해 앱이 ARCore API와 통신할 수 없습니다. Project Settings(프로젝트 설정) > XR > ARCore Extensions(ARCore 확장 프로그램)에서 유효한 승인 전략을 확인합니다.
ErrorResolvingPackageTooNew 클라우드 앵커를 호스팅하는 데 사용되는 ARCore 확장 프로그램 패키지가 최신 버전이므로 획득에 사용되는 버전보다 호환되지 않으므로 클라우드 앵커를 가져올 수 없습니다.
ErrorResolvingPackageTooOld 클라우드 앵커를 호스팅하는 데 사용되는 ARCore 확장 프로그램 패키지가 획득에 사용된 버전보다 오래되고 호환되지 않아 클라우드 앵커를 가져올 수 없습니다.
ErrorResourceExhausted 애플리케이션이 지정된 Google Cloud 프로젝트에 할당된 요청 할당량을 소진했습니다. Google Developers Console에서 프로젝트의 ARCore API에 대한 추가 할당량을 요청해야 합니다.
None 클라우드 앵커를 사용할 준비가 되지 않았습니다.
Success 이 앵커에 대한 호스팅 또는 확인 작업이 완료되었습니다.
TaskInProgress 이 클라우드 앵커의 호스팅 또는 확인 작업이 진행 중입니다. 작업이 백그라운드에서 완료되면 다음 업데이트 후 클라우드 앵커에 새 상태가 표시됩니다.

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

ARCore API에는 요청 대역폭에 다음과 같은 할당량이 적용됩니다.

할당량 유형 최대 시간 적용 대상
앵커 수 unlimited N/A 프로젝트
앵커 호스트 요청 30 IP 주소 및 프로젝트
앵커 resolve 요청 300 IP 주소 및 프로젝트

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

앱에서 좋은 사용자 경험을 제공하려면 다음을 따르도록 안내하세요.

  • 객체를 배치하여 앵커를 호스팅하기 전에 세션이 시작된 후 몇 초 정도 기다립니다. 이렇게 하면 추적이 안정화될 때까지 시간이 걸립니다.
  • 앵커를 호스팅할 위치를 선택할 때 서로 쉽게 구분할 수 있는 시각적 특징이 있는 영역을 찾으세요. 최상의 결과를 얻으려면 반사되는 표면이나 빈 흰색 벽과 같이 시각적 특징이 없는 표면을 피하세요.
  • 카메라를 관심 중심에서 학습시키면서 기기를 다른 중앙에서 움직여 다양한 각도에서 환경을 매핑함으로써 대략 동일한 물리적 거리를 유지합니다. 이렇게 하면 더 많은 시각적 데이터를 캡처하고 더 강력하게 해결할 수 있습니다.

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

지원 중단 정책

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

다음 단계