How to use EasyAR capabilities on Apple Vision Pro

This guide will walk you through the Unity and Xcode project configuration to unlock all EasyAR core capabilities, including Mega cloud localization, for Apple Vision Pro applications.

Before you begin

• Learn how to use the headset samples
• Ensure the development environment meets the following requirements:
  • visionOS 2.0 or later
  • Xcode 16.0 or later with the visionOS simulator for the corresponding visionOS version
  • Recommended Unity version 6000.0.23 or above (LTS version)

Request enterprise API license from Apple Inc.

Since accessing camera frames and parameters on Apple Vision Pro requires an entitlement for enterprise-level APIs, you need to apply to Apple Inc. for a license file that includes this entitlement. For the application and usage of this license, please refer to Building spatial experiences for business apps with enterprise APIs for visionOS.

Important

The Bundle ID in the entitlement obtained from Apple must exactly match the one provided when creating the EasyAR Sense License Key.

How to choose visionOS app mode

Apps running on visionOS can only access ARKit data in Immersive Space. Due to differences in rendering pipelines and APIs, Unity editor-built apps in Immersive Space need to choose between RealityKit with PolySpatial or Metal Rendering with Compositor Services modes.

For the definition of Immersive Space, refer to Apple's official documentation.

For a detailed introduction to Unity's App Mode, refer to the Unity PolySpatial documentation's visionOS Platform Overview.

Tip

App mode selection recommendations

• First choice recommendation: RealityKit with PolySpatial

  If you are new to visionOS, it is recommended to choose this mode first. Its advantages include deep integration with visionOS's system-level rendering features, high stability, and excellent rendering quality.
  This mode does not support custom code shaders (HLSL/ShaderLab) and requires the use of Shader Graph, with only features that pass PolySpatial compatibility checks being supported (they will be converted to MaterialX).

  Unity's built-in Standard (Built-in) and Lit (URP) shaders have been pre-adapted by the official team and can be used directly.

• Advanced/specific needs: Metal Rendering with Compositor Services

  Suitable for projects with a large number of existing 3D assets to migrate or those that must use custom shaders.
  Since Unity handles all rendering logic in this mode, bypassing the system's RealityKit pipeline, the rendering quality is generally inferior to RealityKit and may encounter unforeseen rendering issues.

EasyAR integration recommendations:

When attempting to integrate EasyAR, always start by using the RealityKit with PolySpatial mode to establish the basic workflow. This effectively isolates variables, avoiding the entanglement of Metal-level adaptation issues with AR-related problems, which can make troubleshooting difficult.

Configuration in unity project

The following configurations are required in the unity project:

Import necessary packages for Unity project

Unity 6 (Recommended):

• RealityKit/Hybrid
• Metal

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

Important

All package versions must be strictly consistent.

Unity 6 is recommended, as some early Unity 2023.x versions do not yet support visionOS.

Unity 2022.3:

• RealityKit/Hybrid
• Metal

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

Important

All package versions must be strictly consistent.

1.3.x versions are not supported. Please ensure the version is locked to 1.2.3.

Select build platform

Click File > Build Profiles in the menu bar to switch the Platform to visionOS.

Configure input system

Ensure using the latest version of Input System Package:

Click Edit > Project Settings > Player in the menu bar, and set the Active Input Handling slot to Input System Package(New).

Unity may then require a project restart. Click Apply to make the changes take effect.

Configure XR Plug-in Management

Click Edit > Project Settings > XR Plug-in Management in the menu bar, and check Apple visionOS under Plug-in Providers in the visionOS tab.

Configure Apple visionOS plugin

Click Edit > Project Settings > XR Plug-in Management > Apple visionOS in the menu bar.

Select the appropriate App Mode based on the previous introduction.

Note

Windowed mode does not support AR capabilities as it does not run in Immersive Space.

Hybrid mode requires manual switching between Metal and RealityKit modes, which is not recommended due to its complexity. For details, refer to Unity's official documentation on this mode.

Next, make the following changes on the same page:

• Add a description in the World Sensing Usage Description field.

• Set Metal Immersion Style to Mixed.

• Set Reality Kit Immersion Style to Mixed.

• Check IL2CPP Large Exe Workaround.

[Only required for RealityKit mode] Import TextMesh Pro Essentials

Click on the menu bar Edit > Project Settings > TextMesh Pro > click Import TMP Essentials

Note

Currently, RealityKit with PolySpatial mode only supports TextMesh Pro text. If not imported, text rendering will not work.

[RealityKit mode only] Polyspatial settings

Click Edit > Project Settings > Polyspatial in the menu bar, and make the following changes on this page:

• Set Default Volume Camera Window Config to Default Unbounded Configuration.

• Check Auto-Create Volume Camera

If you need to specify Default Volume Camera Window Config separately, make sure its Mode is Unbounded.

If there is a Volume Camera in the scene, delete it.

Warning

• Volume Camera with World Transform values other than identity is not supported.
• If you need to add a unique custom Volume Camera to the scene for special reasons, make sure:
  • Set its World Transform to identity.
  • Ensure its Volume Camera Window Configuration Mode is set to Unbounded.
  • Use it only after fully understanding its meaning and purpose in the Unity official documentation.

[When Using Mega] Add Location Usage Description

Caution

If the Location permission is enabled in EasyAR configuration (when using the Mega feature), a permission description must be added; otherwise, the build will fail.

Since the Location Usage Description field is currently not displayed in Unity's Project Settings > Player > visionOS tab, please follow these steps to configure it:

1. Switch platform tab: Temporarily switch the tab to iOS.
2. Enter description: Fill in the necessary permission usage description in the Location Usage Description slot.
3. Switch back to visionOS: Switch the tab back to visionOS, and the previously entered configuration will automatically be retained and take effect.

Configuration in the Xcode project

The following configurations are required in the Xcode project obtained through Unity packaging:

Configure camera data entitlement

• Copy the obtained Enterprise.license file to the Xcode project folder.

  

• Drag the Enterprise.license from the Xcode project folder into the Xcode project.

  

Modify info.plist to enable file saving and sharing

To record EIF in the app and share it to computers or other devices via the visionOS Files app, you need to add and modify the following fields in Info.plist:

• Add LSSupportsOpeningDocumentsInPlace and set its value to true.

• Add UIFileSharingEnabled and set its value to true.

Tip

The Key displayed in Xcode may differ from the manually added string (e.g., entering LSSupportsOpeningDocumentsInPlace but displaying Supports opening documents in place is normal).