Troubleshooting

Native iOS

Framework cannot load, models are missing, or the module cannot be imported

Use the complete SDK archive for your target platform. Embed and sign TreedisVPS.xcframework in every executable target that uses it, including the App Clip. Keep its bundled CoreML model directories intact. Use Xcode 26.6 or a compatible newer toolchain for SDK 0.3.0. Do not combine source-built and compiled copies of the same module; clean old build products after switching installation methods. For GLB/glTF, embed both optional frameworks from the same archive too. Verify the archive checksum before installation.

No readiness or events

Import TreedisVPS, retain the VPSController(session:) controller and its delegate, and call start(in:) with a retained ARView. Create that view with automaticallyConfigureSession: false. Typed and wire commands queue before attachment; loading completes asynchronously. This integration does not use UnityFramework or a Unity send closure.

Tour or navigation does not load

Provide loadTour and session.navigation.routeProvider in the host. Match the platform environment, tour ID, Matterport model, provider, and VPS URL. Read onError, session.problem, and navigation events. A missing host adapter is an explicit error. Navigation needs a localized camera and a usable route; a tour slug alone is not a published VPS map.

Offline localization fails

Enable offline mode explicitly, finish downloading that space, and start with .onDevice. Downloads are scoped by server and tour. notDownloaded means there is no valid pack for that target; the SDK does not switch engines or use HTTP to fill missing offline map files. The host must also cache tags/settings/routes and media. Map sets use server localization.

Content shifts or a hint blocks localization

Use public Y-up metre tour coordinates. Controller, session and web hints use that same frame. Convert external marker formats at the host boundary. A floor band must use absolute tour Y. Clear an incorrect hint. Check pose confidence, tracking, and the mesh overlay on a physical device; the simulator has no live camera.

App Clip builds but a public QR does not launch it

Check that the parent embeds the Clip, identifiers and entitlements agree, and the website's AASA plus App Store Connect experience authorize the invocation domain/path. Simulator invocation checks URL handling, not Apple's public association. Test the camera, map, and walking flow on a real device before release.

See the Swift guide for complete setup and contracts.

Web

TreedisVPS.send(type, data) is installed by VPSWebBridge. Define named global handlers such as onLocalizationStatusChanged, onNavigationDistance, and onNavigationComplete; they are not wrapped in onMessage. onMessage receives the generic {type,data} object directly.

For a native iOS WKWebView, configure the bridge before loading and allow the exact HTTPS origin. Subframes and other origins cannot issue commands. The host implements page presentation, account state, and permissions.

Android native hosts

Import com.treedis.vps.*, retain VPSSession and VPSController(session), request camera permission, attach the AR view and call sdk.start(view). See the Kotlin guide. No Unity library or bridge is required. Commands queue until readiness; provide loadTour, route and host-service adapters before use. onReady does not indicate a localized camera.

If Gradle cannot resolve com.treedis:vps-android, add the extracted SDK archive's repository directory to your repositories and match the supplied version. Keep the AAR, POM and Gradle module metadata together. The Treedis coordinate is not on Maven Central; its third-party dependencies resolve from Google/Maven Central. A flatDir AAR dependency does not supply that metadata. Use JDK 17. For live AR use an ARCore-supported device with Google Play Services for AR. Emulator UI/photo tests do not provide a live AR camera. The hosted web bridge requires an up-to-date Android System WebView.