Migrate from VPS to VPS2

What changed in NSDK 4.x

This guide is for developers migrating from Unity ARDK 3.x to NSDK 4.x.

In NSDK 4.x, VPS and WPS are unified into a single system called VPS2. Instead of using separate APIs for localization and geopositioning, all functionality is now handled through ARVps2Manager.

This change:

• Replaces separate VPS and WPS APIs with a single unified API.
• Consolidates localization, geoposition, and anchor workflows.
• Simplifies configuration and runtime behavior.

For a full overview of VPS2 capabilities, see the VPS2 feature page.

Migration steps

1. Set up Sites in Scaniverse - Move location management from GSB to Scaniverse before you update Unity-side integration.
2. Update core APIs to VPS2 - Replace legacy VPS and WPS managers with the unified VPS2 entry point.
3. Update device mapping - Update how you load, convert, and save device maps if your app uses Device Mapping.
4. Update geoposition and coordinate conversion - Replace legacy AR to geoposition helper APIs with transformer-based conversions.
5. Replace VPS Coverage API with Sites API - Stop relying on GSB-only discovery flows when you need Scaniverse-created Sites.
6. Update configuration and events - Update event handling and remove configuration that VPS2 now manages internally.

Set up Sites in Scaniverse

Complete this step first if your Unity project depends on locations created, discovered, or activated through the Geospatial Browser (GSB). In NSDK 4.x, Scaniverse is the system of record for creating and managing Sites and their assets.

Use Scaniverse to manage VPS maps and Sites, then update your Unity workflow to use those Sites.

For instructions on creating a Scaniverse account, creating Sites, and managing mapped locations, see First Localization with NSDK.

If you have saved payloads from VPS locations discovered or activated through GSB, those payloads remain valid and can still be used for localization.

Update core APIs to VPS2

Replace your ARDK 3.x VPS and WPS components with the unified VPS2 API before migrating downstream localization and anchor logic. In NSDK 4.x, ARVps2Manager is the primary Unity entry point for VPS2 functionality.

In NSDK 4.x, localization, geopositioning, and anchor management are handled through a single VPS2 session.

Use the following table to replace each legacy manager or workflow in your project with its NSDK 4.x equivalent.

ARDK 3.x	NSDK 4.x	Details
ARPersistentAnchorManager, ARLocationManager	ARVps2Manager	Use VPS2 to manage Site-based localization and anchor tracking
ARWorldPositioningManager	ARVps2Manager	VPS and WPS functionality are unified under a single manager
ARLocation + ARLocationManager + GSB workflow	ARLocation + ARLocationManager + Scaniverse	Download mesh assets from Scaniverse instead of GSB. The rest of the Unity Editor workflow remains unchanged

Update device mapping

Complete this step if your app uses Device Mapping. The data can still be migrated, but you need to update how you load maps, create anchors, and save map data in NSDK 4.x.

Use the following table to replace each Device Mapping API or data expectation in your migration.

ARDK 3.x	NSDK 4.x	Details
ARPersistentAnchorManager	ARVps2Manager	Use VPS2 to track anchors with Device Mapping
ARDeviceMappingManager	ARDeviceMappingManager	No change
ARDeviceMap	Serialized data as byte[]	Pass serialized Device Map bytes directly to DeviceMapAccessController.AddMap()
Multiple anchors in ARDeviceMap	One "root" anchor	Call DeviceMapAccessController.CreateRootAnchor() after setting the Device Map to generate the anchor payload

NSDK 4.x uses a different serialization format than ARDK 3.x, but serialized Device Mapping data from ARDK 3.x can still be migrated. Pass the byte array returned from ARDeviceMap.Serialize() to DeviceMapAccessController.AddMap(), and NSDK 4.x converts it internally the first time it is loaded.

If you save maps at the end of a session, update that code too. ARDeviceMappingManager.MapFinalized now delivers delta data instead of a full map, so call ARDeviceMappingManager.TryGetMapData() when you need the complete Device Map byte array.

Update geoposition and coordinate conversion

Update these APIs anywhere your app converts between AR poses and geographic coordinates. This is required because VPS2 uses a transformer snapshot instead of the older helper-based conversion flow.

Use the following table to replace each legacy conversion helper in your project.

ARDK 3.x	NSDK 4.x	Details
ARWorldPositioningObjectHelper	ARVps2Manager.TryGetPose()	Converts geographic coordinates to AR coordinates and updates the GameObject transform
ARWorldPositioningCameraHelper	ARVps2Manager.TryGetDeviceGeoLocation()	Use with the current camera pose to retrieve the device’s geographic location

When you migrate this code, make both of the following changes:

1. Retrieving the latest transformer
2. Using that transformer for conversion

See Getting VPS2 Geoposition for details.

Replace VPS Coverage API with Sites API

Update this part of your app if you currently query nearby VPS locations or anchor payloads through the VPS Coverage API. This matters because Scaniverse-created Sites are not discoverable through the old GSB-based coverage flow.

Use Sites API when you need to query Scaniverse-managed Sites and retrieve the VPS anchor payload data that your app should localize against.

The VPS Coverage API remains available for querying VPS locations and anchors near the user at runtime. However, it only returns locations that were created or activated through GSB. VPS locations created on Scaniverse are not supported. It will be replaced by a unified Sites API in a future release.

With Scaniverse, Sites replace the VPS location and test-scan workflows that previously depended on GSB. If your migration includes newly created Sites in Scaniverse, move your discovery logic to Sites-based queries instead of relying on coverage results.

Update configuration and events

Update this code after the core API migration so your runtime behavior still matches user expectations. In VPS2, anchor updates are consolidated and several old configuration properties are no longer set manually.

Update anchor events

Use the following table to replace legacy anchor and location tracking event handlers.

ARDK 3.x	NSDK 4.x	Details
arPersistentAnchorStateChanged event in ARPersistentAnchorManager	ARVps2Manager.trackablesChanged event	trackablesChanged delivers anchor add, update, and remove events together
locationTrackingStateChanged event in ARLocationManager	ARVps2Manager.trackablesChanged event	Check changed anchors in trackablesChanged and inspect whether the tracking state is Tracked

Anchor add, update, and removal remain conceptually consistent with legacy VPS, but tracking quality reporting is different. Anchors can surface coarse poses even when the device is not yet localized to a VPS map.

Handle the tracking state accordingly:

• Treat Limited as a coarse pose that is not yet fully tracked against the VPS map.
• Treat Tracked as the state where the anchor is tracking against the VPS map.

Update configuration properties

Search your project for VPS configuration code and update the remaining properties first, then remove settings that VPS2 now manages internally. This prevents you from carrying forward configuration that no longer has any effect.

Use the following table to replace the remaining configurable properties.

ARDK 3.x	NSDK 4.x	Details
Initial Service Request Interval Seconds	Initial Vps Requests Per Second	Unit changed from interval to requests per second
Continuous Service Request Interval Seconds	Continuous Vps Requests Per Second	Unit changed from interval to requests per second

Then remove the following properties from your project because VPS2 always enables them or manages them internally:

• Continuous Localization Enabled (Continuous localization is always enabled in VPS2)
• Temporal Fusion Enabled (Temporal fusion is always enabled in VPS2)
• Interpolation Enabled (Interpolation is always enabled in VPS2)
• Diagnostics Enabled
• Gps Correction For Continuous Localization
• Vps Usage Mode
• Jpeg Compression Quality

Configuration changes are applied immediately at runtime and no longer require restarting subsystems.