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:
In your module-level Gradle file (usually
project/module/build.gradle.kts
orproject/module/build.gradle
), add the dependency for the WemapMapSDK library for Android:dependencies {
// Add the dependency for the WemapMapSDK library
implementation "com.getwemap.sdk:map:<version>"
// Add the dependency for the WemapPositioningSDK library
implementation "com.getwemap.sdk.positioning:fused-gms:<version>" // Google's Fused Location Source
implementation "com.getwemap.sdk.positioning:polestar:<version>" // Polestar Location Source
implementation "com.getwemap.sdk.positioning:wemap-vps-arcore:<version>" // Wemap VPS ARCore Location Source
}Ensure that your project's minSdkVersion is set to API 21 or higher:
android {
...
defaultConfig {
minSdkVersion 21
}
}Since you've modified your Gradle files, Android Studio will prompt you to sync the Gradle files. Proceed with syncing.
Location Sources
Wemap provides various location sources to track the user's location on the map. By default, WemapMapSDK
uses Android GPS and Network Providers 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
.WemapMapSDK.instance
.mapData(19158, "GUHTU6TYAWWQHUSR5Z5JZNMXX")
.observeOn(AndroidSchedulers.mainThread())
.subscribe({
setupLocationSource(it)
}, {
println("Failed to get map data with error - ${it.message}")
})
.disposedBy(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 renderMode
and cameraMode
of locationManager
, as shown below:
mapView.locationManager.apply {
cameraMode = CameraMode.TRACKING_COMPASS
renderMode = RenderMode.COMPASS
}
Wemap VPS ARCore location source
Setting Up the VPS ARCore Location Source
Once you have the MapData
, create a WemapVPSARCoreLocationSource
instance, add vpsListener
, and assign it to the map:
fun setupLocationSource(mapData: MapData) {
vpsLocationSource = WemapVPSARCoreLocationSource(requireContext(), mapData)
vpsLocationSource.bind(requireContext(), surfaceView)
vpsLocationSource.vpsListeners.add(vpsListener)
mapView.locationManager.apply {
source = vpsLocationSource
isEnabled = true
}
}
Handling Location Source State Changes
You must handle state changes in WemapVPSARCoreLocationSourceListener
, as users may need to scan their environment.
private val vpsListener by lazy {
object : WemapVPSARCoreLocationSourceListener {
override fun onStateChanged(state: WemapVPSARCoreLocationSource.State) {
// Handle state changes
}
override fun onScanStatusChanged(status: WemapVPSARCoreLocationSource.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:
fun startScan() {
vpsLocationSource.startScan()
}
Once the system successfully recognizes the user’s location, it will report the ACCURATE_POSITIONING
state to WemapVPSARCoreLocationSourceListener
. Shortly afterward, the VPS system will start updating the user’s location indicator on the map.
The VPS system will also report:
NOT_POSITIONING
– 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()
.DEGRADED_POSITIONING
– indicates that user location tracking is limited. A scan is recommended, but not mandatory, to restore theACCURATE_POSITIONING
state. We suggest a subtle UI indication when this state occurs, such as a location icon warning or a small toast message prompting the user to rescan.
Google's Fused location source
Once you have the MapData
, create a GmsFusedLocationSource
instance and assign it to the map.
Setting Up the Fused Location Source
fun setupLocationSource(mapData: MapData) {
mapView.locationManager.apply {
source = GmsFusedLocationSource(requireContext(), mapData)
isEnabled = true
}
}
Polestar location source
Once you have the MapData
, create a PolestarLocationSource
instance and assign it to the map.
Setting Up the Polestar Location Source
fun setupLocationSource(mapData: MapData) {
mapView.locationManager.apply {
source = PolestarLocationSource(requireContext(), "emulator", mapData) // change 'emulator' to your polestar API key here
isEnabled = true
}
}
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.