Map+PositioningSDK - Getting started
Installation
Before you start developing your application with WemapSDKs, you need to configure your credentials and add the SDK as a dependency.
The code examples below demonstrate how to configure the WemapPositioningSDK
to work with the WemapMapSDK
, but it can also be used independently. Instructions are available here.
Adding the Dependency
To add WemapSDKs to your app:
Add dependencies in the
Podfile
Add the required WemapSDK pods to your app:
use_frameworks!
target 'TargetNameOfYourApp' do
# Add the dependency for the WemapMapSDK library
pod 'WemapMapSDK', '<version>'
# Add the dependency for the WemapPositioningSDK library
pod 'WemapPositioningSDKPolestar', '<version>' # Polestar Location Source
pod 'WemapPositioningSDK/VPSARKit', '<version>' # Wemap VPS ARKit Location Source
endEnsure minimum iOS version
Your project must target iOS 12.0 or later:
platform :ios, '12.0'
Install dependencies and open the project
Run the following command to install the pods:
AWS_ACCESS_KEY_ID=*** \
AWS_SECRET_ACCESS_KEY=*** \
AWS_REGION=*** \
bundle exec pod install --repo-updateThen, open your project in Xcode:
open your-project.xcworkspace
Location Sources
Wemap provides various location sources to track the user's location on the map. By default, WemapMapSDK
uses Apple’s LocationProvider
to obtain raw location updates.
To use any location source, you must have a mapID
and token
. For more details, please contact the Wemap team.
To set a specific location source, you need to:
Add the relevant
WemapPositioningSDK
library to your project dependencies.Fetch
MapData
using yourmapID
andtoken
.WemapMap.shared
.getMapData(mapID: 19158, token: "GUHTU6TYAWWQHUSR5Z5JZNMXX")
.subscribe(onSuccess: { mapData in
setupLocationSource(mapData: mapData)
}, onFailure: {
debugPrint("Failed to get map data with error - \($0)")
})
.disposed(by: disposeBag)Create a
LocationSource
usingMapData
.Assign the location source to the map. Examples are given below.
If you want the camera to follow the user’s direction, you can do so by changing the userTrackingMode
of the map, as shown below:
map.userTrackingMode = .follow
Wemap VPS ARKit location source
Setting Up the VPS ARKit Location Source
Once you have the MapData
, create a VPSARKitLocationSource
instance, set vpsDelegate
, and assign it to the map:
func setupLocationSource(mapData: MapData) {
vpsLocationSource = VPSARKitLocationSource(mapData: mapData)
vpsLocationSource.vpsDelegate = self
map.userLocationManager.locationSource = source
}
Handling Location Source State Changes
You must handle state changes in VPSARKitLocationSourceDelegate
, as users may need to scan their environment.
extension ViewController: VPSARKitLocationSourceDelegate {
func locationSource(_ locationSource: VPSARKitLocationSource, didChangeState state: VPSARKitLocationSource.State) {
// Handle state changes
}
func locationSource(_ locationSource: VPSARKitLocationSource, didChangeScanStatus status: VPSARKitLocationSource.ScanStatus) {
// Handle scan status changes
}
}
Scanning the Environment
To start tracking the user’s location, you need to allow the user to scan their environment:
func startScan() {
vpsLocationSource.startScan()
}
Once the system successfully recognizes the user’s location, it will report the accuratePositioning
state to VPSARKitLocationSourceDelegate
. Shortly afterward, the VPS system will start updating the user’s location indicator on the map.
The VPS system will also report:
notPositioning
– indicates that the system hasn't yet recognized the environment and a VPS scan is required. At this point, you should present the camera view to the user to allow them to scan usingvpsLocationSource.startScan()
.degradedPositioning
– indicates that user location tracking is limited for various reasons (see reasons in API reference documentation). A scan is recommended, but not mandatory, to restore theaccuratePositioning
state. We recommend a small impact in the UI when this state occurs (location icon warning or a small toast message to suggest a rescan).
Important note
Starting from iOS 18, there is a bug where ARSession
is automatically stopped by ARView
when the view is dismissed or hidden.
As a result, the positioning process stops after a few seconds.
If you are using ARView
, we recommend a workaround in our sample application
Known issue
When using VPSARKitLocationSource
with map.userTrackingMode = .followWithHeading
, there may be a delay in updating the user location indicator on the map. We’re working on a fix, but in the meantime, we recommend using map.userTrackingMode = .follow
to avoid any delays.
Polestar Location Source
Once you have the MapData
, create a PolestarLocationSource
instance and assign it to the map.
Setting Up the Polestar Location Source
func setupLocationSource(mapData: MapData) {
let source = PolestarLocationSource(apiKey: "emulator", mapData: mapData) // change 'emulator' to your Polestar API key
map.userLocationManager.locationSource = source
}
The full example is available in our GitHub repository.
Examples
For additional examples and sample implementations of WemapSDKs, visit the official GitHub repository.
Clone the repository and follow the README instructions to run the sample application.