05 – External provider locations

You may want to use the majority of functionalities that Situm has to offer (cartography, routes, maps…), but not our positioning system. 2 typical examples:

• You have your own positioning system and you want to leverage on our maps & routes.
• You want to inject fake locations so you can test how Situm SDK & WYF would behave (e.g. how geolocation will be visualized, how routes would be computed, etc.).

The External Provider Locations functionality allows you to do that. Instead of computing the geolocation, the SDK will rely on the ones you provide. Aside from that, everything will work as usual with a few exceptions:

• This mode only works with Building mode (right now it is not compatible with the Global mode).
• When this mode is enabled the SDK doesn’t scan WiFi, BLE and GPS.
• This mode is only available for Android SDK v 2.78.0 onwards and Situm WYF for Android for v 0.18.0 onwards.

How to enable this mode #

It’s pretty easy: you just need to call one method after you do “SitumSdk.init(context)”. See below:

SitumSdk.init(context);

//The SDK will not compute internal locations, but rely on external ones
SitumSdk.configuration().useExternalLocations(true);

//The SDK will not compute internal locations, but rely on external ones
SITServices.setUseExternalLocations(true)

SitumSdk().init();
SitumSdk().setConfiguration(ConfigurationOptions(
    useExternalLocations: true));

How to use it #

After enabling this mode you need to start the positioning like you would normally do:

//Important! The LocationRequest needs to contain your buildingId, this mode doesn't work without it
LocationRequest locationRequest = new LocationRequest.Builder()
        .buildingIdentifier("BUILDING_ID")
        .build();
        
//Start positioning as always
SitumSdk.locationManager().requestLocationUpdates(locationRequest, locationListener);

//Set the delegate that will receive the location updates
SITLocationManager.sharedInstance().addDelegate(self)
//Important! The LocationRequest needs to contain your buildingId, this mode doesn't work without it
let locationRequest = SITLocationRequest(buildingId: "BUILDING_ID")
//Start positioning as always
SITLocationManager.sharedInstance().requestLocationUpdates(locationRequest)

//Start positioning as always
SitumSdk().requestLocationUpdates(LocationRequest());

After this, you just need to add your location. You can do it as many times as you want. If you stop calling this method the last location will be the last you have added.

Android

//You may call the addExternalLocation() method everytime you want to inject a new location
//The SDK will notify each location added through the LocationListener
SitumSdk.locationManager().addExternalLocation(new ExternalLocation.Builder("BUILDING_ID","FLOOR_ID", 1.23456, 2.34567).build());

//You may call the addExternalLocation() method everytime you want to inject a new location
//The SDK will notify each location added through the LocationListener
let externalLocation = SITExternalLocation(buildingIdentifier: "BUILDING_ID", floorIdentifier: "FLOOR_ID", latitude: 1.23456, longitude: 2.34567)
SITLocationManager.sharedInstance().add(externalLocation)

//You may call the addExternalLocation() method everytime you want to inject a new location
//The SDK will notify each location added through the LocationListener
SitumSdk().addExternalLocation(ExternalLocation(coordinate: Coordinate(latitude: 44.55555, longitude: 22.33333), buildingIdentifier: "BUILDING_ID", floorIdentifier: "FLOOR_ID"));

Other things to keep in mind #

• Don’t update the location more than once per second (otherwise, just the last one will be taken into account).
• If you’re using this method to simulate the SDK behaviour, it’s common to read the external locations from an external file (just code a simple file reader and you’re good to go).