iOS SDK

Overview

The native iOS VPS SDK lets you localize users inside VPS maps using ARKit tracking. The XCFramework works across UIKit, RealityKit, and SwiftUI apps. Follow the Immersal-style flow below: check prerequisites, add the package, grant permissions, and initialize the service.

Prerequisites

• iOS 12.0 or newer
• Xcode 12+ with Swift 5 toolchain
• Device capable of running ARKit (no simulator support)

Install Options

Add via Swift Package Manager

1. In Xcode pick File → Add Packages….
2. Enter https://github.com/WebAR-Studio/was-vps-ios.git.
3. Select the branch or tag you need and add the package to your target.

Manual integration

1. Clone the repository:

   git clone https://github.com/WebAR-Studio/was-vps-ios.git

2. Drag WASVPS.xcframework into your project.
3. Under General → Frameworks, Libraries, and Embedded Content make sure the framework is embedded.

Configure Permissions

Add camera and location usage descriptions to Info.plist so the system can display prompts.

<key>NSCameraUsageDescription</key>
<string>This app requires access to the camera to display augmented reality content.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs access to your location to place AR content accurately.</string>
<key>NSLocationTemporaryUsageDescriptionDictionary</key>
<dict>
    <key>VPSLocalization</key>
    <string>Enable precise location for accurate AR content positioning.</string>
</dict>

Initialize VPS

Use VPSBuilder.initializeVPS to create a VPSService. Pass in the ARSession, your API key, and location IDs.

Need an API key? Grab one at space.web-ar.studio or email support@webar3.com / support@web-ar.studio.

import ARKit
import WASVPS

final class VPSDemoController: UIViewController, ARSCNViewDelegate {
    @IBOutlet private weak var sceneView: ARSCNView!
    private var configuration: ARWorldTrackingConfiguration?
    private var vps: VPSService?

    override func viewDidLoad() {
        super.viewDidLoad()
        sceneView.delegate = self
        sceneView.scene = SCNScene()

        configuration = VPSBuilder.getDefaultConfiguration()

        VPSBuilder.initializeVPS(
            arSession: sceneView.session,
            apiKey: "your-api-key",
            locationIds: ["your-location-id"],
            url: "https://was-vps.web-ar.xyz/vps/api/v3",
            gpsUsage: false,
            delegate: self
        ) { service in
            self.vps = service
            self.vps?.start()
        }
    }

    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        if let configuration { sceneView.session.run(configuration) }
    }

    func renderer(_ renderer: SCNSceneRenderer, updateAtTime time: TimeInterval) {
        vps?.frameUpdated()
    }
}

extension VPSDemoController: VPSServiceDelegate {
    func positionVPS(pos: ResponseVPSPhoto) {
        print("Localized pose:", pos)
    }

    func error(err: NSError) {
        print("VPS error:", err)
    }

    func sending(requestData: UploadVPSPhoto?) {
        print("Sending localization request…")
    }
}

Pause the service in sessionWasInterrupted and restart it in sessionInterruptionEnded.

RealityKit Integration

For RealityKit you forward frames inside ARSessionDelegate:

func session(_ session: ARSession, didUpdate frame: ARFrame) {
    vps?.frameUpdated()
}

Lifecycle calls (start, stop, clearCustomLocPos) match the SceneKit flow.

SwiftUI Pattern

Wrap ARSCNView or ARView in UIViewRepresentable/UIViewControllerRepresentable. Keep VPSService in a shared view model and toggle start() / stop() from SwiftUI controls.

Advanced Controls

• Provide a known transform before the first localization with setCustomLocPosForFirstRequest.
• Override the default endpoint by passing a different url to initializeVPS.
• Enable gpsUsage if you want the SDK to include device coordinates in requests.

Troubleshooting

• VPSBuilder.getDefaultConfiguration() returning nil signals an unsupported device.
• If callbacks never fire, verify that frameUpdated() runs every frame and that your API key plus location IDs are valid.
• Explore the /examples folder for UIKit, RealityKit, and SwiftUI reference implementations.