Table of Contents

Apple Vision Pro에서 EasyAR 기능 사용하기

이 가이드는 Apple Vision Pro 앱에서 Mega 클라우드 위치 기능을 포함한 모든 EasyAR 핵심 기능을 사용할 수 있도록 Unity와 Xcode 프로젝트를 구성하는 방법을 안내합니다.

시작하기 전에

  • 헤드셋 샘플 사용하기를 익힙니다.
  • 개발 환경이 다음 요구사항을 만족하는지 확인합니다.
    • visionOS 2.0 이상
    • visionOS 버전에 대응하는 Xcode 16.0 이상 및 visionOS simulator 설치
    • 권장 Unity 버전: 6000.0.23 이상의 LTS 버전

Apple Inc.에 기업용 API 라이선스 신청

Apple Vision Pro에서 카메라 영상과 파라미터를 얻으려면 enterprise API를 통한 entitlement가 필요하므로, 해당 entitlement를 포함한 license 파일을 **Apple Inc.**에 신청해야 합니다. 신청 및 사용 방법은 Building spatial experiences for business apps with enterprise APIs for visionOS를 참고하세요.

중요

Apple에서 발급받은 entitlement의 Bundle ID는 EasyAR Sense License Key 생성 시 입력한 값과 정확히 일치해야 합니다.

visionOS App Mode 선택 방법

visionOS에서 실행되는 앱은 Immersive Space에서만 ARKit 데이터를 얻을 수 있습니다. Unity 에디터로 빌드한 앱은 Immersive Space에서 렌더링 흐름과 API가 다르므로 RealityKit with PolySpatial 또는 Metal Rendering with Compositor Services 중 하나를 선택해야 합니다.

Immersive Space의 정의는 Apple의 공식 문서를 참고하세요.

Unity의 App Mode에 대한 자세한 소개는 Unity PolySpatial 문서의 visionOS Platform Overview를 참고하세요.

팁

App Mode 선택 권장 사항

  • 1순위 추천: RealityKit with PolySpatial

    visionOS를 처음 접한다면 이 모드를 우선 추천합니다. visionOS의 시스템 레벨 렌더링 기능과 깊이 통합되어 안정성이 높고 렌더링 품질이 좋습니다. 이 모드는 사용자 정의 코드 셰이더(HLSL/ShaderLab)를 지원하지 않으므로 Shader Graph를 사용해야 하며, PolySpatial 호환성 검사를 통과한 기능만 지원합니다(MaterialX로 변환됨).

    Unity 내장 Standard (Built-in) 및 Lit (URP) 셰이더는 공식적으로 미리 적응되어 있어 바로 사용할 수 있습니다.

  • 고급/특정 요구: Metal Rendering with Compositor Services

    많은 기존 3D 에셋을 이전해야 하거나 사용자 정의 셰이더가 반드시 필요한 복잡한 프로젝트에 적합합니다. 이 모드에서는 Unity가 모든 렌더링 로직을 담당하고 시스템의 RealityKit 파이프라인을 우회하므로, 렌더링 품질은 일반적으로 RealityKit보다 떨어질 수 있고 예기치 않은 렌더링 문제가 발생할 수 있습니다.

EasyAR 연동 권장 사항:

EasyAR를 연동하려면 반드시 먼저 RealityKit with PolySpatial 모드로 기본 흐름을 통과시켜 보세요. 이렇게 하면 Metal 하위 호환 문제와 AR 관련 문제가 뒤섞여 원인을 찾기 어려워지는 상황을 효과적으로 분리할 수 있습니다.

Unity 프로젝트의 설정

Unity 프로젝트에서는 다음 설정이 필요합니다.

Unity 프로젝트에 필요한 Package 가져오기

Unity 6(권장):

  • com.unity.xr.visionos (2.0.4+)
  • com.unity.polyspatial (2.0.4+)
  • com.unity.polyspatial.visionos (2.0.4+)
중요

모든 Package의 버전 번호는 반드시 엄격하게 일치해야 합니다.

Unity 6 사용을 우선 권장합니다. 일부 초기 Unity 2023.x 버전은 아직 visionOS를 지원하지 않습니다.

Unity 2022.3:

  • com.unity.xr.visionos (1.2.3)
  • com.unity.polyspatial (1.2.3)
  • com.unity.polyspatial.visionos (1.2.3)
중요

모든 Package 버전 번호는 반드시 엄격하게 일치해야 합니다.

1.3.x 버전은 지원하지 않으므로, 반드시 1.2.3으로 고정하세요.

Build Platform 선택

메뉴 바에서 File > Build Profiles를 클릭해 Platform을 visionOS로 전환합니다.

Build Platform 전환

Input System 설정

새 버전의 Input System Package를 사용해야 합니다.

메뉴 바에서 Edit > Project Settings > Player를 클릭한 뒤 Active Input Handling 항목을 **Input System Package(New)**로 설정합니다.

이후 Unity가 프로젝트 재시작을 요구할 수 있습니다. Apply를 클릭해 변경 사항을 적용합니다.

Input System 변경 적용

XR Plug-in Management 설정

메뉴 바에서 Edit > Project Settings > XR Plug-in Management를 클릭하고, visionOS 탭의 Plug-in Providers에서 Apple visionOS를 선택합니다.

visionOS 플러그인 선택

Apple visionOS 플러그인 설정

메뉴 바에서 Edit > Project Settings > XR Plug-in Management > Apple visionOS를 클릭합니다.

앞서 설명한 내용을 바탕으로 적절한 App Mode를 선택합니다.

App Mode 선택

참고

Windowed 모드는 Immersive Space에서 실행되지 않으므로 AR 기능을 사용할 수 없습니다.

Hybrid 모드는 개발자가 Metal과 RealityKit 모드 사이를 수동으로 전환해야 합니다. 사용 방식이 복잡하므로 권장하지 않으며, 자세한 내용은 Unity 공식 설명을 참고하세요.

같은 페이지에서 다음 항목도 수정합니다.

  • World Sensing Usage Description 슬롯에 설명을 추가합니다.

  • Metal Immersion Style을 Mixed로 설정합니다.

  • Reality Kit Immersion Style을 Mixed로 설정합니다.

  • IL2CPP Large Exe Workaround를 체크합니다.

visionOS 플러그인 설정 수정

[RealityKit 모드만 필요] TextMesh Pro Essentials 가져오기

메뉴 바에서 Edit > Project Settings > TextMesh Pro > Import TMP Essentials를 클릭합니다.

TMP Essentials 가져오기

참고

현재 RealityKit with PolySpatial 모드는 TextMesh Pro 텍스트만 지원하므로, 이를 가져오지 않으면 텍스트를 렌더링할 수 없습니다.

[RealityKit 모드만 필요] PolySpatial 관련 설정

메뉴 바에서 Edit > Project Settings > PolySpatial를 클릭한 뒤, 다음 항목을 수정합니다.

  • Default Volume Camera Window Config를 Default Unbounded Configuration으로 설정합니다.

  • Auto-Create Volume Camera를 체크합니다.

PolySpatial 설정

별도로 Default Volume Camera Window Config를 지정해야 한다면, 반드시 Mode가 Unbounded인지 확인해야 합니다.

Mode가 Unbounded인지 확인

씬에 Volume Camera가 있다면 삭제합니다.

씬의 Volume Camera 삭제

경고
  • World Transform 값이 identity가 아닌 Volume Camera는 지원하지 않습니다.
  • 특별한 이유로 씬에 하나뿐인 사용자 정의 Volume Camera를 추가해야 한다면, 반드시 다음을 지켜야 합니다.
    • World Transform을 identity로 설정합니다.
    • Volume Camera Window Configuration의 Mode를 Unbounded로 설정합니다.
    • Unity 공식 문서에서 그 의미와 용도를 완전히 이해한 뒤 사용합니다.

[Mega 사용 시] Location Usage Description 추가

주의

EasyAR 설정에서 Location 권한을 활성화한 경우(Mega 기능 사용 시), 권한 설명을 반드시 추가해야 합니다. 그렇지 않으면 Build가 실패합니다.

현재 Unity의 Project Settings > Player > visionOS 탭에는 Location Usage Description 필드가 보이지 않으므로, 다음 순서로 설정합니다.

  1. 플랫폼 탭 전환: 탭을 잠시 iOS로 바꿉니다.
  2. 설명 입력: Location Usage Description 슬롯에 필요한 권한 용도 설명을 입력합니다.
  3. visionOS로 복귀: 탭을 다시 visionOS로 돌리면 방금 입력한 설정이 자동으로 유지되고 적용됩니다.

Location Description

Xcode 프로젝트의 설정

Unity로 패키징한 Xcode 프로젝트에서는 다음 설정이 필요합니다.

카메라 데이터 entitlement 설정

  • 발급받은 Enterprise.license 파일을 Xcode 프로젝트 폴더로 복사합니다.

    Xcode 프로젝트 폴더에 복사

  • Xcode 프로젝트 폴더에 있는 Enterprise.license를 Xcode 프로젝트 안으로 드래그합니다.

    Xcode 프로젝트로 이동

앱이 파일을 저장하고 전달할 수 있도록 info.plist 수정

앱에서 EIF를 녹화하고 visionOS의 파일 앱을 통해 PC나 다른 기기로 전달하려면 Info.plist에 다음 필드를 추가하고 수정해야 합니다.

  • LSSupportsOpeningDocumentsInPlace를 추가하고 값을 true로 설정합니다.

  • UIFileSharingEnabled를 추가하고 값을 true로 설정합니다.

Info.plist 수정

팁

필드를 추가한 뒤 Xcode 화면에 표시되는 Key는 수동으로 입력한 문자열과 다를 수 있습니다(예: LSSupportsOpeningDocumentsInPlace를 입력했는데 Supports opening documents in place로 표시되는 경우). 이는 정상입니다.