Navigation Settings

Available in SDK 0.5.2 on iOS, Android and WebXR. scanOnNewTrip was added in 0.5.4. SDK 0.6.9 adds the Q20 run-completion controls and continueGuidanceDuringRunExitCorrection on all three platforms.

The SDK uses one field-tested navigation and localization-recovery policy across standard routes and custom guidance presentations. Your app supplies route data, authenticated transport and UI. It does not need its own drift timers or another recovery coordinator.

VPSNavigationSettings exposes thresholds and timings for integrations that need different behavior. Omit overrides to keep the field-tested defaults. The current Treedis applications use those defaults. Settings names and default values match across the three platforms.

Configure a session

Only override values your application intentionally needs to change. Other values retain their defaults. These examples demonstrate an override; they are not settings required by Treedis applications.

iOS

import TreedisVPS

let policy = try VPSNavigationSettings(
    offRouteMeters: 4,
    correctionTimeoutSeconds: 9
)
let session = VPSSession(configuration: VPSConfiguration(
    serverURL: serverURL,
    apiKey: apiKey,
    navigationSettings: policy
))

VPSNavigationSettings() returns the defaults. The typed initializer with overrides throws for invalid input. Partial JSON decoding also fills omitted values from defaults and rejects unknown or invalid settings.

For barometer-assisted completion, add NSMotionUsageDescription to the app and App Clip Info.plist. The SDK can request the first motion permission when starting the sensor. Missing permission, denied access or unavailable hardware leaves camera, route-progress and time fallbacks available.

Android

import com.treedis.vps.*

val session = VPSSession(context, VPSConfiguration(
    serverURL = serverURL,
    apiKey = apiKey,
    navigationSettings = VPSNavigationSettings(
        offRouteMeters = 4.0,
        correctionTimeoutSeconds = 9.0,
    ),
))

VPSNavigationSettings() returns the defaults. Invalid constructor values throw IllegalArgumentException. The SDK uses an available pressure sensor for relative height; a missing sensor leaves camera, route-progress and time fallbacks available.

WebXR

import { VPSSession } from '@treedis/vps-webxr';

const session = new VPSSession({
  serverURL,
  apiKey,
  navigationSettings: {
    offRouteMeters: 4,
    correctionTimeoutSeconds: 9,
  },
});

WebXR also exports defaultNavigationSettings, resolveNavigationSettings and the readonly VPSNavigationSettings type. The resolver validates, copies and freezes an override object. Changing the caller's original object cannot mutate a running coordinator. Browser hardware determines which camera/altitude inputs are available; the time fallback remains part of the same policy.

Lifetime and validation

Configure policy before starting navigation. Coordinators snapshot settings; they are not mutable live timers. Create a new coordinator/session for a policy change. Native recovery also supports configuration while inactive.

• Numbers must be finite and nonnegative.
• Correction/request/run-exit timeouts, scan retry and ride speeds must be positive.
• Shares must be between zero and one.
• routeRetryLimit must be an integer from zero through ten. Its default is zero, so automatic transport retry is disabled.
• afterTurnWindowMeters must include afterTurnMeters.
• climbingWindowToleranceSeconds cannot exceed climbingWindowSeconds.
• Turn/bend angles cannot exceed 180 degrees; the bend threshold cannot exceed the turn threshold.
• scanOnNewTrip and continueGuidanceDuringRunExitCorrection must be true or false; all other settings are numbers.
• cameraHeightMinimumMeters must not exceed cameraHeightMeters, which must not exceed cameraHeightMaximumMeters.
• rideMaximumRateMetersPerSecond and runProgressSpeedMetersPerSecond must be positive.

Units and defaults

Positions and distances use Y-up metres. Durations use seconds, speeds use metres per second, angles use degrees and progress shares use 0–1. routeRetryLimit is a count and the two policy flags are true/false. The SDK archives include the same defaults in NavigationSettings.defaults.json.

Run completion in 0.6.9

The shared Q20 policy handles stairs and escalators: subtract measured phone height before comparing the camera with the exit floor, ignore abrupt pressure jumps, and suppress residual barometer movement from starting the next flight during landing grace. Without a reliable barometer, sustained route progress beyond the exit can finish the run. A time fallback remains available. New-trip resets clear measured height; reroutes retain it. Settings above use Nevo’s field-tested defaults.

Starting a trip

Every trip start follows scanOnNewTrip:

Call the custom start() at the beginning of each trip instead of session.rescan(). Before 0.5.4, native starts always scanned and WebXR navigation.start() kept the previous fix. With the default, all three scan. To keep a fix between trips, for example when a kiosk starts trips back to back in the same spot, configure the session with scanOnNewTrip: false:

let policy = try VPSNavigationSettings(scanOnNewTrip: false)

val policy = VPSNavigationSettings(scanOnNewTrip = false)

const session = new VPSSession({ serverURL, apiKey, navigationSettings: { scanOnNewTrip: false } });

Navigation policy versus localization settings

Navigation settings control when the SDK corrects, retains, scans or requests another route. They do not replace localization settings from the current tour.

Continue passing supported tour arSettings dynamically into localization: confidence threshold, scan/background scheduling, position-hint radius, search settings and explicit floor bands. Do not hardcode tour confidence or hint radius into navigation policy. A first accepted fix and a later normally tracked camera frame are still required before guidance resumes; increasing a navigation timeout does not bypass that gate.

Upgrade from 0.5.1

Remove assignments to fieldManaged, automaticallyBoundsProgress and automaticallyCorrectsDeviation. SDK 0.5.2 has one policy rather than field/generic modes. Use the settings type for deliberate future overrides.

Custom presentations must share the session's coordinator and request epochs. Install logical route metadata once; use renderer-only path updates for redraws. Consume SDK actions to update UI and perform transport, without starting a second recovery timer or executing the same localization action twice.

For WebXR, legacy navigation style fields such as arrivalDistance, floorChangeDistance and deviationDistance do not control policy in 0.5.2. Use arrivalMeters, floorEntryMeters and offRouteMeters in navigation settings. Rendering style remains separate.

Standard navigation ends recovery automatically at arrival. Custom WebXR presentations call VPSNavigationRecovery.complete() when arrival is confirmed, then start() for the next trip. A route drawing retained by the arrival screen must not restart scan/retry policy.

UI, audio recordings, accessibility and authenticated route services stay app-owned. Field tests and deterministic replay validate the default policy; simulator/browser tests alone do not establish physical walking or AR alignment.