Situm SDK downloads & stores in the local cache of the smartphone the data from Situm Platform (e.g. building data). This helps avoiding future network calls when these resources are needed, saving mobile data & battery.
This also enables the in-phone computing feature. While other solutions continuously send sensor data to a server that handles heavy geolocation computing, Situm SDK has been optimised to make all the computations on the smartphone, provided that some pre-required data (e.g. Positioning Modesl) has been previously downloaded. Therefore, Situm SDK works even if there is no connectivity.
How does Situm download & store information? #
How Situm downloads & stores the information depens on:
- The Cache Strategy (see below).
- Whether the information is versioned or not. Versioned information can be downloaded only if there is a new version available in Situm Platform: this makes sense specifically for heavy data types.
The following table describes the most important information types and how Situm downloads & stores them:
| Type | How does Situm SDK download & store it? | Versioned? |
|---|---|---|
| Building Cartography Info: Floors (with the exception of floorplan images), POIs, CustomFields… | Downloaded & stored in the local cache when the app calls a method to download it, such as CommunicationManager.fetchBuildings (Android), or SITCommunicationManager.fetchBuildings (iOS). The CommunicationManager.prefetchPositioningInfo (Android) or SITCommunicationManager.prefetchPositioningInfo (iOS) methods also download & store this information. | No |
| Real-time positioning information: information about the location of other users in the building. | Downloaded periodically after the app calls the method RealTimeManager.requestRealTimeUpdates. This information is not stored in the local cache because it should be refreshed every few seconds. | No |
| Positioning Model, built from the data collected during the calibration phase | Downloaded & stored in the local cache when: 1) the app starts positioning in Building Mode in a certain building, or 2) the app is positioning in Global Mode and the Building Detector detects that the user is in a new building (e.g. the user has gone from a building to another one), or 3) the app calls any of the CommunicationManager.prefetchPositioningInfo (Android) or SITCommunicationManager.prefetchPositioningInfo (iOS) methods. | Yes |
| Floorplan images | Downloaded & stored in the local cache when the app downloads it using the CommunicationManager.fetchMapFromFloor (Android) or SITCommunicationManager.fetchMap (iOS) method. | Yes |
Cache strategies #
As explained above, Situm SDK implements several cache strategies that allow you to choose how information should be stored, and when it should be refreshed.
TIMED_CACHE (DEFAULT) #
This is the default and recommended strategy. Under it, each piece of information is stored in the smartphone’s cache with a limited lifespan. When the cache is empty or expired, the following may happen:
- On unversioned information (e.g. POIs), the cache is cleared and the information is downloaded again.
- On versioned information (e.g. Positioning Models), each piece of information is downloaded again only if there is a new version available in Situm Platform.
The following example shows (for Android, iOS is similar) how to configure this cache strategy to use it when downloading the list of buildings with their basic information. In this example, SitumSDK will use the building information already stored in the cache if this information has been stored for less than 1 day. Otherwise, Situm SDK will download the information from Situm Platform.
//Sets the TIMED_CACHE to 1 day
maxSitumSdk.configuration().setCacheMaxAge(1, TimeUnit.DAYS);
//Configures a TIMED_CACHE strategy...
NetworkOptions networkOptions = new NetworkOptionsImpl.Builder().
setCacheStrategy(NetworkOptions.CacheStrategy.TIMED_CACHE).build();
CommunicationConfig communicationConfig = new CommunicationConfigImpl(networkOptions);
//... and uses it to retrieve the buildings of the account
SitumSdk.communicationManager().fetchBuildings(communicationConfig, new Handler<Collection<Building>>() {
@Override
public void onSuccess(Collection<Building> buildings) {
Log.i(TAG, "Success! ");
}
@Override
public void onFailure(Error error) {
Log.i(TAG, "Error! ");
}
});
The lifespan of the cache information is 5 seconds by default, but as shown in the previous example this can be configured using the method SitumSdk.configuration().setCacheMaxAge (Android) or SITCommunicationManager.setCacheMaxAge (iOS)
CACHE_FIRST #
As opposed to the TIMED_CACHE strategy, under the CACHE_FIRST strategy the cached information does not have a lifespan. This means that, once the information is downloaded from Situm Platform, Situm SDK will always return this cached information without re-download it from Situm Platform, unless the developer invalidates the cache using the CommunicationManager.invalidateCache (Android) or SITCommunicationManager.clearCache (iOS) method. This strategy is only recommended in case you require very fine control of when the information reload is acceptable.
The following snippet shows (for Android, iOS is similar) how to configure this method and invalidate the cache:
//Configures a CACHE_FIRST strategy...
NetworkOptions networkOptions = new
NetworkOptionsImpl.Builder().
setCacheStrategy(NetworkOptions.CacheStrategy.CACHE_FIRST ).build();
CommunicationConfig communicationConfig = new CommunicationConfigImpl(networkOptions);
//... and uses it to retrieve the buildings of the account
SitumSdk.communicationManager().fetchBuildings(communicationConfig, new Handler<Collection>() {
@Override
public void onSuccess(Collection buildings) {
Log.i(TAG, "Success! ");
}
@Override
public void onFailure(Error error) {
Log.i(TAG, "Error! ");
}
});
//... You may invalidate the cache at any time...
SitumSdk.communicationManager().invalidateCache();
SERVER_FIRST #
The SDK always tries to download the information from Situm Plaftorm. If this information is not available (e.g. network failure), Situm SDK will try to retrieve it from the cache as a second option.
//Configures a SERVER_FIRST
strategy...NetworkOptions networkOptions = new
NetworkOptionsImpl.Builder().setCacheStrategy(NetworkOptions.CacheStrategy.SERVER_FIRST).build();
CommunicationConfig communicationConfig = new CommunicationConfigImpl(networkOptions);
//... and uses it to retrieve the buildings of the account
SitumSdk.communicationManager().fetchBuildings(communicationConfig, new Handler<Collection<Building>>() {
@Override
public void onSuccess(Collection<Building> buildings) {
Log.i(TAG, "Success! ");
}
@Override
public void onFailure(Error error) {
Log.i(TAG, "Error! ");
}
});
IGNORE_CACHE #
All the information requests go straight to the network, without checking if the information is available in the cache. This is only recommended in development environments. The cache is not even used in case of network failure.
The following snippet shows you how to configure this method and invalidate the cache:
//Configures a IGNORE_CACHE strategy...
NetworkOptions networkOptions = new NetworkOptionsImpl.
Builder().setCacheStrategy(NetworkOptions.CacheStrategy.IGNORE_CACHE).build();
CommunicationConfig communicationConfig = new CommunicationConfigImpl(networkOptions);
//... and uses it to retrieve the buildings of the account
SitumSdk.communicationManager().fetchBuildings(communicationConfig, new Handler<Collection<Building>>() {
@Override
public void onSuccess(Collection<Building> buildings) {
Log.i(TAG, "Success! ");
}
@Override
public void onFailure(Error error) {
Log.i(TAG, "Error! ");
}
});
Useful cache operations #
In addition to the cache strategies that we have seen in the last section, there are some useful cache operations that you should know.
Erase cache #
You may delete all the cache information at any time using the CommunicationManager.invalidateCache method (Android) or SITCommunicationManager.clearCache (iOS).
Refill cache (prefetch) #
You may also download all the information of any building (such the Positioning Models, floors & floorplans, POIs, etc.) at any time. This is useful, for example, if you want to make sure that when the user arrives to a building all the required information will be available without delay (e.g. to start positioning right away or to show the floorplans without waiting for their download to complete).
To do this, you may use the family of CommunicationManager.prefetchPositioningInfo methods.
//Downloads all the building information & stores it in the cache, including the
//Positioning Models, cartography and even the//floorplan images (thanks to the setPreloadImages setter)
NetworkOptions networkOptions = new NetworkOptionsImpl.Builder().setPreloadImages(true).build();
CommunicationConfig communicationConfig = new
CommunicationConfigImpl(networkOptions);
SitumSdk.communicationManager().prefetchPositioningInfo(communicationConfig, new Handler<String>(){
@Override
public void onSuccess(String s) {
Log.i(TAG, "Success! " + s);
}
@Override public void onFailure(Error error) {
Log.e(TAG, "Error! " + error);
}
});
Cache lifespan #
This changes the lifespan of the cache for the TIMED_CACHE strategy (see above). We recommend to use a value of, at least, 24 hours. You may modify this value using the method SitumSdk.configuration().setCacheMaxAge (Android) or SITCommunicationManager.setCacheMaxAge (iOS)
