The entry point of Situm SDK is the SitumSdk class. This class allows you to:

  1. Initialize Situm SDK and provide the appropriate credentials.
  2. Specify the common configurations that have a traversal effect across the SDK.
  3. Access the SDK Managers, utility classes that will allow you to access to all the functionalities and resources.  


SDK Initialization


The first thing you should do with Situm SDK is initialize it using the SitumSdk.init method. This does not start positioning or retrieve any resource from Situm Platform: it just allocates the required resources for the SDK to run. We recommend to do this as soon as possible on your application's lifecycle: for instance, on the onCreate() method of your MainActivity.


The following snippet shows you how to do it.


//MainActivity.java

import es.situm.sdk.SitumSdk;
...

public class MainActivity extends AppCompatActivity{
    private static final String TAG = MainActivity.class.getSimpleName();
  
   @Override
    public void onCreate() {
        super.onCreate();
        ...
        
        SitumSdk.init(this);
    }
}


Traversal configurations

Credentials


As explained in the Basic Android App, you may provide you account credentials using the AndroidManifest.xml  or programatically. The SitumSdk class enabled the second option either by providing:

  1. User and API_KEY credentials, using the Situmsdk.Configuration.setApiKey method.
  2. User and password credentials, using the SitumSdk.Configuration.setUserPass method.


See the following snippet as an example on how to do it:


//You may use your user email and API_KEY
SitumSdk.configuration().setApiKey("USER_EMAIL", "API_KEY");

//... or your user email and password
SitumSdk.configuration().setUserPass("USER_EMAIL", "PASSWORD");

Afterwards, you may retrieve the user's email provided by calling the method SitumSdk.Configuration.currentEmailAccount


Cache Max Age


As explained in this article, Situm SDK stores in the local cache of the smartphone the information it downloads from Situm Platform. Therefore, this information will be available in future requests without making network requests.  


You may configure how long this information will be stored in the smartphone's cache by using the method SitumSdk.Configuration.setCacheMaxAge as in the following example:


//Information will be cached for 1 day at most
SitumSdk.configuration().setCacheMaxAge(1, TimeUnit.DAYS);

//Information will be cached for 1 second at most
SitumSdk.configuration().setCacheMaxAge(1, TimeUnit.SECONDS);


Caching this information may have a different effect depending on the Cache Strategy that you configure. See this article for details.



Connecting to your own Situm Platform instance


In case you are running Situm Platform in your own premises or private cloud, you may want to configure the URL to which Situm SDK connects by using the SitumSdk.Configuration.setDashboardURL method.


//Situm SDK will connect to https://your-own-server.com
SitumSdk.configuration().setDashboardURL("https://your-own-server.com");


Sometimes, in development environments you may want to use self-signed certificates. These certificates will not have a valid Authority, therefore Situm SDK will not work. You may bypass this issue by calling the method SitumSdk.configuration().allowInvalidSSLCertificate right after you initialize the Situm SDK.


//Situm SDK will trust the SSL certificate of the server (even if its Authority is not valid)
SitumSdk.init(this);
SitumSdk.configuration().allowInvalidSSLCertificate(true);

Please take into account that, by using this option, you may be exposing your app and network to unnecessary security risks. Use it at your own risk.



Situm SDK Managers


Managers are utility classes that will allow you to access to all the functionalities and resources.   


LocationManager


The LocationManager handles all configurations & functionalities related to Indoor & Outdoor Positioning. You may refer to Section Positioning for all the details on this manager.


You may access this manager by using the method SitumSdk.locationManager.


LocationManager locationManager = SitumSdk.locationManager();


CommunicationManager


The CommunicationManager handles all configurations & functionalities related to communications & cartography. You may refer to Section Communications & Cartography for all the details on this manager.


You may access this manager by using the method SitumSdk.communicationManager.


CommunicationManager communicationManager = SitumSdk.communicationManager();


DirectionsManager


The DirectionsManager handles all configurations & functionalities related to computing the shortest route from a point A to a point B.  


You may access this manager by using the method SitumSdk.directionsManager.


DirectionsManager directionsManager = SitumSdk.directionsManager();


NavigationManager


The NavigationManager handles all configurations & functionalities related to computing turn by turn directions & indications while the user moves along a route (previously computed using the DirectionsManager).  


You may access this manager by using the method SitumSdk.navigationManager.




NavigationManager navigationManager = SitumSdk.navigationManager();


RealtimeManager


The RealtimeManager handles all configurations & functionalities related to retrieving the real-time geolocation of other users from Situm Platform.  


You may access this manager by using the method SitumSdk.navigationManager.


RealTimeManager realTimeManager = SitumSdk.realtimeManager();