Getting Started

For installation and initialization, see the SDK Quickstart.

Receiving live positions

The session’s onPosition callback delivers the user’s coordinates.
It fires independently of server uploads, up to 4 times per second.
Coordinates are in meters (m).

SwiftUI
UIKit

struct StoreMapView: View {
    @State private var me: Coordinates?

    var body: some View {
        MapCanvas(marker: me)
            .task {
                guard let session = try? OneS1ght.floorSession() else { return }
                // coord.x, coord.y: floor-plan local coordinates (meters, origin at bottom-left) · coord.z: height
                session.onPosition = { coord in me = coord }
            }
    }
}

final class StoreMapViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        guard let session = try? OneS1ght.floorSession() else { return }
        // coord.x, coord.y: floor-plan local coordinates (meters, origin at bottom-left) · coord.z: height
        session.onPosition = { [weak self] coord in
            self?.updateMyLocationMarker(x: coord.x, y: coord.y)
        }
    }
}

Displaying the floor plan

Show the user the floor plan they are being positioned on.
You need a building ID and a floor ID to render it. To draw the user’s position on top of it, map the onPosition coordinates onto the plan.

SwiftUI
UIKit

struct FloorPlanView: View {
    let building: Building
    let floorId: String
    @State private var plan: UIImage?

    var body: some View {
        Group {
            if let plan { Image(uiImage: plan).resizable().scaledToFit() }
            else { ProgressView() }
        }
        .task {
            guard let floor = try? await OneS1ght.floor(building.id, floorId) else { return }
            plan = floor.image.flatMap(UIImage.init(data:))
            setBounds(minX: floor.minX, minY: floor.minY,
                      maxX: floor.maxX, maxY: floor.maxY)
        }
    }
}

final class FloorPlanViewController: UIViewController {
    private let planView = UIImageView()

    override func viewDidLoad() {
        super.viewDidLoad()

        Task { @MainActor in
            let floor = try await OneS1ght.floor(building.id, floorId)
            planView.image = floor.image.flatMap(UIImage.init(data:))
            setBounds(minX: floor.minX, minY: floor.minY,
                      maxX: floor.maxX, maxY: floor.maxY)
        }
    }
}

hasPlan == false means no floor plan has been set up for that floor.
See Guide — Floor plan placement · clusters.

If you need the locator layout and the UWB session ID, look them up separately with locators(_:_:). When positioningReady is false, that floor has no locator or session data and positioning cannot start.

Zone events

Enter, exit and dwell arrive as separate callbacks. The decision is made on the device, so there is no server round trip.

SwiftUI
UIKit

@State private var banner: String?

session.onZoneEnter = { zone in banner = "enter: \(zone.name)" }
session.onZoneExit  = { zone in banner = nil }
session.onZoneDwell = { zone, seconds in
    banner = "dwell: \(zone.name) — \(Int(seconds))s"
}

session.onZoneEnter = { [weak self] zone in self?.showBanner("enter: \(zone.name)") }
session.onZoneExit  = { [weak self] _    in self?.hideBanner() }
session.onZoneDwell = { [weak self] zone, seconds in
    self?.showBanner("dwell: \(zone.name) — \(Int(seconds))s")
}

Callback	When it fires
`onZoneEnter`	When the user enters a zone.
`onZoneExit`	When the user leaves a zone.
`onZoneDwell`	While the user stays in a zone. (default: 5s)

Zones for each floor are configured in Space management.

If a floor has no zones at all, coordinates still accumulate but no enter or exit fires (E3004).

Refreshing zone data

After you change and save zones in the console, refresh them from your code.

let zones = await OneS1ght.refreshZones()

Creating and connecting a profile

To collect a customer’s movement, issue a profile for each account and keep the ID in your own storage.

// 1. Issue a profile on the first visit.
// Profile attributes are used later to build segments in console reports — there is no restriction on the key-value pairs.
let profileId = try await OneS1ght.createProfile([
    "gender":   "F",
    "ageBand":  "20s",
    "interest": "cosmetics",
])

// 2. On a later visit, authenticate with the profile ID you already issued.
OneS1ght.identify(profileId: savedProfileId)

// 3. Stop collecting for this user and clear the profile.
OneS1ght.identify(profileId: nil)

Method	Purpose
`createProfile(_:)`	Creates a new profile.
`getProfile(_:)`	Reads the current profile attributes.
`putProfile(_:_:)`	Replaces the profile with new attributes — the previous data is removed.
`deleteProfile(_:)`	Deletes the profile.
`identify(profileId:)`	Verifies that the profile is valid.

The issued profile ID must be stored by you. A lost profile ID cannot be recovered, so handle it with care.

Selecting a building and floor

To collect positioning data you must set a building and a floor. One building can have several floors. setFloorMap sets the locator data used for positioning and the map together with the zone data shown to the user.

// Look up buildings and floors.
let buildings = try await OneS1ght.buildings()
let floors    = try await OneS1ght.floors(buildings[0].id)

// Set the initial map with the floor and building ID.
try await OneS1ght.setFloorMap(floors[0], buildingID: buildings[0].id)

// Switch to another floor during a live session to swap the map.
try await OneS1ght.setFloorMap(floors[1], buildingID: buildings[0].id)

// Clear the map once collection is finished.
try await OneS1ght.setFloorMap(nil)

Building and floor data requires geoSdkKey at initialization — without it you cannot look them up.

Handling unsupported devices

Using the OneS1ght SDK requires the device to meet the minimum requirements. SDK Quickstart
Even when it is installed on an unsupported device, the app keeps working without any impact from the SDK.

isDeviceAvailable is the short form for checking whether the device can use the SDK, and it returns a Boolean (true/false).

Controlling data upload

The OneS1ght SDK uploads collected positioning data on its own schedule, but you can flush or drop the buffer immediately when you need to.

await OneS1ght.send()      // Upload the positioning data now.
OneS1ght.empty()           // Drop the collected positioning data without uploading.

Resetting the session

Discards the accumulated session and starts a new one.

await OneS1ght.reset()

Using API keys per environment

In the OneS1ght console you can issue keys as Development or Production.
The two environments are isolated and cannot reach into each other.
Set the API key per environment so that test traffic does not mix into production data.

#if DEBUG   // debug build
let sdkKey = "YOUR_DEVELOPMENT_API_KEY"
#else
let sdkKey = "YOUR_PRODUCTION_API_KEY"
#endif
try await OneS1ght.initialize(sdkKey: sdkKey, geoSdkKey: geoSdkKey)

Because of an iOS platform restriction, real positioning cannot be verified in the simulator. Build to a real device and test there.

Positioning Infrastructure (GeoSpace)

OneS1ght Console

Developer Guide (SDK)

Getting Started

Receiving live positions

Displaying the floor plan

Zone events

Refreshing zone data

Creating and connecting a profile

Selecting a building and floor

Handling unsupported devices

Controlling data upload

Resetting the session

Using API keys per environment

Troubleshooting

How to collect logs

SDK error codes

​Receiving live positions

​Displaying the floor plan

​Zone events

​Refreshing zone data

​Creating and connecting a profile

​Selecting a building and floor

​Handling unsupported devices

​Controlling data upload

​Resetting the session

​Using API keys per environment

​Troubleshooting

How to collect logs

SDK error codes

Receiving live positions

Displaying the floor plan

Zone events

Refreshing zone data

Creating and connecting a profile

Selecting a building and floor

Handling unsupported devices

Controlling data upload

Resetting the session

Using API keys per environment

Troubleshooting