03 – A basic Cordova 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.

Pre-requisites: Configuring Cordova #

First, you need to configure Cordova by following this tutorial. Then, make sure you comply with the requirements and library versions needed for building your app for Android and iOS.

Installing the plugin #

We assume that you have already created a Cordova based app with your favourite framework. Then, you may integrate the plugin in your project in different ways.

Please note! that we are using Cocoapods in order to manage iOS dependencies, which means you might need to run pod repo update when trying to compile your app after updating our plugin.
Also check out the project code signing before you run the example.

Alternative 1: With Cordova CLI from npm or Github #

You may install the plugin using Cordova CLI

#From npm
cordova plugin add @situm/cordova

#From Github
cordova plugin add https://github.com/situmtech/cordova.git

If you have already installed our plugin, make sure you uninstall the previous version with:

cordova plugin remove situm-cordova-plugin-official

Alternative 2: Automatic installation using config.xml #

You may also define the plugin in your config.xml

<plugin name="@situm/cordova" source="npm">
</plugin>

Setup native projects #

You will also need to make some changes to the native projects of your Capacitor application.

Android #

Add the ACCESS_FINE_LOCATION permission declaration to your AndroidManifest.xml (you can omit this step if you have configured Situm SDK not to use GPS):

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

Then, make sure the minSdkVersion is set to 24 or later in your app’s build.gradle file (android/app/build.gradle).

Finally, modify your <meta http-equiv=”Content-Security-Policy”> by adding https://map-viewer.situm.com to its content attribute:

<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: https://ssl.gstatic.com https://map-viewer.situm.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *; img-src 'self' data: content:;">

iOS #

Adding the @situm/cordova to your project will automatically include the following permissions in your app’s Info.plist file (modify the permission’s informative texts as you wish):

<key>NSLocationWhenInUseUsageDescription</key>
  <string>Location is required to find out where you are</string>
<key>NSLocationAlwaysUsageDescription</key>
  <string>Location is required to find out where you are</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
  <string>Location is required to find out where you are</string>

Then, make sure you add this line in your config.xml to be able to display our map in your iOS application:

<allow-navigation href="https://map-viewer.situm.com/*" />

Requesting Permissions #

In the next section we will show you how to request all the Android and iOS permissions you could need to be able to locate users inside your building with our SDK. We will be using cordova.plugins.diagnostic package to accomplish this task, so make sure you install this package with:

cordova plugin add cordova.plugins.diagnostic

Using the plugin #

There are many things you can do with the @situm/cordova plugin. In this guide, we will show you how to do the basic stuff. For more info, take a look at our sample app and at the plugin documentation.

Code snippets #

We have built a code snippet to use our basic functionalities. So just copy and paste the following code into your www/index.html:

<!-- Add this component to your body -->
<!-- Retreive your situm api-key here https://dashboard.situm.com/accounts/profile -->
<!-- Follow this guide (https://situm.com/docs/sdk-cartography/#building-identifier)
  to find out the identifier of the building you want to display -->
<map-view
  viewer-domain="https://map-viewer.situm.com"
  situm-api-key="YOUR_SITUM_API_KEY"
  building-identifier="YOUR_BUILDING_IDENTIFIER">
</map-view>

And then copy and paste the following code in your www/js/index.js. Remember to add cordova.plugins.diagnostic as we will be requesting the app permissions to the user with this package:

document.addEventListener("deviceready", onDeviceReady, false);

function onDeviceReady() {
  startPositioning();
}

const YOUR_SITUM_EMAIL = "demoaccount@situm.com";
const YOUR_SITUM_API_KEY =
  "1ff42011a71218ce887eae6d89f1ed97fce0d037a12e25ab99c82b88d85251bf";
const YOUR_BUILDING_IDENTIFIER = "7033";
const YOUR_POI_IDENTIFIER = "505824";

function startPositioning() {
  // 1. Authenticate in our SDK.
  cordova.plugins.Situm.setApiKey(YOUR_SITUM_EMAIL, YOUR_SITUM_API_KEY);

  // 2. Ask the user for permission before positioning.
  _requestPermissions(
    () => {
      // 3. Start positioning.
      // You may want to specify a buildingIdentifier to locate the user inside a specific building.
      // When positioning starts, the map will automatically draw the user's position.
      cordova.plugins.Situm.onLocationUpdate((location) => {
        console.log("EXAMPLE> location update: ", location.position);
      });
      cordova.plugins.Situm.onLocationStatus((status) => {
        console.log("EXAMPLE> location status: ", status);
      });
      cordova.plugins.Situm.onLocationError((err) => {
        // Something went wrong while trying to start positioning on the device.
        // Handle the possible errors and notify the user so he can fix them.
        console.error("EXAMPLE> location error :", err);
      });
      // Start positioning in the building specified at /src/constants.ts:
      cordova.plugins.Situm.requestLocationUpdates(
        // In case you have multiple buildings that the user could visit,
        // you might want to start positioning in all your buildings using global mode
        // by specifying an empty identifier.
        // Visit https://situm.com/docs/sdk-cartography/ to learn how to obtain your identifier.
        { buildingIdentifier: YOUR_BUILDING_IDENTIFIER }
      );
    },
    (errorMessage) => {
      console.error("ERR> ", JSON.stringify(errorMessage));
    }
  );

  // 4. Send actions to our viewer and handle events happening inside it.
  cordova.plugins.MapView.onLoad((controller) => {
    // MapView was loaded correctly,
    // now you can use our controller to manage our visual component.

    controller.selectPoi(YOUR_POI_IDENTIFIER);
    // In this case we are selecting some POI of a building.
    // You can find out what identifier has a certain POI of your building
    // by previously retrieving them with cordova.plugins.Situm.fetchIndoorPOIsFromBuilding(),
    // learn to use this method in our documentation (https://developers.situm.com/sdk_documentation/cordova/jsdoc/latest/situm#.fetchIndoorPOIsFromBuilding)
  });
}

function _requestPermissions(successCb, errorCb) {
  var isAndroid =
    navigator.userAgent.match(/Android/i) &&
    navigator.userAgent.match(/Android/i).length > 0;
  var isIOS = /iPhone|iPad|iPod/i.test(navigator.userAgent);

  if (isAndroid) {
    cordova.plugins.diagnostic.requestRuntimePermissions(
      function (permissions) {
        console.log("EXAMPLE> permissions statuses: ", permissions);
        successCb();
      },
      function (error) {
        errorCb(JSON.stringify(error));
      },
      [
        cordova.plugins.diagnostic.permission.ACCESS_FINE_LOCATION,
        cordova.plugins.diagnostic.permission.BLUETOOTH_CONNECT,
        cordova.plugins.diagnostic.permission.BLUETOOTH_SCAN,
      ]
    );
  } else if (isIOS) {
    cordova.plugins.diagnostic.getLocationAuthorizationStatus(
      (status) => {
        if (status == "authorized") {
          successCb();
        }
      },
      () => {
        // Do nothing
      }
    );

    cordova.plugins.diagnostic.requestLocationAuthorization(
      function (status) {
        switch (status) {
          case cordova.plugins.diagnostic.permissionStatus.NOT_REQUESTED:
            errorCb("Permission not requested");
            break;
          case cordova.plugins.diagnostic.permissionStatus.DENIED_ALWAYS:
            errorCb("Permission denied");
            break;
          case cordova.plugins.diagnostic.permissionStatus.GRANTED:
            console.log("Permission granted always");
            successCb();
            break;
          case cordova.plugins.diagnostic.permissionStatus.GRANTED_WHEN_IN_USE:
            console.log("Permission granted only when in use");
            successCb();
            break;
        }
      },
      function (error) {
        errorCb(JSON.stringify(error));
      },
      cordova.plugins.diagnostic.locationAuthorizationMode.ALWAYS
    );
  }
}

Running the application #

#Android
cordova run android
#iOS
cordova run ios

If your followed step by step this guide your app should be asking for the permissions needed right after launching, and then start positioning in the building specified and painting positions in the map. You might face common configuration issues, so troubleshoot them by checking the logs with the web inspector.

Also make sure you have calibrated correctly your building to be able to draw indoor positions in the map view.