02 – Initialization & common configurations

Before you perform any other operation with Situm SDK, you should initialize it and perform some common configurations. The entry point of Situm SDK is the SitumSdk class. This class allows you to do it.

Importing Situm SDK #

In order to learn how to import Situm SDK in your project, we recommend you to follow one the Quickstart guides: Android, iOS, Cordova, React Native.

SDK Initialization #

After the import step, you may initialize Situm SDK. This does not start positioning nor retrieves any resource from Situm Platform: it just allocates the required resources for the SDK to run.

The following snippet shows you how to do it in Android and React Native (we recommend to do this as soon as possible on your application’s lifecycle). In iOS & Cordova the SDK initializes itself after the import, so you don’t need to take further actions.

//MainActivity.java

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

public class MainActivity extends AppCompatActivity{
  
   @Override
    public void onCreate() {
        super.onCreate();
        ...
        
        SitumSdk.init(this);
    }
}

//App.js
import SitumPlugin from 'react-native-situm-plugin';
...

const App = () => {

  //Initialize Situm SDK
  SitumPlugin.initSitumSDK();

  ...
}
 
export default App;

Traversal configurations #

Credentials

You may provide you account credentials programmatically, as in the following example. We recommend to use the APIKEY way (see docs of the function for Android, iOS, Cordova and React Native).

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

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

//You may use your user email and API_KEY
SITServices.provideAPIKey("SET YOUR APIKEY HERE", forEmail: "SET YOUR EMAIL HERE")

//... or your user email and password (not recommended)
SITServices.provideUser("SET YOUR USER EMAIL HERE", password: "SET YOUR PASSWORD HERE")

#APIKEY based authentication
cordova.plugins.setApiKey("SITUM_EMAIL", "SITUM_API_KEY")

#User-Password based authentication
cordova.plugins.setUserPass("SITUM_EMAIL", "SITUM_PASS")

//You may use your user email and API_KEY
SitumPlugin.setApiKey("SITUM_EMAIL","SITUM_API_KEY")

//... or your user email and password
SitumPlugin.setUserPass("SITUM_EMAIL","SITUM_USER_PASSWORD")

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 (reference for Android, iOS, Cordova, ReactNative). The following snippet shows an example for Android and React Native, iOS and Cordova are similar (see reference above).

//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);

//Information will be cached for 1 hour (3600 seconds) at most
SitumPlugin.setCacheMaxAge(1*60*60)

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 (Native Android/iOS only)

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 (Android) or SITServices.setDashboardURL (iOS).

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

//Situm SDK will connect to https://your-own-server.com
SITServices.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 (Android) or SITServices.setAllowsInvalidSSLCertificate (iOS) 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);

//Situm SDK will trust the SSL certificate of the server (even if its Authority is not valid)
SITServices.setAllowsInvalidSSLCertificate(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.