01 – A basic Java 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.

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 either to your project’s “build.gradle” file (for Gradle versions <=6) or to your “settings.gradle” file (for Gradle versions >7).

//Add this to your Project's build.gradle

allprojects {
    repositories {
        maven { url "https://repo.situm.es/artifactory/libs-release-local" }
    }
}
//Add this to your Project's settings.gradle

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url = "https://repo.situm.com/artifactory/libs-release-local"
        }
    }
}

Then add the Situm SDK library dependency into the section dependencies of your application “build.gradle” 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 of your app
...
dependencies {
    ...
    //Change X.Y.Z with the SDK version you want
    implementation ('es.situm:situm-sdk:X.Y.Z@aar') { 
        transitive = true
    }
}

Finally, make sure your gradle.properties (Project properties) contains these two lines:

android.useAndroidX=true
android.enableJetifier=true

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

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:

  1. User and API_KEY credentials.
  2. User and password credentials. 

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

// MainActivity.java. You may insert this code in then onCreate(), always after the SitumSDK.init()

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

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:

  1. 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.
  2. 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. You may insert this code in then onCreate(), always after the SitumSDK.init() 

...


// We ask for location permissions
// Warning! This is a naive way to ask for permissions for the example's simplicity
// Check https://developer.android.com/training/permissions/requesting to know how
// to ask for permissions
ActivityCompat.requestPermissions(MainActivity.this, new String[]{Manifest.permission.ACCESS_FINE_LOCATION},0);

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

Configure positioning parameters #

Next, you will need to configure the positioning parameters. You may do this by building a LocationRequest object, as shown in the following example.

//MainActivity.java. You may insert this code in then onCreate(), always after the SitumSDK.init()

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

The previous code will configure a LocationRequest with the default parameters. You may also set each parameter individually. You have two options:

  1. (Recommended) By using the Remote Configuration feature, that allows you to change the LocationRequest over-the-air using Situm Dashboard.
  2. (Not recommended) By manually setting the parameters in the LocationRequest builder.

Start Positioning #

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

  1. The LocationRequest, which will contain the positioning configuration parameters (see previous Section).
  2. 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);
        ActivityCompat.requestPermissions(MainActivity.this, new String[]{Manifest.permission.ACCESS_FINE_LOCATION},0);
        LocationRequest locationRequest = new LocationRequest.Builder().build();
        ...


        //Call requestLocationUpdates whenever you are ready to start positioning
        SitumSdk.locationManager().requestLocationUpdates(locationRequest, locationListener);
    }

   ...


   //The LocationListener will receive every location, status or error produced by Situm SDK
   private LocationListener locationListener = new LocationListener() {
        @Override
        public void onLocationChanged(@NonNull Location location) {
            Log.i(TAG, "onLocationChanged() called with: location = [" + location + "]");
        }

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

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


}

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

Stop Positioning #

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

//MainActivity.java

...

SitumSdk.locationManager().removeUpdates(locationListener);

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