Locate API: Geolocation

The location coordinates of the device can be set as a JavaScript array by the app, either when the page is loaded or on request. Once defined, the array contains key-value pairs for latitude, longitude, accuracy, and a timestamp of when the reading was taken.

If the app is set to Check Location Coordinates = Continuously & On Javascript API Request, it will pull location data from the device once a minute and compares it to the previous location data. If a change in location is detected, Kiosk Pro supports a special callback to notify your page of that change.

Functions

Callbacks

App-Defined Variables

Related Settings

Requirements

  • Access JavaScript API
    • By Import - recommended, works both online & offline, requires inclusion of kiosk_functions.js prior to any of the following calls.
    • By Injection - only works offline, may not be available 'onload' event.
  • Check Location Coordinates
    • On JavaScript API Request Only - requests location data using the kp_Geolocation_requestLocation function.
    • On App Launch & On JavaScript API Request - for a stationary kiosk, defining these variables once when the app is launched may be sufficient and will help prevent battery drain from regular location monitoring.
    • Continuously & On JavaScript API Request - queries once a minute for new location data.
  • Permission to access Location Services
    • Location Services can be turned on in iOS Settings > Privacy > Location Services. Once this setting is enabled, a special system alert will pop-up immediately after launching the app asking for permission to access Location Services. You must grant this permission for the app to be able to access and return location data.

Sample Code

This sample code relies on the JavaScript APIs built into Kiosk Pro and will not run successfully in other browsers or within our in-app help interface.  
To run sample code, set the app's homepage to http://www.kioskproapp.com/geolocation

Download Sample Code


kp_Geolocation_requestLocation

Added in version 9.2

This function allows access to detailed location data for the device on demand.  

Format
kp_Geolocation_requestLocation(callback);
		
Parameters
  • callback = [string] name of callback function which will be called with the following signature: callback(error, location).
Callback format
callback(error, location);
		
Callback return values
  • error = if defined, the function was unable to successfully access location services and return a location. Formatted as an associative array of key-value pairs with the following keys:
    • domain
    • code
    • description
    • failureReason
    • recoverySuggestion
    • debugDescription
  • location = if defined, the function successfully returned a location. Formatted as an associative array of key-value pairs with the following keys:
    • latitude = latitude, measured in degrees. Positive values indicate latitudes north of the equator. Negative values indicate latitudes south of the equator.
    • longitude = longitude, measured in degrees. Measurements are relative to the zero meridian, with positive values extending east of the meridian and negative values extending west of the meridian.
    • altitude = altitude, measured in meters. Positive values indicate altitudes above sea level. Negative values indicate altitudes below sea level.
    • horizontalAccuracy = radius of uncertainty for the location, measured in meters. The location’s latitude and longitude identify the center of the circle, and this value indicates the radius of that circle. A negative value indicates that the latitude and longitude are invalid.
    • verticalAccuracy = accuracy of the altitude value, measured in meters. When this property contains 0 or a positive number, the value in the altitude property is plus or minus the specified number of meters. When this property contains a negative number, the value in the altitude property is invalid. Determining the vertical accuracy requires a device with GPS capabilities. Thus, on some devices, this property always contains a negative value.
    • speed = speed of the location in m/s. Negative if speed is invalid.
    • course = course of the location in degrees true North. Negative if course is invalid. Range: 0.0 - 359.9 degrees, 0 being true North.
    • timestamp = the time at which this location check occurred.
    • accuracy = equivalent of "horizontalAccuracy". Included for backward compatibility.


kp_LocationTracker_locationDidUpdate

This callback is triggered by the app when new location coordinates are detected. Since this detection is based on new location data, 'Define Location Coordinates' must be set to 'Continuously'.  As 'Continuously' only triggers new location checks once a minute to preserve battery life, in use cases requiring more frequent location data, it is recommended to use kp_Geolocation_requestLocation above. 

Format
kp_LocationTracker_locationDidUpdate(callback);
		
Parameters callback = callback name as a string.

Status

Returns no specific value, but can be used to trigger other events based on the location of the device changing. This is done by defining this callback function in your code and placing a call within it.

For example, this call is used in the Location API code sample referenced above to update the page with new coordinates when a change in location is detected.


kioskpro_location

This associative array returns key-value pairs defining the coordinates, accuracy, and timestamp of the most recent location check.

Format
window.kioskpro_location[value];
		
Return Values
  • latitude = the latitude in degrees. Positive values indicate latitudes north of the equator. Negative values indicate latitudes south of the equator.
  • longitude = the longitude in degrees. Measurements are relative to the zero meridian, with positive values extending east of the meridian and negative values extending west of the meridian.
  • accuracy = the radius of uncertainty for the location, measured in meters.
  • timestamp = the time at which this location check occurred.

Example

To return an alert containing the timestamp of the last location check, you could call:

function alertLocationTimestamp() {
	var timestamp = window.kioskpro_location['timestamp'];
	alert(timestamp);
}

Still stuck? How can we help? How can we help?