Custom routes

Situm allows to create customized routes. Custom routes utilize the paths outlined in Situm Dashboard but factor in modifiers known as tags (as explained in Section “Customize the tags to include/exclude by your app”). These tags influence which segments of the route are included or excluded, allowing for tailored navigation beyond simply calculating the shortest or accessible path.

What can you customize? #

By setting up certain segments of your route with tags (see explanation above), you’ll be able to include or exclude specific segments when computing a route. Additionally, you’ll be able to exclude tags on a certain time range.

Including tags #

If you choose to exclude certain tags, the route will be computed taking into account the segments that have no tag at all + the segments that have the tags that you’ve included. For instance, if you tag some segments as “public” and others as “private”, and you include the tag “public” when computing a route, your route will consider segments with no tag, or with the tag “public”.

Excluding tags #

If you choose to exclude certain tags, the route will be computed taking into account all the segments except for those that contain the tags that you’ve specifically excluded. For instance, if you tag some segments as “public” and others as “private”, and you exclude the tag “private” when computing a route, your route will consider all the segments, except the “private” ones.

Excluding tags by time range #

An special case of the “excluding tags” use case is to exclude certain paths from a route based on a time range: if you tag certain segments with the following format “hh:mm-hh:mm”, you’ll be able to exclude them within that time range.

For example, if you add a tag “15:00-16:30” to a segment, and you exclude this tag when computing a route, the route will not consider this segment within the 15:00-16:30 time range (in local user time). This is useful, for instance, if certain paths should be closed by night.

To exclude tags do this:

val excludedTags = mutableListOf<String>()
excludedTags.add("18:00-19:00")
val directionsRequest = DirectionsRequest.Builder()
                .from(origin, Angle.fromDegrees(0.0))
                .to(destination)
                .excludedTags(excludedTags)).build()

let excludedTags = ["18:00-19:00"]
let directionsRequest = SITDirectionsRequest(origin: origin, withDestination: destination)
directionsRequest.excludedTags = excludedTags

Example of how including / excluding tags works #

Let’s say you’ve configured some of your paths with a tag called “private“, and some others with a tag called “public” as in the following image:

Then, how the routing algorithm will work will be different depending on which tags you include / exclude:

Tags included / excluded	Result: the route will be computed based on…
Including only the “public” tag	Yelow paths + Dark paths
Including “public” & “private” tags	All paths
Including only the “private” tag	Green paths + dark paths
Excluding only the “public” tag	Green paths + Dark paths
Excluding “public” & “private” tags	Only dark paths
Excluding only the “private” tag:	Yelow paths+ dark paths

More graphically:

How to include/exclude tags when computing a route #

This depends on whether you want to include Situm’s Map Viewer, our built-in wayfinding UI (recommended) or you want to use the raw SDK data (positioning, route engine, etc.) to build your own.

Using the MapView component (recommended) #

In this case, you have two options:

• Using the MapViewer configuration (recommended)
• Programmatically

From MapView configuration (recommended) #

You can set several settings from the Map Viewer Settings Panel, including which tags you want to include / exclude from your routes. Therefore, one simple option is to just to create one or more configurations (which will differ on the tags that you’ll include/exclude) and, at runtime, load one or the other based on the “remoteIdentifier” parameter of the Map Viewer.

Programmatically #

Another option is to modify directly the paths to include/exclude programmatically, by using SDK methods specifically designed for this. To this extent, you’ll need to wait until the MapViewer component loads (until onLoad() method is called). Then you may call these methods as follows:

val excludedTags = listOf("tag1", "tag2")
val includedTags = listOf("tag3", "tag4")
val options = MapViewDirectionsOptions.Builder()
      .setExcludedTags(excludedTags)
      .setIncludedTags(includedTags)
      .build()
//The mapViewController is obtained in the onLoad callback
mapViewController.setDirectionsOptions(options)

let includedTags = ["tag1", "tag2"]
let excludedTags = ["tag3", "tag4"]
let mapViewDirectionsOptions = SITMapViewDirectionsOptions(includedTags: includedTags,excludedTags: excludedTags)
mapViewController?.setDirectionsOptions(mapViewDirectionsOptions)

//Call this after the mapview finished loading
let directionsOptions: MapViewDirectionsOptions = {
              excludedTags: ['tag1','tag2'],
              includedTags: ['tag3','tag4'],
            }
        
_mapViewRef.setDirectionsOptions(directionsOptions);

Using the SDK raw directions engine (not recommended) #

An alternative to using our MapViewer (built-in UI) is to use the SDK routing engine directly. If you want to do this, you can configure your DirectionsRequest with the included/excluded tags that you want:

val excludedTags = listOf("tag1", "tag2")
val includedTags = listOf("tag3", "tag4")
val directionsRequest = DirectionsRequest.Builder()
   //Add the other neccessary things in the directionsRequest and then add the tags
   .includedTags(includedTags)
   .excludedTags(excludedTags)
   .build()
SitumSdk.directionsManager().requestDirections(directionsRequest, object: Handler<Route> {
    override fun onSuccess(obtained: Route?) {
    }

    override fun onFailure(error: Error?) {
    }
})

let directionsRequest = SITDirectionsRequest(location: <SITLocation>, withDestination: <SITPoint>, includedTags: includedTags, excludedTags: excludedTags)
SITDirectionsManager.sharedInstance().requestDirections(request)

const includedTags = ['tag1','tag2'];
const excludedTags = ['tag3','tag4'];
SitumPlugin.requestDirections(_building, from, to, {
      minimizeFloorChanges,
      accessibilityMode,
      bearingFrom,
      includedTags,
      excludedTags,
    })