SDK для iOS

Обзор

Нативный SDK WebAR³ VPS для iOS локализует пользователей внутри карт VPS с использованием трекинга ARKit. XCFramework работает в UIKit-, RealityKit- и SwiftUI-приложениях. Следуйте знакомому сценарию: проверьте требования, подключите пакет, добавьте разрешения и инициализируйте сервис.

Требования

• iOS 12.0 или новее
• Xcode 12+ со Swift 5
• Устройство с поддержкой ARKit (симулятор не подходит)

Варианты установки

Через Swift Package Manager

1. В Xcode перейдите в File → Add Packages….
2. Укажите https://github.com/WebAR-Studio/was-vps-ios.git.
3. Выберите нужную ветку или тег и добавьте пакет в цель проекта.

Ручная интеграция

1. Клонируйте репозиторий:

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

2. Перетащите WASVPS.xcframework в проект.
3. В разделе General → Frameworks, Libraries, and Embedded Content убедитесь, что фреймворк подключён.

Разрешения

Добавьте описания использования камеры и геолокации в Info.plist, чтобы система показала запросы прав.

<key>NSCameraUsageDescription</key>
<string>Для отображения дополненной реальности требуется доступ к камере.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Доступ к геопозиции нужен для точного размещения AR-контента.</string>
<key>NSLocationTemporaryUsageDescriptionDictionary</key>
<dict>
    <key>VPSLocalization</key>
    <string>Точная локализация обеспечивает корректную работу AR-сцен.</string>
</dict>

Инициализация VPS

Используйте VPSBuilder.initializeVPS, чтобы создать VPSService: передайте ARSession, API-ключ и список Location ID.

Нужен API ключ? Получите его на space.web-ar.studio или напишите на 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…")
    }
}

Останавливайте сервис в sessionWasInterrupted и запускайте снова в sessionInterruptionEnded.

RealityKit

В RealityKit передавайте кадры в делегате ARSessionDelegate:

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

Остальные вызовы (start, stop, clearCustomLocPos) совпадают со сценарием SceneKit.

SwiftUI

Оборачивайте ARSCNView или ARView в UIViewRepresentable/UIViewControllerRepresentable. Храните VPSService во вью-модели и переключайте start()/stop() из SwiftUI-кнопок.

Дополнительные настройки

• setCustomLocPosForFirstRequest задаёт стартовую позу перед первой локализацией.
• Параметр url в initializeVPS позволяет поменять конечную точку API (по умолчанию https://was-vps.web-ar.xyz/vps/api/v3).
• Флаг gpsUsage добавляет координаты устройства в запросы.

Решение проблем

• Если VPSBuilder.getDefaultConfiguration() возвращает nil, устройство не поддерживает ARKit.
• Если колбэки не вызываются, проверьте вызов frameUpdated() каждый кадр и корректность API-ключа с Location ID.
• В папке /examples есть полноценные примеры для UIKit, RealityKit и SwiftUI.