03 – Working offline with cached data

Please note! All the code snippets in this section have been provided for Android. If you use iOS, you’ll find it easy to translate them appropriately.

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:

  1. The Cache Strategy (see below).  
  2. 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:  

TypeHow 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 phaseDownloaded & 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 imagesDownloaded & 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! ");    
        }
});
//Sets the TIMED_CACHE to 1 day 
SITCommunicationManager.shared(86400).setCacheMaxAge()

//As TIMED_CACHE is the default one, you dont need to do anything else
SITCommunicationManager.shared().fetchBuildings(options: nil, success: { mapping in
    print ("Success!")
}, failure: { error in
    print("Failure!")
})

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 (Only in Android) #

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) 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 (Only in Android) #

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! ");
        }
});
//Configures a IGNORE_CACHE strategy...
let options = [SITForceRequestKey:true]

//... and uses it to retrieve the buildings of the account
SITCommunicationManager.shared().fetchBuildings(options: options, success: { mapping in
    print ("Success!")
}, failure: { error in
    print("Failure!")
})

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)

Subscribe to our newsletter

BASIC INFORMATION ON DATA PROTECTION

Data controller: SITUM TECHNOLOGIES, S.L.
Contact: Data controller: situm@situm.es
Responsible for protection: dpo@situm.es
Purpose and legal basis: To manage the sending of SITUM newsletters only with consent.
Legitimation: Express consent of the interested party.
Recipients: The data will not be passed on to third parties with the exception of legal obligations.
Retention period: As long as the interested party remains subscribed to the newsletter (a link to unsubscribe will be available in each newsletter sent by Situm).
Rights: The interested party may at any time revoke their consent, as well as exercise their rights of opposition, access, conservation, rectification, limitation, deletion of data and not be subject to a decision based only on automated data processing, by writing to SITUM at the addresses indicated.
Additional Information: You can consult additional and detailed information on Data Protection in our privacy policy.

Please, download your copy here

Thank you for downloading our whitepaper. Please do not hesitate to contact us if you would like to know more about how our solutions can help your business. Download whitepaper


Close window