Apple Client: Setup and Build#

Note

Applies to: Spatial Extensions, Kit 109.0.3+, CloudXR 6

This setup workflow walks you through setting up the CloudXR Apple Generic Viewer, configuring Xcode, and building for Apple Vision Pro or iPad.

Prerequisites#

Requirement

Value

macOS

Apple Silicon or Intel Mac

Xcode

16.4 or later

Swift

5.9 or later

visionOS SDK

2.4 (for Vision Pro)

iOS SDK

18.0 (for iPad)

Apple Developer Program

Required for Low-Latency Streaming entitlement

Low-Latency Streaming Entitlement

The Low-Latency Streaming entitlement requires an active Apple Developer Program membership. Without it, you can still build and run the app, but streaming performance can be degraded.

To build without the entitlement, remove or clear the Code Signing Entitlements build setting.

Step 1: Clone the Repository#

Clone the Generic Viewer#
git clone https://github.com/NVIDIA/cloudxr-apple-generic-viewer.git
cd cloudxr-apple-generic-viewer

Step 2: Open the Xcode Project#

open CloudXRViewer.xcodeproj

Step 3: Add CloudXR Framework#

The CloudXR Framework provides the CloudXRKit SDK. Add it as a Swift Package dependency.

  1. In Xcode, right-click the project in the navigator -> Add Package Dependencies

  2. Enter the URL: https://github.com/NVIDIA/cloudxr-framework

  3. Select the appropriate version

  4. Add the package to your target(s):

    • CloudXRViewer-visionOS (for Apple Vision Pro)

    • CloudXRViewer-iOS (for iPad)

If you have the CloudXR Framework SDK downloaded locally:

  1. Download the SDK (e.g., cloudxr-sdk-external-6.0.2-rc2.zip)

  2. Unzip to a local directory

  3. In Xcode: right-click the project -> Add Package Dependencies -> Add Local…

  4. Navigate to the unzipped framework directory

  5. Add to the appropriate target(s)

Step 4: Configure Code Signing#

  1. Select the project in the Xcode navigator

  2. Select your target (CloudXRViewer-visionOS or CloudXRViewer-iOS)

  3. Go to the Signing & Capabilities tab

  4. Select your development team

  5. Ensure the bundle identifier is unique (e.g., com.yourcompany.cloudxr-viewer)

The project includes a Config.xcconfig file with default settings:

Config.xcconfig#
MARKETING_VERSION = 6.0.0
PRODUCT_BUNDLE_IDENTIFIER = com.nvidia.cloudxr-viewer

Tip

Change the bundle identifier if it does not match your team’s provisioning profile.

Step 5: Select Target and Destination#

  1. Select the CloudXRViewer-visionOS scheme

  2. Choose your destination:

Destination

Use Case

Apple Vision Pro (connected device)

Full streaming + XR

Apple Vision Pro (Designed for iPad)

iPad compatibility mode

visionOS Simulator

UI testing only – streaming will not work

  1. Select the CloudXRViewer-iOS scheme

  2. Choose your destination:

Destination

Use Case

Your iPad (connected device)

Full streaming + touch

iOS Simulator

UI testing only – streaming will not work

Step 6: Build and Run#

Press Cmd+R or click the Run button to build and deploy.

On first build, Xcode will:

  1. Resolve the CloudXR Framework package dependency

  2. Compile the project

  3. Deploy to the selected device or simulator

Tip

If you encounter code signing issues, verify that your Apple Developer Program membership is active and that provisioning profiles are up to date. See Troubleshooting for common issues.

Project Structure#

Full project directory layout
cloudxr-apple-generic-viewer/
├── CloudXRViewer/
│   ├── Common/                    # Shared code
│   │   ├── AppDelegate.swift      # Application delegate
│   │   ├── AppModel.swift         # Session state model
│   │   ├── ViewerApp.swift        # App entry point
│   │   ├── SessionConfigView.swift # Connection UI
│   │   ├── ServerActionsView.swift # Data channel actions
│   │   └── ...
│   ├── iOS/                       # iPad-specific views
│   │   ├── StreamingView+iOS.swift
│   │   └── ...
│   └── visionOS/                  # Vision Pro-specific views
│       ├── ImmersiveView.swift
│       ├── WindowUI.swift
│       └── ...
├── CloudXRViewer.xcodeproj
├── Config.xcconfig
└── README.md

Key Files for Customization#

File

Purpose

SessionConfigView.swift

Connection UI – modify to change configuration options

ServerActionsView.swift

Data channel buttons – modify to send custom messages (see Scene Integration and Code Snippets)

AppModel.swift

Session lifecycle – modify to change connection behavior

Config.xcconfig

Build configuration (version, bundle ID)

Settings Bundle (iOS)#

The iOS version includes a Settings.bundle that exposes runtime options in the iOS Settings app:

Setting

Description

persistLaunchWindow

Keep launch window open after connecting

showPropertyWindow

Show the property inspection window

Next Steps#

Connect to Server

Configure and connect to your Kit XR server.

Apple Client: Connect to Server
Code Snippets

Ready-to-use Swift snippets for structured messaging, gestures, variant switching, portals, and more.

CloudXR Cookbook: Common Feature Snippets

See also

Scene Integration – Wire up data channel messages to Kit