01 – Android quickstart guide

This guide refers to the previous version of the WYF module, which is no longer maintained. We strongly recommend visiting the updated guide which will guide you on how to integrate the new visual component, MapView.
To stay up to date, checkout the Android SDK Changelog and visit the migration guide to ease the transition to the new library.

In this tutorial, we will guide you step by step to set up your first application using Situm Wayfinding Module. We have also prepared a sample app that shows how to use the Situm Wayfinding Module in different situations.

Configure the WYF module in your Android project #

First of all, you must include the Wayfinding Module in your Android project. 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" file

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

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 WYF library dependency to the “build.gradle” file (to the individual module file, not to the project’s “build.gradle” file). You must specify your desired SDK version (see Changelog for details) and add the transitive = true property to download the Situm SDK dependencies.

//Add this to your module's "build.gradle" file

dependencies {
 
    ...
    implementation ('es.situm:situm-wayfinding:X.Y.Z-alpha@aar') {
        transitive = true
    }
}

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

android.useAndroidX=true
android.enableJetifier=true

Common issues #

Under some Gradle versions or specific configurations you may see this error when you compile Situm SDK.

Duplicate class androidx.lifecycle.ViewModelLazy found in modules lifecycle-viewmodel-2.5.1-runtime (androidx.lifecycle:lifecycle-viewmodel:2.5.1) and lifecycle-viewmodel-ktx-2.2.0-runtime (androidx.lifecycle:lifecycle-viewmodel-ktx:2.2.0)

If this is the case, introduce this in your app’s build.gradle

dependencies {
    ...

    //Change this version with the most recent stable version from https://developer.android.com/jetpack/androidx/releases/lifecycle
    def lifecycle_version = "2.5.1". 

    implementation "androidx.lifecycle:lifecycle-viewmodel:$lifecycle_version"
    implementation "androidx.lifecycle:lifecycle-viewmodel-ktx:$lifecycle_version"

    ... 
}

Set your Situm credentials #

There are two ways to set the Situm 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:

<?xml ...>
<manifest ...>
    <application
    ...>

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

        ...
        <activity ...></activity>
    </application>
</manifest>

Option 2: Programmatically #

If you choose to load SitumWYF programmatically, you cal also set the credentials this way. In the code, you can set the user and API key with:

librarySettings.setApiKey("SITUM_USER_EMAIL", "SITUM_API_KEY");

or you can set the user and password with:

librarySettings.setUserPass("SITUM_USER_EMAIL", "SITUM_PASSWORD");

Configure Google Maps #

Situm WYF uses Google Maps as a base layer, on top of which everything else is drawn: floorplans, routes, user’s location… More concretely, it uses the Dynamic Maps service, which has a generous free tier.

First, you should create an API Key for your project. Then, add the API Key to your “AndroidManifest.xml” file:

<?xml ...>
<manifest ...>
    <application
        ...>

        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="GOOGLE_MAPS_APIKEY" />
   
        ...
        <activity ...></activity>
    </application>
</manifest>

Other configurations #

Android Pie Devices #

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

...
   <application ...>

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

   <application/>
...

Search bar #

By default, the wayfinding library will include a POI search Toolbar. In order to work, you should either tell your activity or app theme that you already have a Toolbar by adding these lines to your “values/themes/themes.xml

<resources ...>
    <style ...>

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

    ...        
    </style>
</resources>

or remove the Situm search Toolbar.

Add SitumMapView #

Option 1: Programmatically #

Adding the view in the xml it’s easier and faster but it doesn’t allow you to interact much with the module. This is solved by adding the view programmatically. To do this follow the steps:

First, inside of your layout (layouts/activity_main.xml) you need to add a view where the map is going to be:

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout 

    ...
    <FrameLayout
        android:id="@+id/maps_library_target"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

    ...
</androidx.constraintlayout.widget.ConstraintLayout>

After that in the onCreate method of your activity you need to initialize the module:

public class MainActivity extends AppCompatActivity {

    SitumMapsLibrary mapsLibrary = null;
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        //Create LibrarySettings and set the account credentials
        LibrarySettings librarySettings = new LibrarySettings();
        librarySettings.setApiKey("EMAIL", "APIKEY");

        //Build the view and load it (with the library settings previously set)
        mapsLibrary = new SitumMapsLibrary(R.id.maps_library_target, this, librarySettings);
        mapsLibrary.load();
    }
}

Option 2: From XML #

In your layouts/activity_main.xml file declare the SitumMapView:

...
<es.situm.wayfinding.SitumMapView
    android:id="@+id/map_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />
...

Enjoy your new app! #

After doing this the module will be shown and it can be used. If you want to interact more with it you can use the classes “LibrarySettings” and “SitumMapsLibrary” to do it.

That’s it! You will be able to build and run this app. Try it out and for more advanced uses, go to our sample app in Github.

Suscríbete a nuestro boletín

INFORMACIÓN BÁSICA SOBRE PROTECCIÓN DE DATOS

Responsable del tratamiento: SITUM TECHNOLOGIES, S.L.
Contacto: Responsable del tratamiento: situm@situm.es
Responsable de protección: dpo@situm.es
Finalidad y base legal: Gestionar el envío de newsletter de SITUM sólo con consentimiento.
Legitimación: Consentimiento expreso del interesado.
Destinatarios: Los datos no serán cedidos a terceros salvo obligación legal.
Plazo de conservación: Mientras la parte interesada permanezca suscrita al newsletter (en cada newsletter enviado por Situm estará disponible un link para darse de baja).
Derechos: El interesado podrá revocar en cualquier momento su consentimiento, así como ejercitar los derechos de oposición, acceso, conservación, rectificación, limitación, supresión de datos y no ser objeto de una decisión basada únicamente en el tratamiento automatizado de datos, dirigiéndose por escrito a SITUM en las direcciones indicadas.
Información Adicional: Puede consultar la información adicional y detallada sobre Protección de Datos en nuestra política de privacidad.

Por favor, descarga tu copia aquí.

Muchas gracias por descargar nuestro whitepaper. No dudes en contactar con nosotros si quieres saber más sobre cómo nuestras soluciones pueden ayudar a tu negocio.


Cerrar ventana