Use Geolocation Data (Fire Tablets)

Geolocation data is available to your app through JavaScript on devices that support the navigator.geolocation property. The W3C provides a Geolocation API Specification that describes how to access geolocation data.

The Geolocation sample demonstrates how to access geolocation data. The code for this sample is located in <Amazon Apps & Games Services SDKs>/Web/Cookbook/Geolocation/. The Web App SDK can be downloaded from the SDK Download page.

Detect Whether Geolocation is Supported
Request Geolocation Data for the User's Current Position
Use the Geolocation Data
Request Permission to Use Geolocation Data

Detect Whether Geolocation is Supported

To detect whether geolocation is supported, check to see whether the navigator.geolocation property is present. If it is present, geolocation is supported.

if (navigator.geolocation) {
  // geolocation is supported
} else {
  // geolocation is not supported
}

Request Geolocation Data for the User's Current Position

Once you have verified that the navigator.geolocation property is present, you can request geolocation data for the user's current position by calling navigator.geolocation.getCurrentPosition() with a minimum of one and maximum of three arguments. The arguments, in order, are:

(Required) A callback to a function that is called when the current location of the device is successfully determined.
(Optional) A callback to a function that is called when an error occurs while attempting to determine the current location of the device.
(Optional) An object encapsulating position-finding options.

The position-finding options are as follows:

enableHighAccuracy (boolean) provides a hint that the app would like to receive the best possible results. High-accuracy results may result in slower response times and/or increased power consumption. The user might deny this capability, or the device might not be able to provide results that are any more accurate than if this flag was set to false. The intent of this flag is to allow apps to inform the implementation that they do not require high-accuracy results so that the implementation can avoid using geolocation providers that consume a significant amount of power, such as GPS.
timeout (long) is the maximum number of milliseconds that can elapse between the call to getCurrentPosition() and when the corresponding success callback is invoked. If timeout milliseconds elapse and no other errors have occurred, the error callback is called with a timeout error code.
maximumAge (long) is the maximum number of milliseconds old a cached location can be and still be used. If maximumAge is set to zero, the implementation must immediately attempt to get new position data. Setting maximumAge to infinity means that cached data will always be returned, regardless of age.

Here is an example call to getCurrentPosition() with a success callback, error callback, and options object defined. The implementation of the success callback is shown in the section called Using Geolocation Data. The implementation of the error callback is not shown.

var options = {
  enableHighAccuracy: true,
  timeout: 5000,
  maximumAge: 0
};

if (navigator.geolocation) {
  navigator.geolocation.getCurrentPosition(showPositionSuccessCallback, showPositionErrorCallback, options);
} else {
  $("#location").text("Geolocation is not supported in this browser or context");
}

Use the Geolocation Data

Once you have requested geolocation data and the request is successfully processed, the success callback is called. The callback function receives a position object that contains a coordinates object and a timestamp. The coordinates object contains the following properties:

latitude specified in decimal degrees.
longitude specified in decimal degrees.
altitude is the height, in meters, of the position above the WGS84 ellipsoid. May be null if the implementation cannot provide this information.
accuracy of latitude and longitude, specified in meters with a 95% confidence level.
altitudeAccuracy specified in meters with a 95% confidence level. May be null if the implementation cannot provide altitude information.
heading is the device's direction of travel, specified in degrees such that 0° ≤ heading < 360°. May be NaN if the device is stationary (i.e., speed is 0). May be null if the implementation cannot provide heading information.
speed is the magnitude of the horizontal component of the device's current velocity, specified in meters per second. May be null if the implementation cannot provide speed information.

Here is an example success callback that uses the information in the position's coordinates object to display latitude, longitude, and accuracy information, as well as a link to a map where the latitude and longitude are embedded in the query string:

function showPositionSuccessCallback(position) {
  var latitude = position.coords.latitude;
  var longitude = position.coords.longitude;
  var accuracy = position.coords.accuracy;
  $("#location").html("Latitude: " + latitude
                      + "<br/>Longitude: " + longitude
                      + "<br/>Accuracy: " + accuracy + " meters");
  $("#osm").html('<a href="http://www.openstreetmap.org/?lat=' + latitude
                 + '&lon=' + longitude + '&zoom=17&layers=M">Open Street Maps view</a>');
}

Request Permission to Use Geolocation Data

When you submit your app to the Amazon Appstore, ensure you check the checkbox for Geolocation in the section called Web App Features on the App Information tab. This will add the appropriate permissions to the Android manifest. If you do not check the appropriate checkbox, the geolocation features of your app will not work.

Last updated: Jun 09, 2022