Google Cloud에서 ARCore API 사용

플랫폼 선택:

Geospatial API 및 Cloud Anchors와 같은 ARCore 기능은 Google Cloud에서 호스팅되는 ARCore API를 사용합니다. 이러한 기능을 사용할 때 애플리케이션은 사용자 인증 정보를 사용하여 ARCore API 서비스에 액세스합니다.

이 빠른 시작에서는 Google Cloud에서 호스팅되는 ARCore API 서비스와 통신할 수 있도록 애플리케이션을 설정하는 방법을 설명합니다.

새 Google Cloud 프로젝트를 만들거나 기존 프로젝트 사용

기존 프로젝트가 있는 경우 선택합니다.

프로젝트 선택기로 이동

기존 Google Cloud 프로젝트가 없으면 하나 만듭니다.

새 프로젝트 만들기

ARCore API 사용 설정

ARCore API를 사용하려면 프로젝트에서 사용 설정해야 합니다.

ARCore API 사용 설정

승인 방법 설정

Unity 애플리케이션은 권장 방법인 키리스 승인과 API 키 승인이라는 두 가지 승인 방법을 사용하여 ARCore API와 통신할 수 있습니다.

  • Android에서 키리스 승인은 애플리케이션의 패키지 이름과 서명 키의 디지털 지문을 조합하여 애플리케이션을 승인합니다.

    iOS에서 키리스 승인은 API에 대한 액세스를 제어하기 위해 서명된 토큰을 사용합니다. 이 메서드를 사용하려면 토큰에 서명하고 API에 대한 액세스를 제어하는 서버가 있어야 합니다.

  • API 키는 Google Cloud 프로젝트를 식별하는 문자열입니다. API 키는 일반적으로 클라이언트가 액세스할 수 있으므로 안전하다고 간주되지 않습니다. 키리스 승인을 사용하여 ARCore API와 통신하는 것이 좋습니다.

키리스

키리스 인증을 사용하여 앱을 승인하려면 OAuth 2.0 클라이언트 ID를 만드세요.

서명 키 디지털 지문 확인

OAuth 2.0 클라이언트 ID는 앱의 서명 키 지문을 사용하여 앱을 식별합니다.

디버그 서명 디지털 지문을 가져오는 방법

프로젝트를 실행하거나 디버그할 때 Android SDK 도구는 생성된 디버그 인증서를 사용하여 앱에 자동으로 서명합니다.

다음 명령어를 사용하여 디버그 인증서 지문을 가져옵니다.

Mac/Linux
keytool -list -v -alias androiddebugkey -keystore ~/.android/debug.keystore
Windows
keytool -list -v -alias androiddebugkey -keystore %USERPROFILE%\.android\debug.keystore

keytool 유틸리티에서 키 저장소의 비밀번호를 입력하라는 메시지를 표시합니다. 디버그 키 저장소의 기본 비밀번호는 android입니다. 그러면 keytool 유틸리티가 터미널에 지문을 출력합니다. 예를 들면 다음과 같습니다.

   Certificate fingerprint: SHA1: <strong>DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

키 저장소에서 서명 지문을 가져오는 방법

키 저장소 파일이 있는 경우 keytool 유틸리티를 사용하여 지문을 확인합니다.

keytool -list -v -alias your-key-name -keystore path-to-production-keystore

그러면 keytool 유틸리티가 터미널에 지문을 출력합니다. 예를 들면 다음과 같습니다.

   Certificate fingerprint: SHA1: DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

Play 앱 서명에서 앱의 서명 키를 획득하는 방법

Play 앱 서명을 사용하면 Google에서 앱의 서명 키를 관리하고 이 키를 사용하여 APK에 서명합니다. 이 키는 서명 지문에 사용해야 합니다.

  1. Google Play Console의 앱 서명 페이지에서 앱 서명 키 인증서로 스크롤합니다.
  2. SHA-1 인증서 지문을 사용합니다.

OAuth 2.0 클라이언트 ID 만들기

이전 단계의 각 해당 서명 키에 대해 Google Cloud 프로젝트의 사용자 인증 정보에서 OAuth 2.0 클라이언트 ID를 만듭니다.

  • Google Cloud에서 사용자 인증 정보 페이지를 엽니다.

    사용자 인증 정보

  • 사용자 인증 정보 만들기를 클릭하고 메뉴에서 OAuth 클라이언트 ID를 선택합니다.

  • 다음과 같이 필수 입력란을 작성합니다.

    • 애플리케이션 유형: Android를 선택합니다.
    • 패키지 이름: AndroidManifest.xml에 선언된 패키지 이름을 사용합니다.
    • SHA-1 인증서 지문: 이전 단계에서 획득한 지문을 사용합니다.

  • 만들기를 누릅니다.

필요한 라이브러리 포함

  1. 앱의 종속 항목에 com.google.android.gms:play-services-auth:16+을 포함합니다.

  2. 코드 축소를 사용하는 경우 앱의 build.gradle 파일에 추가합니다.

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

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

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

이제 앱이 키리스 인증을 사용하도록 구성되었습니다.

키리스

ARCore는 JSON 웹 토큰을 사용하여 iOS에서 API 호출 승인을 지원합니다. 토큰은 Google 서비스 계정으로 서명해야 합니다.

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

  • 자체 승인 메커니즘이 엔드포인트를 보호해야 합니다.

  • 엔드포인트는 다음과 같이 매번 새 토큰을 생성해야 합니다.

    • 각 사용자에게 고유한 토큰이 부여됩니다.
    • 토큰은 즉시 만료되지 않습니다.

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

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

  1. Google Cloud에서 사용자 인증 정보 페이지를 엽니다.
    사용자 인증 정보
  2. 사용자 인증 정보 만들기 > 서비스 계정을 클릭합니다.
  3. 서비스 계정 세부정보에서 새 계정의 이름을 입력한 다음 만들기를 클릭합니다.
  4. '서비스 계정 권한' 페이지에서 역할 선택 드롭다운으로 이동합니다. 서비스 계정 > 서비스 계정 토큰 생성자를 선택한 다음 계속을 클릭합니다.
  5. 사용자에게 이 서비스 계정에 대한 액세스 권한 부여 페이지에서 완료를 클릭합니다.
  6. 사용자 인증 정보 페이지에서 서비스 계정 섹션을 찾아 방금 만든 계정의 이름을 클릭합니다.
  7. 서비스 계정 세부정보 페이지에서 키 섹션으로 스크롤한 후 키 추가 > 새 키 만들기를 선택합니다.

  8. 키 유형으로 JSON을 선택하고 만들기를 클릭합니다.

    그러면 비공개 키가 포함된 JSON 파일이 컴퓨터에 다운로드됩니다. 다운로드한 JSON 키 파일을 안전한 위치에 저장합니다.

서버에서 토큰 만들기

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

개발 머신에서 토큰 만들기

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

oauth2l fetch --cache "" --jwt --json $KEYFILE --audience "https://arcore.googleapis.com/"

--cache 플래그를 사용하여 빈 캐시 위치를 지정해야 매번 다른 토큰이 생성됩니다. 결과 문자열을 자르세요. 공백이나 줄바꿈 문자가 있으면 API에서 토큰을 거부합니다.

토큰에 서명

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

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

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

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

ARCore 세션에서 토큰 전달

  1. iOS 인증 전략이 AuthenticationToken으로 설정되어 있는지 확인합니다. Unity에서 Edit(수정) > Project Settings(프로젝트 설정) > XR Plug-in Management(XR 플러그인 관리) > ARCore Extensions(ARCore 확장)로 이동합니다. iOS 인증 전략 드롭다운 메뉴에서 인증 토큰 옵션을 선택합니다.

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

    // Designate the token to authorize ARCore API calls
// on the iOS platform. This should be called each time the application's token is refreshed.
ARAnchorManager.SetAuthToken(authToken);

이제 앱이 키리스 인증을 사용하도록 구성되었습니다.

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

  • API 키를 사용하여 세션을 만든 경우 ARCore는 토큰을 무시하고 오류를 기록합니다.

    API 키가 더 이상 필요하지 않으면 Google Developers Console에서 삭제하고 앱에서 삭제합니다.

  • ARCore는 공백이나 특수문자가 포함된 토큰을 무시합니다.

  • 토큰은 일반적으로 1시간 후에 만료됩니다. 사용 중에 토큰이 만료될 가능성이 있는 경우 새 토큰을 획득하여 API에 전달하세요.

API 키

  1. Google Cloud에서 사용자 인증 정보 페이지를 엽니다.
    사용자 인증 정보
  2. 사용자 인증 정보 만들기를 클릭한 후 메뉴에서 API 키를 선택합니다.
    API 키 생성 완료 대화상자에 새로 생성된 키의 문자열이 표시됩니다.

  3. Unity에서 Edit(수정) > Project Settings(프로젝트 설정) > XR Plug-in Management(XR 플러그인 관리) > ARCore Extensions(ARCore 확장)로 이동합니다. 각 타겟 플랫폼 (Android, iOS)의 인증 전략 드롭다운 메뉴에서 API 키 옵션을 선택합니다. 그런 다음 API 키 필드에 API 키를 삽입합니다.

  4. API 키 제한사항에 관한 문서를 검토하여 API 키를 보호하세요.

이제 앱이 API 키를 사용하도록 구성되었습니다.

다음 단계

승인이 구성되면 이를 사용하는 다음 ARCore 기능을 확인하세요.