Table of Contents

Apple Vision Pro에서 EasyAR 기능을 사용하는 방법

이 가이드는 Apple Vision Pro 앱에 Mega 클라우드 위치 기반을 포함한 모든 EasyAR 핵심 기능을 잠금 해제하기 위해 Unity 및 Xcode 프로젝트 구성을 안내합니다.

시작하기 전에

  • 헤드셋 샘플 사용 방법 학습
  • 개발 환경이 다음 요구 사항을 충족하는지 확인:
    • visionOS 2.0 이상
    • 해당 visionOS 버전과 호환되는 Xcode 16.0 이상 및 visionOS 시뮬레이터 설치
    • 권장 Unity 버전: 6000.0.23 이상의 LTS 버전

Apple Inc.에 엔터프라이즈급 API 라이선스 신청

Apple Vision Pro에서 카메라 영상 및 파라미터 획득은 엔터프라이즈급 API에 해당하는 entitlement가 필요하므로, **Apple Inc.**에 해당 entitlement가 포함된 라이선스 파일을 신청해야 합니다. 라이선스 신청 및 사용 방법은 Building spatial experiences for business apps with enterprise APIs for visionOS를 참조하십시오.

중요

Apple로부터 획득한 entitlement의 번들 ID는 EasyAR Sense 라이선스 키 생성 시 입력한 것과 정확히 일치해야 합니다.

VisionOS 앱 모드를 선택하는 방법

visionOS에서 실행되는 앱은 Immersive Space에서만 ARKit 데이터를 획득할 수 있습니다. Unity 에디터로 빌드된 앱은 Immersive Space에서 렌더링 파이프라인 및 API 차이로 인해 RealityKit with PolySpatial 또는 Metal Rendering with Compositor Services 모드 중 선택해야 합니다.

Immersive Space 정의는 Apple 공식 문서를 참조하십시오.

Unity 앱 모드에 대한 자세한 설명은 Unity PolySpatial 문서의 visionOS Platform Overview를 참조하십시오.

팁

앱 모드 선택 권장 사항

  • 첫 번째 추천: 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 프로젝트에 필요한 패키지 임포트

Unity 6 (권장):

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

모든 패키지 버전은 반드시 정확히 일치해야 합니다.

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)
중요

모든 패키지 버전은 반드시 정확히 일치해야 합니다.

1.3.x 버전은 지원되지 않으므로 반드시 1.2.3으로 고정하십시오.

빌드 플랫폼 선택

메뉴 바에서 File > Build Profiles를 클릭하고 플랫폼을 visionOS로 전환하십시오.

빌드 플랫폼 전환

입력 시스템 구성

최신 Input System Package 사용을 확인하십시오:

메뉴 바에서 Edit > Project Settings > Player를 클릭하고 Active Input Handling 슬롯을 **Input System Package(New)**로 설정하십시오.

이후 Unity가 프로젝트 재시작을 요청할 수 있으며, Apply를 클릭하여 변경 사항을 적용하십시오.

입력 시스템 변경 적용

XR 플러그인 관리 구성

메뉴 바에서 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를 클릭하십시오.

이전 설명에 따라 적절한 앱 모드를 선택하십시오.

앱 모드 선택

참고

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 사용 시] 위치 사용 설명 추가

주의

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

현재 Unity의 Project Settings > Player > visionOS 탭에 Location Usage Description 필드가 표시되지 않으므로 다음 단계로 구성하십시오:

  1. 플랫폼 탭 전환: 일시적으로 iOS 탭으로 전환하십시오.
  2. 설명 입력: Location Usage Description 슬롯에 필요한 권한 사용 설명을 입력하십시오.
  3. visionOS로 전환: 탭을 다시 visionOS로 전환하면 방금 입력한 구성이 자동으로 유지되고 적용됩니다.

위치 설명

Xcode 프로젝트 구성

Unity로 빌드된 Xcode 프로젝트에서 다음 구성을 수행해야 합니다:

카메라 데이터 entitlement 구성

  • 획득한 Enterprise.license 파일을 Xcode 프로젝트 폴더에 복사하십시오.

    Xcode 프로젝트 폴더에 복사

  • Xcode 프로젝트 폴더의 Enterprise.license를 Xcode 프로젝트로 드래그하십시오.

    Xcode 프로젝트로 이동

앱이 파일 저장 및 전송 가능하도록 info.plist 수정

앱에서 EIF 녹화 후 visionOS 파일 앱을 통해 컴퓨터나 기타 장치로 전송해야 하는 경우 Info.plist에 다음 필드를 추가하고 수정하십시오:

  • LSSupportsOpeningDocumentsInPlace 추가 후 값을 true로 설정하십시오.
  • UIFileSharingEnabled 추가 후 값을 true로 설정하십시오.

Info.plist 수정

팁

필드 추가 후 Xcode 인터페이스에 표시되는 Key가 수동으로 입력한 문자열과 다를 수 있습니다(예: LSSupportsOpeningDocumentsInPlace 입력 시 Supports opening documents in place로 표시). 이는 정상입니다.