- Step 1: Configure our SDK in your Android project
- Step 2: Initialize the SDK
- Step 3: Set your credentials
- Step 4: Setup Google Maps
- Optional step 5: location and runtime permissions
- Optional step 6: Setup indoor positioning
- Positioning: Download the buildings in your account and how to start the positioning in a building.
- Indoor-Outdoor: Use the indoor-outdoor positioning.
- Draw building: Draw the floorplan of a building over a map.
- Draw position: Draw the position you obtain from the SDK in the map.
- Draw pois: Draw the pois of a building over the map
- Draw route: Draw a route between to points over the map
- Show realtime: Draw the users that are position inside a building over a map.
- Building events: Get the events of a building.
- User inside event: Calculate if the user is inside a event.
- Poi filtering: Filter the pois with a especific key-value.
- Guide instructions: Give indications when you are going to a point.
- Animate position: Animate the position and the camera.
- Point inside geofence: Draw geofences and calculate if a point is inside them.
- Update location parameters: Update the parameters of the location on the fly.
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:
- Obtain information related to buildings where Situm's positioning system is already configured: floor plans, points of interest, geotriggered events, etc.
- Retrieve the location of the smartphone inside these buildings (position, orientation, and floor where the smartphone is).
- 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).
- 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 Situm SDK. 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.
- Go to the sign in form and enter your username and password to sign in.
- Go to the account section and on the bottom, click on "generate one" to generate your API KEY.
- Go to the buildings section and create your first building.
- 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.
First of all, you must configure Situm SDK 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 the maven repository to the project build.gradle:
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 app build.gradle.
It's important to add the
transitive = true
property to download the Situm SDK dependencies.
implementation ('es.situm:situm-sdk:2.46.2@aar') {
transitive = true
}
You must initialize the SDK in the onCreate()
method of your Application:
@Override
public void onCreate() {
super.onCreate();
SitumSdk.init(this);
}
There are two ways to set the credentials, in the AndroidManifest.xml
file or programmatically.
You can set the credentials (user and API key) in the AndroidManifest.xml
file adding the next meta-data
fields:
<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" />
In the code, you can set the the user and API key with:
SitumSdk.configuration().setApiKey("USER_EMAIL", "API_KEY");
or you can set the user and password with:
SitumSdk.configuration().setUserPass("USER_EMAIL", "PASSWORD");
This step is only necessary if you want to run the sample that draws the buildings' floorplan over the Google Maps map. Otherwise, you can skip it and continue with the code samples.
First of all, you need to add the Google Services dependency to the project. If you need more info: Setup Google Play Services. To do this, paste the dependency in your module build.gradle as usual:
implementation 'com.google.android.gms:play-services-maps:16.0.0'
Add in the app manifest the version of the Google Play Services that we have imported. To do this, paste the next snippet inside the application tag:
<meta-data
android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />
An api key is needed to add Google Maps Services and use them in an application. If you need more info, you can visit the official Google Maps documentation. To obtain a Google api key please refer to the same documentation: obtain Google Maps api key, then go back to your app module file build.gradle and replace 'gmaps_api_key' with the value of the obtained key from Google.
resValue 'string', 'google_maps_key', "YOUR_API_KEY"
All the necessary permissions are already declared by the SDK, but the ACCESS_COARSE_LOCATION
is a dangerous permission, so your app must prompt the user to grant permission at runtime. More info at Android Developers .
If you want to use indoor-outdoor positioning using GPS, you must declare ACCESS_FINE_LOCATION
permission in your AndroidManifest.xml
and request the permission at runtime.
In order to use indoor positioning, you must define which building you want to position in. This can be achieved by editing the value of private static final String BUILDING_ID = "YOUR_BUILDING_ID";
in PositioningActivity
More info is available at our Developers Page.
For any question or bug report, please send an email to [email protected]