PositioningSDK - Getting started

Installation

Before starting to develop your application with the WemapSDKs, you'll need to configure your credentials and add the SDK as a dependency.

info

The code examples below show how to configure the WemapPositioningSDK to work with custom map, but it can be used with WemapMapSDK. Instructions are here

Add the dependency

Add the WemapSDKs to your app

1. In your module-level Gradle file (usually project/module/build.gradle.kts or project/module/build.gradle), add the dependency for the WemapMapSDK library for Android:

   dependencies {
       // Add the dependency for the WemapPositioningSDK library
       implementation "com.getwemap.sdk.positioning:wemap-vps-arcore:<version>" // Wemap VPS ARCore Location Source
   }

2. Ensure that your project's minSdkVersion is set to API 21 or higher:

   android {
       ...
       defaultConfig {
           minSdkVersion 21
       }
   }

3. Since you've modified your Gradle files, Android Studio will prompt you to sync the Gradle files. Proceed with syncing.

Location Sources

Wemap provides a variety of location sources to manage the user’s location on the map.

To set a specific location source, you need to:

• Add the relevant WemapPositioningSDK library to your project dependencies.

• Assign the location source to the map.

Wemap VPS ARCore location source

To use the VPS Location Source, you must have a mapID and token or a VPS serviceURL. For more details, please contact Wemap team.

Fetching the VPS Service URL

val request = ServiceFactory
    .getMapService()
    .mapById(19158, "GUHTU6TYAWWQHUSR5Z5JZNMXX")
    .observeOn(AndroidSchedulers.mainThread())
    .subscribe({
        // mapData contains the VPS service URL
    }, {
        println("Failed to receive map data with error - ${it.message}")
    })

Setting Up the VPS ARCore Location Source

Once you have the serviceURL, create a WemapVPSARCoreLocationSource instance:

fun setupLocationSource() {
    val vpsLocationSource = WemapVPSARCoreLocationSource(requireContext(), mapData.extras?.vpsEndpoint ?: "https://your-wemap-vps-endpoint")
    vpsLocationSource.bind(requireContext(), surfaceView)
    vpsLocationSource.vpsListeners.add(vpsListener)
    vpsLocationSource.listener = locationListener

    vpsLocationSource.start()
}

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
        }

        override fun onError(error: WemapVPSARCoreLocationSourceError) {
            // Handle location source errors
        }
    }
}

Retrieving User's Coordinate and Attitude

To get the user’s coordinate and attitude, implement LocationSourceListener:

private val locationListener by lazy {
    object : LocationSourceListener {

        override fun onCoordinateChanged(coordinate: Coordinate) {
            // Pass the updated coordinate to your map implementation
        }

        override fun onAttitudeChanged(attitude: Attitude) {
            // Pass the updated attitude to your map implementation
        }

        override fun onError(error: Error) {
            // Handle errors
        }
    }
}

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 after, you will start receiving updated Coordinate and Attitude values in LocationSourceListener.

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.

🔗 Positioning sample