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 for Android, iOS and Cocoapods.

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.

Alternative 1: With Cordova CLI from npm or Github #

You may install the plugin using Cordova CLI

#From npm
cordova plugin add situm-cordova-plugin-official

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

Alternative 2: Automatic installation using config.xml #

You may also define the plugin in your config.xml

<plugin name="situm-cordova-plugin-official" source="npm">
</plugin>

Using the plugin #

There are many things you can do with the Situm SDK Cordova Plugin. In this guide, we will show you how to do the basic stuff. For more info, take a look at our Cordova sample app and at the Plugin Method Reference.

Initializing the plugin #

Situm Cordova Plugin initializes automatically. When the “device ready” event is fired, the Situm Cordova Plugin will be autowired in the variable cordova.plugins.Situm.

Setting the credentials #

Then, you can setup your credentials. If you choose APIKEY based authentication, you may retrieve your APIKEY from your Profile.

#APIKEY based authentication
cordova.plugins.setApiKey("SITUM_EMAIL", "SITUM_API_KEY")

#User-Password based authentication
cordova.plugins.setUserPass("SITUM_EMAIL", "SITUM_PASS")

Starting positioning #

Then, you may start positioning by using the cordova.plugins.startPositioning method. You may pass a locationOptions object in order to modify the default positioning parameters.

cordova.plugins.Situm.startPositioning(locationOptions, (res: any) => {
   //Receives position as a result ...
   let position = res 
}, (err: any) => {
   // ... or it may also produce an error if positioning can not be started
   console.log('Error when starting positioning.', err);
});

Running the application #

Assuming you use ionic (you may use other frameworks as well):

#Android
ionic cordova run android

#iOS
ionic cordova run ios