A basic Android app :

Situm SDK can be used to build Wayfinding and Tracking applications, and dozens of use cases within those realms. However, there is a common pattern or skeleton that most Situm based applications will follow. In this Section, we provide an Android step-by-step guide to build your first Situm app based on this pattern.

1. Import Situm SDK in your project dependencies

First of all, you will need to include Situm SDK as part of your project dependencies. This will allow you to compile your app using Situm SDK and to use Situm SDK's classes and methods.

To do this, first of all you should add the maven repository to your project's "build.gradle (Project: My_Application)":

allprojects {
    repositories {
        maven { url "https://repo.situm.es/artifactory/libs-release-local" }
    }
}

Then add the Situm SDK library dependency into the section dependencies of the "build.gradle (Module: My_Application.app)" file. Please specify your desired SDK version (see Changelog for details). It's important to add the transitive = true property to download the Situm SDK dependencies.

// build.gradle (Module: My_Application.app)
...
dependencies {
    ...
    //Change X.Y.Z with the SDK version you want
    implementation ('es.situm:situm-sdk:X.Y.Z@aar') { 
        transitive = true
    }
}

2. Import and initialize Situm SDK

Then, you must initialize the SDK in the onCreate() method of your Application. You may do this in your MainActivity or anywhere else.

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

3. Set your credentials

There are two ways to set the credentials, in the AndroidManifest.xml file or programmatically.

Option 1: AndroidManifest.xml

You can set the credentials (user and API key) in the AndroidManifest.xml file adding the next meta-data fields. These data can be obtained from https://dashboard.situm.es/accounts/profile.

//AndroidManifest.xml
...
<application >

...
<meta-data
    android:name="es.situm.sdk.API_USER"
    android:value="API_USER_EMAIL" />
<meta-data
    android:name="es.situm.sdk.API_KEY"
    android:value="API_KEY" />

...
  </application>

Option 2: Programmatically

You may also configure your credentials programmatically. This allows you to use either:

User and API_KEY credentials.
User and password credentials.

Either way, you may do it by using the following methods in your application's code:

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

4. Request application permissions

According to Android docs, application permissions help support user privacy by protecting access to restricted data and restricted actions. Broadly, permissions can be categorized in:

Install-time. Allow access to data and actions that extend beyond your app's sandbox, but the data and actions present very little risk to the user's privacy, and the operation of other apps.
Runtime. Also known as dangerous, they give the app additional access to restricted data, and/or allow the app to perform restricted actions that more substantially affect the system.

Install-time permissions are already declared by the Situm SDK itself (therefore automatically granted when the user installs the app). Runtime permisions, however, need to be declared in the AndroidManifest.xml file of your app.

//AndroidManifest.xml
<manifest>
...

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

...
</manifest>

Then, at runtime, you will need to ask the user if they wish to grant your app this permissions.

//MainActivity.java
...

ActivityCompat.requestPermissions(MainActivity.this, new String[]{Manifest.permission.ACCESS_FINE_LOCATION},0);

You may follow this Android guide for more details on this topic.

5. Configure positioning parameters

Next, you will need to configure the positioning parameters. You may do this by building a LocationRequest object. For example, the following code snippet shows how to set up positioning with the default parameters.

//MainActivity.java

import es.situm.sdk.location.LocationRequest;
...

public class MainActivity extends AppCompatActivity{
    private static final String TAG = MainActivity.class.getSimpleName();

      LocationRequest locationRequest = new LocationRequest.Builder().build();

In another example, you may specify that you want: 1) use WiFi but not BLE for positionining, 2) execute Situm SDK as a Foreground Service. Running Situm as a Foreground Service is recommended if you want to provide positioning while you app is in the Background (recommended for tracking applications).

    LocationRequest locationRequest = new LocationRequest.Builder()
                .useWifi(true)
                .useBle(false)
                .useForegroundService(true)
                .build();

Or, instead of letting Situm SDK use the Global Mode (default), you may want to specify manually the building where you want to be located (Building Mode).

LocationRequest locationRequest = new LocationRequest.Builder()
        .buildingIdentifier("BUILDING_IDENTIFIER")
        .build();

Please go to the LocationRequest Javadoc for a full reference on all the configuration options.

6. Start Positioning

Finally, you may start the positioning by calling the LocationManager with two arguments:

The LocationRequest, which will contain the positioning configuration parameters (see previous Section).
An implementation of the LocationListener, which will contain three callback methods that will called every time a new result is produced:
1. onLocationChanged. It will receive every new location produced.
2. onStatusChanged. It will receive every status change produced inside the SDK.
3. onError. It will receive any error that the SDK informs.

//MainActivity.java
...
import es.situm.sdk.location.LocationListener;
import es.situm.sdk.location.LocationStatus;
import es.situm.sdk.model.location.Location;
import es.situm.sdk.error.Error;

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

   private LocationListener locationListener = new LocationListener() {
           @Override
           public void onLocationChanged(Location location) {
               Log.i(TAG, "onLocationChanged() called with: location = [" + location + "]");
            ...
           }

           @Override
           public void onStatusChanged(@NonNull LocationStatus status) {
               Log.i(TAG, "onStatusChanged() called with: status = [" + status + "]");
            ...
           }

           @Override
           public void onError(@NonNull Error error) {
               Log.e(TAG, "onError() called with: error = [" + error + "]");
            ...
           }
       };


...

   private void startPositioning() {

        ActivityCompat.requestPermissions(MainActivity.this, new String[]{Manifest.permission.ACCESS_FINE_LOCATION},0);                                                                                                                                                                                                                  
	SitumSdk.locationManager().requestLocationUpdates(locationRequest, locationListener)                                                                                                                                 
}

At this point, Situm SDK will start computing your geolocation. Your application log should show something like this:

7. Stop Positioning

At any point you may choose to stop the positioning system. You may do so by calling the method removeUpdates.

 private void stopPositioning() {

 if (!SitumSdk.locationManager().isRunning()) {
            return;
  }

SitumSdk.locationManager().removeUpdates(locationListener);
}

A basic Android app Print

Related Articles