kony.location Namespace

---

Using the getCurrentPostion function, you can get the current location of the device.

Syntax

kony.location.getCurrentPosition(
    successcallback,
    errorcallback,
    positionoptions)

Parameters

successcallback [Function] - Mandatory

The successcallback function specifies the callback function that must be executed when the API call is successful. The signature of the callback function is successcallback(position) where, position contains the coordinates of the geo-location that are created and returned by the API. It is an object that contains certain key-value pairs.

coords [Object] - Coordinates that has the following key-value pairs:

key	Description
latitude [Number]	Latitude in decimal degrees.
longitude [Number]	Longitude in decimal degrees.
altitude [Number]	Height of the location in meters above the ellipsoid.
accuracy [Number]	Accuracy level of the latitude and longitude coordinates in meters.
altitudeaccuracy [Number]	Accuracy level of the altitude coordinate in meters.
heading [Number]	Direction of travel, specified in degrees counting clockwise relative to the true north.
speeding [Number]	Current ground speed of the device, specified in meters per second.
timestamp [Number]	Represents the time when the Position object was acquired.

 

errorcallback [Function] - Optional

The errorcallback function specifies the callback function that must be executed when the API call fails. The callback function has the following signature:

errorcallback(positionerror)- positionerror is an object that has the following key-value pairs:

key	Description
code [Number]	error code.
message [String]	error message.

For more information on the Error codes and messages, refer error code.

positionoptions [Object] - Optional

Using the positionoptions parameter, the user can customize the retrieval of the geolocation. It is an object that has the following key-value pairs:

key	Description
enableHighAccuracy [Boolean]	Provides a hint to the implementation in order to receive the best possible result.
timeout [Number]	Denotes the maximum length of time in milliseconds that is allowed to pass from the call.
maximumAge [Number]	Indicates the application to accept a cached position whose age is no greater than the specified time in milliseconds.
minimumTime [Number]	Indicates the desired interval for active location updates in milliseconds. Note: This property is only available on the Android platform.
requireBackgroundAccess [Boolean]	Set to true to fetch location updates even when the app is running in the background on Android devices. In apps that use TargetSDK version 29 (and later), you must add the ACCESS_BACKGROUND_LOCATION permission in the Android Manifest file to get location updates in the background. This property is only available on the Android platform. Important: This parameter has been introduced in the Kony Visualizer V8 Service Pack 4 Fixpack 98 release, to support scoped storage that has been added as part of the Android TargetSDK Level 29 enhancements.
useBestProvider	Set to true to improve the reliability of calls to this function on Android devices. Omitting this option on Android could cause calls to this function to have intermittent timeouts.

 

Example

/******************************************************************
 *	Name   : getCurrentPosition function
 *	Author  : Kony
 *	Purpose : This function helps to get the current location
 *******************************************************************/
function getPosition() {
    var positionoptions = {
        timeout: 15000
    }; // 15 secs 
    kony.location.getCurrentPosition(successcallback, errorcallback, positionoptions);
}

// Callback that is executed on success of getCurrentPosition function.
function successcallback(position) {
    var geoPosition = "Latitude: " + position.coords.latitude;
    geoPosition = geoPosition + " Longitude: " + position.coords.longitude;
    geoPosition = geoPosition + " Altitude: " + position.coords.altitude;
    geoPosition = geoPosition + " Accuracy: " + position.coords.accuracy;
    geoPosition = geoPosition + " Altitude Accuracy: " + position.coords.altitudeAccuracy;
    geoPosition = geoPosition + " Heading: " + position.coords.heading;
    geoPosition = geoPosition + " Speeding: " + position.coords.speeding;
    geoPosition = geoPosition + " Timestamp: " + position.timestamp;
    alert(geoPosition);
}

// Callback that is executed on error of getCurrentPosition function.
function errorcallback(positionerror) {
    var errorMesg = "Error code: " + positionerror.code;
    errorMesg = errorMesg + " message: " + positionerror.message;
    alert(errorMesg);
}

MVC Example

currentPositionSuccessCallback: function(position) {
    /* 
  //  position object will have the below properties .
         latitude = position.coords.latitude 
         longitude = position.coords.longitude
         altitude = position.coords.altitude
         atitudeAccuracy = position.coords.altitudeAccuracy
         heading = position.coords.heading
         speeding = position.coords.speeding
         timestamp = position.timestamp
    */
    alert(JSON.stringify(position));
    /* use the position depending on the use case ,some of the use cases are listed below .    
	1. Get the nearby events(like ATMs, Restaurants …etc.)  based on the user current location
	2. In a tracking-based scenario ,use as an initial position of the user .
	*/

},
currentPositionFailureCallback: function(error) {
    alert(JSON.stringify(error));
},
getCurrentPositionOfDevice: function() {
    var options = {};
    options.enableHighAccuracy = true; //  uses provider that gets accurate location
    options.timeout = 10000; // timeout in milliseconds
    options.requireBackgroundAccess  = true; // gets the location updates in the background as well
    kony.location.getCurrentPosition(this.currentPositionSuccessCallback, this.currentPositionFailureCallback, options);
}

/* Please see example of getCurrentPosition() in "frmTrackingUserLocation" Form of sample app*/

Free form Example

function currentPositionSuccessCallback(position) {
  /* 
	// position object will have the below properties .
   	latitute = position.coords.latitude
    longitude = position.coords.longitude
    altitude = position.coords.altitude
    atitudeAccuracy = position.coords.altitudeAccuracy
    heading = position.coords.heading
    speeding = position.coords.speeding
    timestamp = position.timestamp
	*/
  alert(JSON.stringify(position));
  /* use the position depending on the use case ,some of the use cases are listed below .    
	1. Get the nearby events(like ATMs, Restaurants …etc.)  based on the user current location
	2. In a tracking-based scenario ,use as an initial position of the user .
	*/

}

function currentPositionFailureCallback(error) {
  alert(JSON.stringify(error));
}

function getCurrentPositionOfDevice () {
  var options = {};
  options.enableHighAccuracy = true; 
  options.timeout = 10000; // timeout in milli seconds    
  options.requireBackgroundAccess  = true; // gets the location updates in the background as well
  kony.location.getCurrentPosition(currentPositionSuccessCallback, currentPositionFailureCallback, options);
}

Return Values

None

Exceptions

LocationError

Error Code

Error Code	Description
1	PERMISSION_DENIED
2	POSITION_UNAVAILABLE
3	TIMEOUT

Android-specific Error Codes

Error Code	Error Message	Description
4	Missing android.permission.ACCESS_BACKGROUND_LOCATION permission in AndroidManifest.xml	The developer has missed adding the android.permission.ACCESS_BACKGROUND_LOCATION permission in the AndroidManifest.xml
5	BACKGROUND_PERMISSION_DENIED	The end-user has selected ”Allow only while the app is in use" instead of “Allow all the time” option on devices that run on Android 9 (and later).
6	Permission Denied for <PermissionName> with Don't Ask Again	The user has denied permission with the Don't ask again or Never ask again option.

Remarks

This API takes up to three arguments. When invoked, the API returns and asynchronously attempts to obtain the current location of the device. The app on which this API is used must contain runtime permission from the end-user to obtain the current location of the device. If the API is invoked without obtaining the permission, device native platforms automatically display a system permission dialog box with Allow and Deny options. The end-user can grant permission to get the current location.

In Android apps that use TargetSDK version 29 (and later), and the requireBackgroundAccess property is enabled, you must manually add the ACCESS_BACKGROUND_LOCATION permission in the Android Manifest file to get location updates in the background.

If the end-user taps the Allow option, the attempt is successful, the successCallback is invoked (i.e. the handleEvent operation must be called on the callback object) with a new Position object, reflecting the current location of the device. If the attempt fails, the errorCallback is invoked with a new PositionError object, reflecting the reason for the failure. This is applicable only for Android and iOS platforms.

If the end-user taps the Deny option, the errorcallback is invoked with the PERMISSON_DENIED error code and error message.

Note: Runtime permissions are applicable only on iOS and Android platforms

Platform Availability

Available on all platforms except prior to IE8 releases.

---

Remarks

This API takes up to three arguments. When invoked, the API returns and asynchronously attempts to obtain the current location of the device. The app on which this API is used must contain runtime permission from the end-user to obtain the current location of the device. If the API is invoked without obtaining the permission, device native platforms automatically display a system permission dialog box with Allow and Deny options. The end-user can grant permission to get the current location.

In Android apps that use TargetSDK version 29 (and later), and the requireBackgroundAccess property is enabled, you must manually add the ACCESS_BACKGROUND_LOCATION permission in the Android Manifest file to get location updates in the background.

If the end-user taps the Allow option, the attempt is successful, the successCallback is invoked (i.e. the handleEvent operation must be called on the callback object) with a new Position object, reflecting the current location of the device. If the attempt fails, the errorCallback is invoked with a new PositionError object, reflecting the reason for the failure. This is applicable only for Android and iOS platforms.

If the end-user taps the Deny option, the errorcallback is invoked with the PERMISSON_DENIED error code and error message.

Note: Runtime permissions are applicable only on iOS and Android platforms

Platform Availability

Available on all platforms except Windows 7 Kiosk and prior to IE8 releases.

---

---

Using the watchPosition function, you can set callbacks that report the device's position.

Syntax

kony.location.watchPosition(
    successcallback,
    errorcallback,
    positionoptions)

Parameters

successcallback [Function] - Mandatory

The successcallback function specifies the callback function that must be executed when the API call is successful. The signature of the callback function is successcallback(position) where, position contains the coordinates of the geo-location that are created and returned by the API. It is an object that contains certain key-value pairs.

coords [Object] - Coordinates that has the following key-value pairs:

key	Description
latitude [Number]	Latitude in decimal degrees.
longitude [Number]	Longitude in decimal degrees.
altitude [Number]	Height of the location in meters above the ellipsoid.
accuracy [Number]	Accuracy level of the latitude and longitude coordinates in meters.
altitudeaccuracy [Number]	Accuracy level of the altitude coordinate in meters.
heading [Number]	Direction of travel, specified in degrees counting clockwise relative to the true north.
speeding [Number]	Current ground speed of the device, specified in meters per second.
timestamp [Number]	Represents the time when the Position object was acquired.

 

errorcallback [Function] - Optional

The errorcallback function specifies the callback function that must be executed when the API call fails. The callback function has the following signature:

errorcallback(positionerror)- positionerror is an object that has the following key-value pairs:

key	Description
code [Number]	error code.
message [String]	error message.

For more information on the Error codes and messages, refer error code.

positionoptions [Object] - Optional

Using the positionoptions parameter, the user can customize the retrieval of the geolocation. It is an object that has the following key-value pairs:

key	Description
enableHighAccuracy [Boolean]	Provides a hint to the implementation in order to receive the best possible result.
fastestInterval [Number]	Sets the fastest interval for location updates in milliseconds. The fastestInterval key controls the rate at which your application will receive location updates, which might be faster than minimumTime in some cases. This happens when other apps fetch location updates and the current app receives them passively to save power. Note: This property is only available on the Android platform. The rate at which the app receives the fastest update will not be less than the value specified for the fastestInterval property. The value for the fastestInterval must be more than zero and less than the value of minimumTime (i.e, 0 < fastestInterval <= minimumTime). If you do not set the value for fastestInterval, the value of minimumTime is set, by default. Note: Ensure that you have enabled the Use Google Play Location Services checkbox in the Project Settings > Native > Android section of Kony Visualizer.
timeout [Number]	Denotes the maximum length of time in milliseconds that is allowed to pass from the call.
maximumAge [Number]	Indicates the application to accept a cached position whose age is no greater than the specified time in milliseconds.
minimumDistance [Number]	Minimum distance in meters between location updates.
minimumTime [Number]	Minimum time in milliseconds between location updates.
requireBackgroundAccess [Boolean]	Set to true to fetch location updates even when the app is running in the background on Android devices. In apps that use TargetSDK version 29 (and later), you must add the ACCESS_BACKGROUND_LOCATION permission in the Android Manifest file to get location updates in the background. This property is only available on the Android platform. Important: This parameter has been introduced in the Kony Visualizer V8 Service Pack 4 Fixpack 98 release, to support scoped storage that has been added as part of the Android TargetSDK Level 29 enhancements.

 

Return Values

Return Value	Description
watchID [Number]	Returns a number that denotes the unique ID of the watch operation.

 

Example

function successcallback1(position) {
    lblTest.text = "working with watchPosition success full call back";
    var geoPosition = "Latitude: " + position.coords.latitude;
    geoPosition = geoPosition + " Longitude: " + position.coords.longitude;
    geoPosition = geoPosition + " Altitude: " + position.coords.altitude;
    geoPosition = geoPosition + " Accuracy: " + position.coords.accuracy;
    geoPosition = geoPosition + " Altitude Accuracy: " + position.coords.altitudeAccuracy;
    geoPosition = geoPosition + " Heading: " + position.coords.heading;
    geoPosition = geoPosition + " Speeding: " + position.coords.speeding;
    geoPosition = geoPosition + " Timestamp: " + position.timestamp;
    alert(geoPosition);
}

function errorcallback1(positionerror) {
    lblTest.text = "working with watchPosition err call back";
    var errorMesg = "Error code: " + positionerror.code;
    errorMesg = errorMesg + " message: " + positionerror.message;
    alert(errorMesg);
}
var positionoptions = {
    maximumAge: 3000,
    minimumDistance: 5,
    minimumTime: 5000
};
watchID = kony.location.watchPosition(successcallback1, errorcallback1, positionoptions);

MVC Example

watchID: null,
  watchPositionSuccessCallback: function(position) {
    /* 
    // position object will have the below properties .
      	latitute = position.coords.latitude
       longitude = position.coords.longitude
       altitude = position.coords.altitude
       atitudeAccuracy = position.coords.altitudeAccuracy
       heading = position.coords.heading
       speeding = position.coords.speeding
       timestamp = position.timestamp
     */
    alert(JSON.stringify(position));
  },
  watchPositionFailureCallback: function(error) {
    alert(JSON.stringify(error));
  },
  watchPositionOfDevice: function() {
    var self = this;
    var options = {};
    options.maximumAge = 1000;
    options.minimumTime = 2000; // time in milli seconds
    options.minimumDistance = 2; // distance in meters 
    options.requireBackgroundAccess  = true; // gets the location updates in the background as well
    this.watchID = kony.location.watchPosition(this.watchPositionSuccessCallback,this.watchPositionFailureCallback, options);
    /* Use-Cases:
	In tracking-based scenarios, the watchPosition() API can be used to 
    monitor a position
	*/
	
	/*Please see example of watchPosition() in "frmTrackingUserLocation" Form of sample app*/
  }
  

Free Form Example

watchID = null;

function watchPositionSuccessCallback(position) {
    /* 
        // position object will have the below properties .
       latitute = position.coords.latitude
       longitude = position.coords.longitude
       altitude = position.coords.altitude
       atitudeAccuracy = position.coords.altitudeAccuracy
       heading = position.coords.heading
       speeding = position.coords.speeding
       timestamp = position.timestamp
       */

    alert(JSON.stringify(position));
}

function watchPositionFailureCallback(error) {
    alert(JSON.stringify(error));
}

function watchPositionOfDevice() {
    var self = this;
    var options = {};
    options.maximumAge = 1000; // use cached position if exists in mentioned time(in milliseconds)
    options.minimumTime = 2000; // time criteria for location updates
    options.minimumDistance = 2; // distance criteria for location updates 
    options.requireBackgroundAccess  = true; // gets the location updates in the background as well
    watchID = kony.location.watchPosition(watchPositionSuccessCallback, watchPositionFailureCallback, options);
}

Exceptions

LocationError

Error Code

Error Code	Description
1	PERMISSION_DENIED
2	POSITION_UNAVAILABLE
3	TIMEOUT

 

Remarks

Android-specific Error Codes

Error Code	Error Message	Description
4	Missing android.permission.ACCESS_BACKGROUND_LOCATION permission in AndroidManifest.xml	The developer has missed adding the android.permission.ACCESS_BACKGROUND_LOCATION permission in the AndroidManifest.xml
5	BACKGROUND_PERMISSION_DENIED	The end-user has selected ”Allow only while the app is in use" instead of “Allow all the time” option on devices that run on Android 9 (and later).
6	Permission Denied for <PermissionName> with Don't Ask Again	The user has denied permission with the Don't ask again or Never ask again option.

Remarks

The behavior of this function depends on the underlying hardware platform. For example, if your app is running on Android and you set minimumTime and minimumDistance to their minimum possible values, the callback function in the successcallback parameter will not be called, as per the Android documentation.

This API takes one, two, or three arguments. When invoked, it must immediately return a number that uniquely identifies a watch operation and then asynchronously start the watch operation. This operation first attempts to obtain the current location of the device. Your app needs runtime permission from the end-user to obtain the current location of the device. If you call the API without obtaining the permission, platforms automatically pops up a system permission dialog box with Allow and Deny options, asking the end-user to grant permission to get the current location.

In Android apps that use TargetSDK version 29 (and later), and the requireBackgroundAccess property is enabled, you must manually add the ACCESS_BACKGROUND_LOCATION permission in the Android Manifest file to get location updates in the background.

If the end-user taps the Allow option, the attempt is successful, the succesCallback is invoked (i.e. the handleEvent operation must be called on the callback object) with a new Position object, reflecting the current location of the device. If the attempt fails, the errorCallback is invoked with a new PositionError object, reflecting the reason for the failure.

If the end-user taps the Deny option, the errorcallback in invoked with the PERMISSON_DENIED error code and error message.

Note: The runtime permissions are applicable only in the iOS and Android platforms.

The watch operation continues to monitor the position of the device and invokes the appropriate callback every time this position changes. The watch operation continues until the clearwatch method is called with the corresponding identifier.

Platform Availability

Available on all platforms except Desktop Web, IE8 and prior to IE8 releases.

---

The behavior of this function depends on the underlying hardware platform. For example, if your app is running on Android and you set minimumTime and minimumDistance to their minimum possible values, the callback function in the successcallback parameter will not be called, as per the Android documentation.

This API takes one, two, or three arguments. When invoked, it must immediately return a number that uniquely identifies a watch operation and then asynchronously start the watch operation. This operation first attempts to obtain the current location of the device. Your app needs runtime permission from the end-user to obtain the current location of the device. If you call the API without obtaining the permission, platforms automatically pops up a system permission dialog box with Allow and Deny options, asking the end-user to grant permission to get the current location.

If the end-user taps the Allow option, the attempt is successful, the succesCallback is invoked (i.e. the handleEvent operation must be called on the callback object) with a new Position object, reflecting the current location of the device. If the attempt fails, the errorCallback is invoked with a new PositionError object, reflecting the reason for the failure.

If the end-user taps the Deny option, the errorcallback in invoked with the PERMISSON_DENIED error code and error message.

Note: The runtime permissions are applicable only in the iOS and Android platforms.

The watch operation continues to monitor the position of the device and invokes the appropriate callback every time this position changes. The watch operation continues until the clearwatch method is called with the corresponding identifier.

Platform Availability

Available on all platforms except Desktop Web, Windows 7 Kiosk, IE8 and prior to IE8 releases.

---

---

When invoked, the clearWatch first checks the value of the given watchID argument. If this value does not correspond to any previously started watch process, then the method returns immediately without performing any further action. Otherwise, the watch process identified by the watchID argument is stopped immediately and no further callbacks are invoked.

Syntax

kony.location.clearWatch(
    watchID);

Parameters

Function	Description
watchID [Number] - Mandatory	Specifies the number that uniquely identifies the watch.

Example

kony.location.clearWatch(watchID);

MVC

stopWatchingPosition: function() {
    try {
        kony.location.clearWatch(this.watchID); // clears/stops watching position of the user which was being monitored using watchPosition API
        alert("Cleared !");
    } catch (exception) {
        alert(exception);
    }

    /* Please see example of clearWatch() in "frmTrackingUserLocation" Form of sample app */
}

Free Form

function stopWatchingPosition () {
  try{
    kony.location.clearWatch(watchID); // clears/stops watching position of the user which was being monitored using watchPosition API
    alert("Cleared !");
  }catch(exception){
    alert(exception);
  }
}

Return Values

None.

Exceptions

LocationError

Error

Platform Availability

Available on all platforms except Desktop Web and Windows 7 Kiosk.

---