SDK iOS

Vue d’ensemble

Le SDK iOS natif de AR Clip VPS localise les utilisateurs dans vos cartes VPS grâce au suivi ARKit. Le XCFramework est compatible avec UIKit, RealityKit et SwiftUI. Suivez le déroulé Immersal : prérequis, installation, autorisations puis initialisation du service.

Prérequis

• iOS 12.0 ou version ultérieure
• Xcode 12+ avec Swift 5
• Appareil compatible ARKit (le simulateur n’est pas pris en charge)

Options d’installation

Via Swift Package Manager

1. Dans Xcode, ouvrez File → Add Packages….
2. Entrez https://github.com/WebAR-Studio/was-vps-ios.git.
3. Sélectionnez la branche ou le tag souhaité puis ajoutez le package à votre cible.

Intégration manuelle

1. Clonez le dépôt :

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

2. Glissez WASVPS.xcframework dans votre projet.
3. Dans General → Frameworks, Libraries, and Embedded Content, vérifiez que le framework est bien intégré.

Configurer les autorisations

Ajoutez les textes d’usage caméra et localisation dans Info.plist pour déclencher les invites système.

<key>NSCameraUsageDescription</key>
<string>L’app nécessite la caméra pour afficher du contenu en réalité augmentée.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>L’app utilise votre position pour placer précisément le contenu AR.</string>
<key>NSLocationTemporaryUsageDescriptionDictionary</key>
<dict>
    <key>VPSLocalization</key>
    <string>Active une localisation précise pour des expériences AR fiables.</string>
</dict>

Initialiser le VPS

VPSBuilder.initializeVPS crée une instance de VPSService. Passez l’ARSession, votre API key et les Location ID.

Besoin d’une API key ? Vous pouvez l’obtenir sur arclip.design ou en écrivant à support@arclip.design / 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…")
    }
}

Arrêtez le service dans sessionWasInterrupted et relancez-le dans sessionInterruptionEnded.

RealityKit

En RealityKit, transférez chaque frame via ARSessionDelegate :

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

Les méthodes de cycle de vie (start, stop, clearCustomLocPos) restent identiques à SceneKit.

SwiftUI

Encapsulez ARSCNView ou ARView dans un UIViewRepresentable/UIViewControllerRepresentable. Stockez VPSService dans un ViewModel et déclenchez start()/stop() depuis les contrôles SwiftUI.

Contrôles avancés

• setCustomLocPosForFirstRequest définit une pose connue avant la première requête.
• Le paramètre url de initializeVPS permet de cibler un autre endpoint (par défaut https://api.arclip.app/vps/api/v3).
• Activez gpsUsage pour inclure les coordonnées de l’appareil dans les requêtes.

Dépannage

• VPSBuilder.getDefaultConfiguration() renvoie nil ? L’appareil ne supporte pas ARKit.
• Pas de callbacks ? Vérifiez que frameUpdated() est appelé à chaque frame et que l’API key et les Location ID sont valides.
• Jetez un œil au dossier /examples pour des implémentations complètes UIKit, RealityKit et SwiftUI.