@situm/cordova 3.0.0

package/docs/getting-started.md

@@ -0,0 +1,298 @@
+<h1>Quick start guide</h1>
+
+<div id="guide__introduction" class="guide__section">
+<h2>Introduction</h2>
+</div>
+
+In this tutorial, we will guide you step by step to set up your first Cordova application using Cordova Situm Plugin. 
+Before starting to write code, we recommend you to set up an account on our Dashboard ([https://dashboard.situm.es](https://dashboard.situm.es)), retrieve your API KEY and configure your first building.
+
+1. Go to the [sign in form](http://dashboard.situm.es/accounts/register) and enter your username and password to sign in.
+
+2. Go to the [account section](https://dashboard.situm.es/accounts/profile) and on the bottom, click on “generate one” to generate your API KEY.
+
+3. Go to the [buildings section](http://dashboard.situm.es/buildings) and create your first building.
+
+4. Download Situm Mapping Tool in Play Store (Only Android devices) and calibrate your building. Check out our user guide for detailed information.
+
+5. You are ready to build your own Cordova applications. Please check the next steps for requirements:
+
+
+<div id="guide__pre_requisites" class="guide__section">
+<h2>Installing pre-requisites</h2>
+</div>
+
+### Configure cordova:
+
+* [Installing the Cordova CLI](https://cordova.apache.org/docs/en/latest/guide/cli/index.html#installing-the-cordova-cli)
+
+### Cordova requirements:
+
+* [Android](https://cordova.apache.org/docs/en/latest/guide/platforms/android/#installing-the-requirements)
+
+* [iOS](https://cordova.apache.org/docs/en/latest/guide/platforms/android/#installing-the-requirements)
+
+
+<div id="guide__installing_the_plugin" class="guide__section">
+<h2>Installing the plugin</h2>
+</div>
+
+We assume that you have already created a hybrid application with your favorite framework (Ionic, PhoneGap, Appcelerator, Telerik...). There are some different ways to install the plugin:
+
+### 1) Manually from npm:
+
+```bash
+$ cordova plugin add @situm/cordova
+```
+
+### 2) Defined in config.xml for automatic installation:
+
+```xml
+  <plugin name="@situm/cordova" source="npm">
+
+  </plugin>
+```
+
+### 3) With Cordova CLI utility from master (or another branch):
+
+```
+$ cordova plugin add https://github.com/situmtech/situm-cordova-plugin.git
+```
+
+<div id="guide__using_the_plugin" class="guide__section">
+<h2>Using the plugin</h2>
+</div>
+
+### Accessing plugin object
+
+When the device ready event is fired, the global cordova variable is injected into the namespace. Plugins are available in this variable: cordova.plugins. The Situm Cordova Plugin is autowired within this object.
+
+So, all methods are called in the same way, e.g. 'setApiKey':
+
+```javascript
+  cordova.plugins.Situm.setApiKey(email, apiKey);
+```
+
+<div id="guide__methods" class="guide__section">
+<h2>Methods</h2>
+</div>
+
+#### - setApiKey
+
+Allows you to log in to your Situm Account. This key is generated in Situm Dashboard. Returns true if apiKey was set successfully, otherwise false
+
+```javascript
+  setApiKey("your_email@domain.com", "YOUR_API_KEY");
+```
+
+#### - setUserPass
+
+Provides user's email and password.
+
+```javascript
+  setUserPass("email@domain.com", "yourPassword");
+````
+
+#### - setCacheMaxAge
+
+Sets the maximum age of a cached response in seconds. Some information, such as floor plans, floors, POIs, etc. is stored in the cache. After the cache expires, we will fetch this information from the server again.
+
+```javascript
+  setCacheMaxAge(200);
+```
+
+#### - startPositioning
+
+Starts the positioning on the [locationRequest](http://developers.situm.es/sdk_documentation/cordova/jsdoc/1.3.10/symbols/LocationRequest.html), a [building](http://developers.situm.es/sdk_documentation/cordova/jsdoc/1.3.10/symbols/Building.html) should be sent as the first parameter and a locationRequest should be sent as the second one. Returns a set of locationStatus and [location](http://developers.situm.es/sdk_documentation/cordova/jsdoc/1.3.10/symbols/Location.html) through the success callback.
+
+```javascript
+  startPositioning([building, locationRequest], position => {
+    // position as location object:
+  }, (error) => {
+    // If errors will come here
+  });
+```
+
+#### - stopPositioning
+
+Stops locationListener on current active listener.
+
+```javascript
+  stopPositioning(() => {
+    // Your code here
+  }, (error) => {
+    // If errors will come here
+  });
+```
+
+#### - fetchBuildings
+
+Downloads all the [buildings](http://developers.situm.es/sdk_documentation/cordova/jsdoc/1.3.10/symbols/Building.html) for the current user.
+
+```javascript
+  fetchBuildings((buildings) => {
+    // Array of buildings
+  }, (error) => {
+    // If errors will come here
+  });
+```
+
+#### - fetchFloorsFromBuilding
+
+Downloads all the [floors](http://developers.situm.es/sdk_documentation/cordova/jsdoc/1.3.10/symbols/Floor.html) of a [building](http://developers.situm.es/sdk_documentation/cordova/jsdoc/1.3.10/symbols/Building.html).
+
+```javascript
+  fetchFloorsFromBuilding(building, (floors) => {
+    // Array of floors
+  }, (error) => {
+    // If errors will come here
+  });
+```
+
+#### - fetchIndoorPOIsFromBuilding
+
+Downloads the indoor [POIs](http://developers.situm.es/sdk_documentation/cordova/jsdoc/1.3.10/symbols/Poi.html) of a [building](http://developers.situm.es/sdk_documentation/cordova/jsdoc/1.3.10/symbols/Building.html).
+
+```javascript
+  fetchIndoorPOIsFromBuilding(building, (pois) => {
+    // Array of pois
+  }, (error) => {
+    // If errors will come here
+  });
+```
+
+#### - fetchOutdoorPOIsFromBuilding
+
+Downloads the outdoor [POIs](http://developers.situm.es/sdk_documentation/cordova/jsdoc/1.3.10/symbols/Poi.html) of a [building](http://developers.situm.es/sdk_documentation/cordova/jsdoc/1.3.10/symbols/Building.html).
+
+```javascript
+  fetchOutdoorPOIsFromBuilding(building, (pois) => {
+    // Array of pois
+  }, (error) => {
+    // If errors will come here
+  });
+```
+
+#### - fetchEventsFromBuilding
+
+Downloads the events of a [building](http://developers.situm.es/sdk_documentation/cordova/jsdoc/1.3.10/symbols/Building.html).
+
+```javascript
+  fetchEventsFromBuilding(building, (events) => {
+    // Array of Situm events
+  }, (error) => {
+    // If errors will come here
+  });
+```
+
+#### - fetchPoiCategories
+
+Gets all [POI categories](http://developers.situm.es/sdk_documentation/cordova/jsdoc/1.3.10/symbols/PoiCategory.html), download and cache their icons asynchronously.
+
+```javascript
+  fetchPoiCategories((poiCategories) => {
+    // Array of POI cateogires
+  }, (error) => {
+    // If errors will come here
+  });
+```
+
+#### - fetchMapFromFloor
+
+Downloads the map image of a [floor](http://developers.situm.es/sdk_documentation/cordova/jsdoc/1.3.10/symbols/Floor.html).
+
+```javascript
+  fetchMapFromFloor (floor, (mapImage) => {
+    // Map image as a bitmap
+  }, (error) => {
+    // If errors will come here
+  });
+```
+
+#### - fetchPoiCategoryIconNormal
+
+Gets the normal category icon for a [category](http://developers.situm.es/sdk_documentation/cordova/jsdoc/1.3.10/symbols/PoiCategory.html).
+
+```javascript
+  fetchPoiCategoryIconNormal (poiCategory, (iconNormal) => {
+    // Icon as a bitmap
+  }, (error) => {
+    // If errors will come here
+  });
+```
+
+#### - fetchPoiCategoryIconSelected
+
+Gets the selected category icon for a [category](http://developers.situm.es/sdk_documentation/cordova/jsdoc/1.3.10/symbols/PoiCategory.html).
+
+```javascript
+  fetchPoiCategoryIconSelected (poiCategory, (iconSelected) => {
+    // Icon as a bitmap
+  }, (error) => {
+    // If errors will come here
+  });
+```
+
+#### - invalidateCache
+
+Invalidates all the resources in the cache.
+
+```javascript
+  invalidateCache((response) => {});
+```
+#### - requestDirections
+
+Calculates a route between two [points](http://developers.situm.es/sdk_documentation/cordova/jsdoc/1.3.10/symbols/Point.html).
+
+```javascript
+  requestDirections([building, from, to], (route) => {
+    // Route Situm object
+  }, (error) => {
+    // If errors will come here
+  });
+```
+
+#### - requestNavigationUpdates
+
+Requests navigation updates. This method should be called after `requestDirections` in order to provide navigation updates when a new position is computed.
+
+```javascript
+var navigationOptions = new Object();
+  navigationOptions.distanceToFloorChangeThreshold = 0; // number in meters
+  navigationOptions.distanceToChangeIndicationThreshold = 0; // number in meters
+  navigationOptions.distanceToGoalThreshold = 0; // number in meters
+  navigationOptions.outsideRouteThreshold = 0; // number in meters
+  navigationOptions.indicationsInterval = 0; // number in millis
+  navigationOptions.timeToFirstIndication = 0; // number in millis
+  navigationOptions.roundIndicationsStep = 0; // number in meters
+  navigationOptions.timeToIgnoreUnexpectedFloorChanges = 0; // number in millis
+  requestNavigationUpdates([navigationOptions], (res: any) => {
+    // Progress and other navigation status messages can be processed here  
+  }, (error: any) => {
+    // If errors will come here 
+  });
+```
+
+#### - updateNavigationWithLocation
+
+Updates navigation progress with a location, which would usually be provided by the [`startPositioning`](#--startpositioning) method. Returns progress and other navigation status messages. This method should be called after `requestNavigationUpdates`.
+
+```javascript
+  updateNavigationWithLocation([position], (result) => {
+    // Result
+  }, (error) => {
+    // If errors will come here
+  });
+```
+
+#### - removeNavigationUpdates
+
+Removes all location updates. This removes the internal state of the manager, including the listener provided in `requestNavigationUpdates`,so it won't receive more progress updates.
+
+```javascript
+  removeNavigationUpdates();
+```
+
+## License
+
+Situm-Cordova-Plugin is licensed under [MIT License](https://opensource.org/licenses/MIT)

package/docs/static/styles/custom.css

@@ -0,0 +1,23 @@
+footer {
+    background-color: rgb(0,161,223);
+}
+
+footer > img {
+    display: none !important;
+}
+
+.main section article table td.name, .main section article table td.type, .main section article table td.attributes, .main section article table td.default {
+    max-width: 300px;
+}
+
+.lnb h3 {
+    color: rgb(0,161,223);
+}
+
+.main section article h3.subsection-title {
+    color: rgb(0,161,223);
+}
+
+#resizer {
+    background-color: rgb(0,161,223);
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@situm/cordova",
+  "version": "3.0.0",
+  "description": "Set of utilities that allow any developer to build Cordova location based apps using Situm's indoor positioning system.",
+  "private": false,
+  "repository": "https://github.com/situmtech/cordova",
+  "author": "Situm Technologies <mobile@situm.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/situmtech/cordova/issues"
+  },
+  "homepage": "https://github.com/situmtech/cordova#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "cordova": {
+    "id": "@situm/cordova",
+    "platforms": [
+      "android",
+      "ios"
+    ]
+  },
+  "keywords": [
+    "situm",
+    "indoor positioning",
+    "ecosystem:cordova",
+    "cordova-android",
+    "cordova-ios"
+  ],
+  "engines": [
+    {
+      "name": "cordova-android",
+      "version": ">=6.0.0"
+    }
+  ],
+  "dependencies": {
+    "cordova-common": "^2.2.5",
+    "describe": "^1.2.0",
+    "q": "^1.5.1",
+    "tui-jsdoc-template": "^1.2.2"
+  },
+  "scripts": {
+    "test": "cd tests/js && mocha",
+    "eslint": "node node_modules/eslint/bin/eslint www && node node_modules/eslint/bin/eslint src && node node_modules/eslint/bin/eslint tests",
+    "jsdoc": "rm -rf docs/JSDoc && ./node_modules/.bin/jsdoc www/android/situm.js www/android/Interfaces.js www/map-view.js www/map-view-controller.js -c ./docs/conf.json -d docs/JSDoc"
+  },
+  "devDependencies": {
+    "eslint": "^5.3.0",
+    "eslint-config-semistandard": "^11.0.0",
+    "eslint-config-standard": "^10.2.1",
+    "eslint-plugin-import": "^2.3.0",
+    "eslint-plugin-node": "^5.0.0",
+    "eslint-plugin-promise": "^3.5.0",
+    "eslint-plugin-standard": "^3.0.1",
+    "jsdoc": "^3.5.5",
+    "mocha": "^5.2.0",
+    "expect.js": "^0.3.1",
+    "jsdoc-toolkit": "0.0.2"
+  }
+}

package/plugin.xml

@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
+    id="@situm/cordova"
+    version="3.0.0">
+    <name>Situm Cordova plugin Official</name>
+    <description>This is the stable branch.</description>
+    <license>MIT</license>
+    <keywords>situm, indoor positioning</keywords>
+    <repo>https://github.com/situmtech/situm-cordova-plugin.git</repo>
+    <issue>https://github.com/situmtech/situm-cordova-plugin/issues</issue>
+
+    <engines>
+        <engine name="cordova-android" version=">=10.0.0" />
+    </engines>
+
+    <js-module src="www/map-view.js" name="map-view">
+        <runs/>
+        <clobbers target="cordova.plugins.MapView" />
+    </js-module>
+
+    <js-module src="www/map-view-controller.js" name="map-view-controller">
+        <runs/>
+        <clobbers target="cordova.plugins.MapViewController" />
+    </js-module>
+
+    <!-- android -->
+    <platform name="android">
+        <js-module src="www/android/situm.js" name="situm">
+            <runs/>
+            <clobbers target="cordova.plugins.Situm" />
+        </js-module>
+
+        <framework src="src/android/situm.gradle" custom="true" type="gradleReference" />
+
+        <config-file target="res/xml/config.xml" parent="/*">
+            <feature name="Situm">
+            <param name="android-package" value="es.situm.plugin.SitumPlugin" />
+            <param name="onload" value="true" />
+            </feature>
+       </config-file>
+
+        <source-file src="src/android/app/src/main/java/es/situm/plugin/SitumPlugin.java" target-dir="src/es/situm/plugin" />
+        <source-file src="src/android/app/src/main/java/es/situm/plugin/PluginHelper.java" target-dir="src/es/situm/plugin" />
+        <source-file src="src/android/app/src/main/java/es/situm/plugin/SitumMapper.java" target-dir="src/es/situm/plugin" />
+        <source-file src="src/android/app/src/main/java/es/situm/plugin/DateUtils.java" target-dir="src/es/situm/plugin" />
+
+    </platform>
+
+    <!-- ios -->
+    <platform name="ios">
+        <js-module src="www/ios/situm.js" name="situm">
+            <runs/>
+            <clobbers target="cordova.plugins.Situm" />
+        </js-module>
+        <config-file target="config.xml" parent="/*">
+	    <feature name="SitumPlugin">
+                <param name="ios-package" value="SitumPlugin" onload="true" />
+            </feature>
+        </config-file>
+
+        <config-file target="*-Info.plist" parent="NSLocationAlwaysUsageDescription">
+		        <string>Location is required to find out where you are</string>
+    		</config-file>
+    		<config-file target="*-Info.plist" parent="NSLocationWhenInUseUsageDescription">
+    			   <string>Location is required to find out where you are</string>
+    		</config-file>
+    		<config-file target="*-Info.plist" parent="NSLocationUsageDescription">
+    			   <string>Location is required to find out where you are</string>
+    		</config-file>
+
+        <framework src="CFNetwork.framework" />
+        <framework src="CoreData.framework" />
+        <framework src="UIKit.framework" />
+        <framework src="CoreLocation.framework" />
+        <framework src="CoreMotion.framework" />
+        <framework src="CoreBluetooth.framework" />
+        <framework src="Security.framework" />
+        <framework src="SystemConfiguration.framework"/>
+        <framework src="libz.dylib" />
+        <framework src="libc++.dylib" />
+
+        <podspec>
+            <config>
+            </config>
+            <pods use-frameworks="false">
+                <pod name="SitumSDK" spec="~> 3.3.0"/>
+            </pods>
+        </podspec>
+
+
+        <header-file src="src/ios/situmcordovaplugin/SitumPlugin.h" />
+        <header-file src="src/ios/situmcordovaplugin/SitumLocationWrapper.h" />
+        <header-file src="src/ios/situmcordovaplugin/Constants.h" />
+        <source-file src="src/ios/situmcordovaplugin/SitumPlugin.m" />
+        <source-file src="src/ios/situmcordovaplugin/SitumLocationWrapper.m" />
+        <source-file src="src/ios/situmcordovaplugin/Constants.m" />
+        <source-file src="src/ios/situmcordovaplugin/SITUtils.m" />
+        <source-file src="src/ios/situmcordovaplugin/SITUtils.h" />
+        
+    </platform>
+</plugin>

package/scripts/update_changelog.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Copy the content from CHANGELOG_UNRELEASED.md to the top of CHANGELOG.md.
+root_path=`git rev-parse --show-toplevel`
+cd $root_path
+
+if [ "$#" -ne 1 ]; then
+    echo >&2 "Error: illegal number of parameters"
+    echo "Usage: bash update_changelog.sh [RELEASE_VERSION]"
+    exit 1
+fi
+
+release_version=$1
+
+#Remove all newlines at end of file
+echo "$(awk '/^$/ {nlstack=nlstack "\n";next;} {printf "%s",nlstack; nlstack=""; print;}' CHANGELOG_UNRELEASED.md)" > CHANGELOG_UNRELEASED.md
+
+sed -i -e '/---------/a \\n' CHANGELOG.md
+sed -i -e '/---------/rCHANGELOG_UNRELEASED.md' CHANGELOG.md
+sed -i -e "/---------/a ## [$release_version] - `date +%Y-%m-%d`\\n" CHANGELOG.md > CHANGELOG_UNRELEASED.md
+
+
+git commit CHANGELOG.md CHANGELOG_UNRELEASED.md -m "Update CHANGELOG. (Commited by release script)" > /dev/null

package/src/android/app/build.gradle

@@ -0,0 +1,51 @@
+apply plugin: 'com.android.application'
+
+android {
+    compileSdkVersion 33
+    buildToolsVersion '30.0.3'
+    defaultConfig {
+        applicationId "es.plugin.situm"
+        minSdkVersion 22
+        targetSdkVersion 33
+        versionCode 1
+        versionName "1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+    testOptions {
+        unitTests.returnDefaultValues = true
+    }
+    compileOptions {
+        sourceCompatibility 1.8
+        targetCompatibility 1.8
+    }
+}
+
+dependencies {
+    implementation fileTree(include: ['*.jar'], dir: 'libs')
+
+    // Core library
+    androidTestImplementation 'androidx.test:core:1.4.0'
+    androidTestImplementation 'androidx.test:runner:1.4.0'
+    androidTestImplementation 'androidx.test.espresso:espresso-core:3.4.0'
+    androidTestImplementation 'androidx.test.espresso:espresso-web:3.4.0'
+
+    testImplementation 'junit:junit:4.12'
+    testImplementation 'org.json:json:20140107'
+    testImplementation "com.google.truth:truth:0.42"
+
+    implementation "androidx.appcompat:appcompat:1.3.1"
+
+    implementation ('com.googlecode.json-simple:json-simple:1.1.1'){
+        exclude group: 'junit', module:'junit'
+    }
+    implementation ('es.situm:situm-sdk:3.7.0@aar') {
+        transitive = true
+    }
+    implementation 'org.apache.cordova:framework:10.1.1'
+}

package/src/android/app/proguard-rules.pro

@@ -0,0 +1,21 @@
+# Add project specific ProGuard rules here.
+# You can control the set of applied configuration files using the
+# proguardFiles setting in build.gradle.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html
+
+# If your project uses WebView with JS, uncomment the following
+# and specify the fully qualified class name to the JavaScript interface
+# class:
+#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
+#   public *;
+#}
+
+# Uncomment this to preserve the line number information for
+# debugging stack traces.
+#-keepattributes SourceFile,LineNumberTable
+
+# If you keep the line number information, uncomment this to
+# hide the original source file name.
+#-renamesourcefileattribute SourceFile

package/src/android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,11 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="es.plugin.situm">
+
+    <application
+        android:allowBackup="true"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:supportsRtl="true"
+        android:theme="@style/AppTheme" />
+</manifest>

package/src/android/app/src/main/java/es/situm/plugin/DateUtils.java

@@ -0,0 +1,15 @@
+package es.situm.plugin;
+
+import java.text.DateFormat;
+import java.text.SimpleDateFormat;
+import java.util.Locale;
+import java.util.TimeZone;
+
+public class DateUtils {
+    public static final DateFormat dateFormat;
+
+    static {
+        dateFormat = new SimpleDateFormat("E MMM dd HH:mm:ss Z yyyy", Locale.US);
+        dateFormat.setTimeZone(TimeZone.getTimeZone("UTC"));
+    }
+}