# Set up the Niantic SDK Source: https://www.nianticspatial.com/docs/nsdk/setup/?platform=swift # Set up the NSDK in Swift The Swift NSDK plugin enables you to integrate AR capabilities into any Xcode project. It is distributed as a Swift Package hosted on GitHub and can be added directly through Xcode's built-in Swift Package Manager. ### Prerequisites Before you begin, make sure you have Xcode 12.0 or later, an iOS device with ARKit support, Apple Developer account setup, and basic familiarity with Swift and ARKit. ## AI set up > **Tip:** > > NSDK supports AI-assisted development > > NSDK publishes **Skills**: packaged setup workflows that an AI coding assistant reads > directly. This is a supported way to work with NSDK, and usually the fastest and > smoothest path to a working integration -- the assistant carries out the steps on this > page with you, checking your project as it goes. > > **Download the Swift setup Skill** To use an **AI coding assistant** to set up the NSDK for you, do the following: 1. Extract and place the folder into your AI assistant's skills directory. For example: - Claude Code: `.claude/skills/` - Codex: `.agents/skills/` 2. Create or open an existing Xcode project. If you're creating a new project, use the **Augmented Reality App** template and **SwiftUI** interface. 3. Ask the assistant to help you add and configure NSDK. The assistant will guide you through the required Xcode steps and help configure the project. ## Manual set up To **manually** set up the NSDK in Swift, you will need to: 1. [Create an account](#create-an-account-1). 2. [Add the NSDK package](#add-the-nsdk-package). 3. [Create an NSDK session](#create-an-nsdk-session). 4. [Provide frame and sensor data](#provide-frame-and-sensor-data). 5. [Review permissions](#permissions). Steps to manually set up the NSDK are shown in the following sections. --- ### Create an account Before getting started with the NSDK setup, follow the steps to [create a Scaniverse account](https://www.nianticspatial.com/docs/nsdk/create_account/#create-a-scaniverse-account). You will need an access token to initialize the NSDK session. For development and internal testing, create a developer token in [Scaniverse Web](https://scaniverse.nianticspatial.com/signin) and pass it to NSDK as-is; no exchange step is needed. For production apps, use an access token from your backend. For more information, see [Authorization](https://www.nianticspatial.com/docs/nsdk/auth_getting_started/), [Generate developer tokens](https://www.nianticspatial.com/docs/nsdk/auth_developer_token/), and [Generate access tokens](https://www.nianticspatial.com/docs/nsdk/auth_backend/). ### Add the NSDK package 1. Open your project in Xcode or create a new one: - When creating a new project: 1. Start with the "Augmented Reality App" template in Xcode 11 or later. 2. Select SwiftUI as your interface technology. 3. In your project, ensure you have imported the SwiftUI, RealityKit, and ARKit frameworks. 2. Add the NSDK Swift Package: 1. On the top menu bar, go to **File** -> **Add Package Dependencies...** 2. In the search bar, enter the package URL: ``` https://github.com/nianticspatial/nsdk-library-xcframework ``` 3. For the version rule, choose **Exact Version** and enter the NSDK version you want, then click **Add Package**. You can find versions on the [NSDK Swift package releases page](https://github.com/nianticspatial/nsdk-library-xcframework/releases). 4. When prompted, select **NSDK** in the package product list and click **Add Package**. 3. Navigate to your project target. 4. Configure your project. 1. Select **General -> Scroll down to Frameworks, Libraries, and Embedded Content**. 2. Set NSDK to **Embed & Sign**. 5. Add required privacy descriptions to your `Info.plist` NSDK uses the camera for AR and location for GPS features. Add both usage descriptions to `Info.plist` as follows: 1. In Xcode, click on the **Info** tab, locate **Custom iOS Target Properties**, hover over any key and click the **+** icon to add a new entry. (image: Add new property to plist) 2. Add both of the following keys with a short description of how your app uses each. **If either key is missing, iOS terminates the app** the first time NSDK accesses the camera or location. The following table provides example key descriptions: | Key | Example value | |-----|---------------| | `Privacy - Camera Usage Description` | `Required for AR` | | `Privacy - Location When In Use Usage Description` | `Required for AR features` | The following image shows how to add a key to `Info.plist` in the Xcode UI: (image: Add location property to plist) ### Create an NSDK session To create an NSDK session, you will need a valid access token from your Niantic Spatial account. Create an `NSDKSession` object to access NSDK features as shown in the following simple initializer: ```swift let nsdkSession = NSDKSession( accessToken: "YOUR_ACCESS_TOKEN" ) ``` Most apps can use the access-token initializer shown in the previous example. If your app needs more control over NSDK configuration, you can also create the session from a `Configuration` object or a JSON configuration file. For those options, see the [NSDKSession API reference](https://www.nianticspatial.com/docs/api/swift/NSDK.class-NSDKSession). Create one `NSDKSession` and reuse it for the life of your app. When you no longer need the session, call `destroyAll()` to release its resources. If you acquired a child session from `NSDKSession`, call `destroy(_:)` for that child session. Do not create a second `NSDKSession` while the first one is still active. If you need a new session, call `destroyAll()` on the current session first and wait for it to finish. ### Provide frame and sensor data Before you use features that rely on live AR or device data, connect your `NSDKSession` to a data source. The following code example creates a `DefaultSessionDataSource` with your ARKit session and orientation reporter, then assigns it to `NSDKSession` so it can receive camera frames and sensor data: ```swift import ARKit import NSDK let dataSource = DefaultSessionDataSource( session: arSession, orientationReporter: self ) nsdkSession.dataSource = dataSource ``` After you assign the data source, `NSDKSession` can read camera frames and sensor data from it. - `arSession` should be the `ARSession` your app is using. - `orientationReporter` reports the current screen orientation. In most apps, your view controller provides it. To report the current orientation, conform your view controller to `UIOrientationReporter`. The following code example adds a property to your view controller that returns the current interface orientation so NSDK can interpret AR data correctly: ```swift extension ViewController: UIOrientationReporter { var currentOrientation: NSDKScreenOrientation { let orientation = view.window?.windowScene?.interfaceOrientation ?? .unknown return NSDKScreenOrientation(orientation) } } ``` Configure the data source once for the session. This step is required for features that depend on live AR or device data. ### Call update for each ARKit frame ARKit delivers camera data one frame at a time. A frame is one camera image and its related device data. After you assign a data source, NSDK can read that data, but NSDK does not process it until you call [NSDKSession.update()](https://www.nianticspatial.com/docs/api/swift/NSDK.NSDKSession.method-update). Call `update()` once each time ARKit provides a new frame. If your view controller implements `ARSessionDelegate`, ARKit calls [session(_:didUpdate:)](https://developer.apple.com/documentation/arkit/arsessiondelegate/session(_:didupdate:)) whenever a new frame is available. You can call `update()` in your view controller as shown in the following example: ```swift extension ViewController: ARSessionDelegate { func session(_ session: ARSession, didUpdate frame: ARFrame) { nsdkSession.update() } } ``` If you use `ARSessionDelegate`, make sure your app is set up to receive [session(_:didUpdate:)](https://developer.apple.com/documentation/arkit/arsessiondelegate/session(_:didupdate:)) callbacks. If you do not call `update()` for each frame, NSDK does not process camera frames. Features such as VPS localization, depth, meshing, and semantics do not run, and NSDK does not show an error. ### Permissions NSDK uses two device permissions: **camera** for AR and **location** for GPS and visual localization. The usage descriptions in [Add the NSDK package](#add-the-nsdk-package) are required, but they are not enough on their own. Your app must also obtain each permission at runtime. When your app starts ARKit, iOS prompts for camera access automatically. Location works differently. iOS does not prompt for location access automatically. Request location access before you use a feature that depends on it. If you do not, GPS and visual localization will not run, and NSDK does not show an error or a permission dialog. Request location access as shown in the following code example: ```swift import CoreLocation let locationManager = CLLocationManager() locationManager.requestWhenInUseAuthorization() ``` Refer to the [Swift sample projects](https://www.nianticspatial.com/docs/nsdk/sample_projects/) for examples of handling permission checks and requests. ## Next steps After your project is set up, continue to [Swift sample projects](https://www.nianticspatial.com/docs/nsdk/sample_projects/) to explore working examples of NSDK features. ### Example code The following example provides a complete base view controller for an NSDK project. It is used by the [Swift how-to guides](https://www.nianticspatial.com/docs/nsdk/features/ar_effects/#guides) and can be used as a foundation to build your own application. Before using it, [create a Niantic Spatial account](https://www.nianticspatial.com/docs/nsdk/create_account/) and [authenticate](https://www.nianticspatial.com/docs/nsdk/auth_client/). #### Click to reveal `BaseARViewController.swift` ```swift import UIKit import RealityKit import ARKit import NSDK // Base view controller for ARKit and NSDK class BaseARViewController: UIViewController, UIOrientationReporter, NSDKViewDelegate { // NSDK AR view public let arView: NSDKView // Active NSDK session public private(set) var nsdkSession: NSDKSession! // Data source for frames and sensors private var nsdkDataSource: NSDKSessionDataSource? // Access token var accessToken: String = "YOUR_ACCESS_TOKEN" // MARK: UIOrientationReporter // Current device orientation var currentOrientation: NSDKScreenOrientation { let uiOrientation = arView.window?.windowScene?.interfaceOrientation ?? .unknown return NSDKScreenOrientation(uiOrientation) } // MARK: Initialization init() { self.arView = NSDKView() super.init(nibName: nil, bundle: nil) } required init?(coder aDecoder: NSCoder) { fatalError("not supported") } // MARK: Lifecycle // Setup view and NSDK override func viewDidLoad() { super.viewDidLoad() arView.setup(in: view) setupNsdk() } // Create session and data source private func setupNsdk() { nsdkSession = NSDKSession( accessToken: accessToken ) if let playbackSession = arView.session as? PlaybackSession { nsdkDataSource = PlaybackSessionDataSource(session: playbackSession) } else { nsdkDataSource = DefaultSessionDataSource( session: arView.session, orientationReporter: self ) } nsdkSession.dataSource = nsdkDataSource } // Start AR session override func viewDidAppear(_ animated: Bool) { super.viewDidAppear(animated) let configuration = ARWorldTrackingConfiguration() configuration.planeDetection = [.horizontal, .vertical] if ARUtils.isLidarAvailable() { configuration.frameSemantics.insert(.sceneDepth) } arView.session.run(configuration) arView.delegate = self UIApplication.shared.isIdleTimerDisabled = true } // Pause AR session override func viewWillDisappear(_ animated: Bool) { super.viewWillDisappear(animated) arView.session.pause() } // MARK: Entity Management // Add anchor entity func addAnchorEntity(for anchor: ARAnchor) -> AnchorEntity { let anchorEntity = AnchorEntity(anchor: anchor) arView.scene.addAnchor(anchorEntity) return anchorEntity } // Update anchor entity func updateAnchorEntity(_ entity: Entity, for anchor: ARAnchor) {} // MARK: NSDKViewDelegate // Update NSDK each frame func session(_ session: ARSession, didUpdate frame: ARFrame) { nsdkSession.update() } // Update NSDK for playback func playbackSession(_ session: PlaybackSession, didUpdate frame: PlaybackFrame) { nsdkSession.update() } // Handle interruption end func sessionInterruptionEnded(_ session: ARSession) { resetTracking() } // Handle AR errors func session(_ session: ARSession, didFailWithError error: Error) { guard error is ARError else { return } resetTracking() } // Reset tracking private func resetTracking() { let configuration = ARWorldTrackingConfiguration() configuration.planeDetection = [.horizontal, .vertical] arView.session.run( configuration, options: [.resetTracking, .removeExistingAnchors] ) } } ```