Situm Wayfinding Getting Started

This is a sample Android application built with Situm Wayfinding Module. Situm Wayfinding Module has been designed to create indoor location applications in the simplest way. It has been built in the top of the Situm SDK and its functionalities has been widely tested. If you are interested in building applications using the Situm SDK, please refer to Situm Android SDK Sample app.

With the samples app you will be able to:

1. Load a Situm Map with all the buildings of your account and start the positioning for a selected building, using the SitumMapView and SitumMap objects.
2. Set listeners to receive notifications about user location, buildings, POIs and routes.
3. Get more control of the map loading using the underlying SitumMapsLibrary object.
4. Delegate onBackPressed() events for convenience.

Table of contents

Introduction

Setup

1. Step 1: Configure your Android project
2. Step 2: Set your credentials
3. Step 3: Configure Third Party Dependencies

Samples

1. SitumMapView
2. Install listeners using SitumMap
3. Load the map using SitumMapsLibrary
4. Delegate onBackPressed events
5. Set your own theme in the UI
6. Remove the situm_search_view feature
7. Customize location, navigation and directions requests

More information

Support information

Introduction

Situm SDK is a set of utilities that allow any developer to build location based apps using Situm's indoor positioning system. Among many other capabilities, apps developed with Situm SDK will be able to:

1. Obtain information related to buildings where Situm's positioning system is already configured: floor plans, points of interest, geotriggered events, etc.
2. Retrieve the location of the smartphone inside these buildings (position, orientation, and floor where the smartphone is).
3. Compute a route from a point A (e.g. where the smartphone is) to a point B (e.g. any point of interest within the building).
4. Trigger notifications when the user enters a certain area.

In this tutorial, we will guide you step by step to set up your first Android application using the Situm Wayfinding Module, which has been built in the top of the Situm SDK to extremely easy the development of indoor positioning Android applications.

Before starting to write code, we recommend you to set up an account in our Dashboard (https://dashboard.situm.es), retrieve your API KEY and configure your first building.

1. Go to the sign in form and enter your username and password to sign in.
2. Go to the account section and on the bottom, click on "generate one" to generate your API KEY.
3. Go to the buildings section and create your first building.
4. Download Situm Mapping Tool Android application. With this application you will be able to configure and test Situm's indoor positioning system in your buildings.

Perfect! Now you are ready to develop your first indoor positioning application.

Configure project

Step 1: Configure your Android project

First of all, you must configure Situm SDK and Situm Wayfinding Module in your Android project. This has been already done for you in the sample application, but nonetheless we will walk you through the process.

• Add our maven repository to the project build.gradle:

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

• Now add the Situm Wayfinding Module dependency into the dependencies section of the app build.gradle.

    implementation ('es.situm:situm-wayfinding:0.2.0-alpha@aar') {
        transitive = true
    }

It's important to add the transitive = true property to download the inherited dependencies.

• Set compatibility with Java 8 in your app build.gradle file:

android {
    ...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

• Finally, add multidex compatibility to your app build.gradle:

android {
    defaultConfig {
        ...
        minSdkVersion 16
        targetSdkVersion Y
        multiDexEnabled true
    }
    ...
}

Please remember that if your minSdkVersion is set to 20 or lower, you must use the multidex support library as follows:

dependencies {
  implementation 'com.android.support:multidex:1.0.3'
}

Step 2: Set your credentials

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

Option 1: AndroidManifest.xml file

You can set the credentials (user and API key) in the application element of your AndroidManifest.xml file adding the next meta-data fields:

<meta-data
  android:name="es.situm.maps.API_USER"
  android:value="YOUR_API_USER" />
<meta-data
  android:name="es.situm.maps.API_KEY"
  android:value="YOUR_API_KEY" />

Option 2: programmatically

When using the SitumMapsLibrary object, you can set the the user and API key with:

librarySettings.setApiKey(USER, API_KEY);

Or with user and password:

librarySettings.setUserPass(USER, PASSWORD);

Step 3: Configure Third Party Dependencies

• Get your Google Maps API key by following the instructions detailed in Google Maps Get Started. Add the API key to your AndroidManifest.xml:

<meta-data
  android:name="com.google.android.geo.API_KEY"
  android:value="AIza..." />

• If you are targeting Android Pie devices, add Apache Http Legacy to your AndroidManifest.xml:

<uses-library
  android:name="org.apache.http.legacy"
  android:required="false"/>

• By default, the wayfinding library will include a ToolBar with the situm search feature.

  • Tell your activity or app theme that you already use one by adding these lines to your styles.xml:

  <item name="windowActionBar">false</item>
  <item name="windowNoTitle">true</item>

  • Or remove the Situm search toolbar setting to false the situm_has_search_view property of your SitumMapView:

  <es.situm.wayfinding.SitumMapView
      ...
      app:situm_has_search_view="false" />

• Make sure to extend AppCompatActivity. If you chose not to use the situm_search_view feature you can just extend FragmentActivity.

• Right now, the minSdkVersion must be 16 or greater.

Samples

We have created some samples that show different use cases of this module

SitumMapView

The simplest way to use our module is by creating an empty activity and including SitumMapView in the layout file.

For more information, please refer to ActivitySampleSimpleMap.java.

Install listeners using SitumMap

If you want to get notified about what happens inside the module, your activity should implement the SitumMapView.OnMapReadyCallback interface:

For more information, please refer to ActivitySampleLogEvents.java

Load the map using SitumMapsLibrary

Under some circumstances you may prefer to control the exact moment at which the underlying maps fragment is loaded. If that is your case, just use the SitumMapsLibrary object as described in ActivitySampleUsingLibrary.java.

Delegate onBackPressed events

The Situm Map implements some convenience actions for onBackPressed Android events:

• When there is an active building selected: zoom out to see building markers again.
• When a POI is selected: deselects the current POI.
• When a route has been requested: cancels the current route.
• When an event is triggered: closes the event dialog.

If you want to keep this behaviour in your application, just delegate each onBackPressed as described in ActivitySampleDelegateBackEvents.java.

Set your own theme in the UI

You can use your own logo and color scheme in the module.

1. Define an organization theme in your Situm Dashboard.
2. Tell the module to use the organization theme. For that, see ActivitySampleDashboardTheme.java.

Remove the situm_search_view feature

If you want to remove the default situm_search_view feature, please refer to ActivitySampleNoSearchView.java.

Customize location, navigation and directions requests

The wayfinding module builds default location, navigation and directions requests. You may want to configure those requests before they are dispatched to the underlying SitumSDK. If that is your case, please refer to ActivitySampleCustomizeRequests.java.

More information

More info is available at our Developers Page.

Support information

For any question or bug report, please send an email to [email protected]