iOS SDK

Add AR Clip VPS to a native iOS app. The SDK uses ARKit tracking to find the user's position on your VPS maps. It is an XCFramework that works in UIKit, RealityKit and SwiftUI apps.

Before you start

• iOS 15.0 or newer
• Xcode 14 or newer (Swift 5.7 or newer)
• A device that can run ARKit. The simulator is not supported.

Install

Choose one of two ways.

Swift Package Manager

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

Manual

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.

Add permissions

Add camera and location usage descriptions to Info.plist, so iOS can ask the user for access.

<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>

Start VPS

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

Need an API key?

Get one at arclip.design or email support@arclip.design.

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://api.arclip.app/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 start it again in sessionInterruptionEnded.

RealityKit

With RealityKit, forward frames in ARSessionDelegate:

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

The lifecycle calls (start, stop, clearCustomLocPos) are the same as with SceneKit.

SwiftUI

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

More options

• Give a known transform before the first localization with setCustomLocPosForFirstRequest.
• Use a different endpoint by passing another url to initializeVPS.
• Turn on gpsUsage to include the device's coordinates in requests.

Troubleshooting

• If VPSBuilder.getDefaultConfiguration() returns nil, the device is not supported.
• If callbacks never fire, check that frameUpdated() runs every frame, and that your API key and location IDs are valid.
• See the /examples folder for UIKit, RealityKit and SwiftUI examples.