Skip to main content

Geo Location (GPS) Feature

buildfire.geo#

This service lets you access users location. It helps request and watch the location of the device.

Methods#

getCurrentPosition()
#

buildfire.geo.getCurrentPosition(options, callback)

Gets the device current location

buildfire.geo.getCurrentPosition(null, (err, position) => {
if (err) return console.error(err);
console.log("Lat", position.coords.latitude);
console.log("Lng", position.coords.longitude);
});

options#

NameTypeRequiredDescriptionDefault
enableHighAccuracybooleannoProvides a hint that the application needs the best possible results. By default, the device attempts to retrieve a Position using network-based methods. Setting this property to true tells the framework to use more accurate methods, such as satellite positioning.false
timeoutnumbernoThe maximum length of time (milliseconds) that is allowed to pass from the call to getCurrentPosition until the success callback executes. If the success callback is not invoked within this time, the error callback is passed a PositionError.TIMEOUT error code.
maximumAgenumbernoAccept a cached position whose age is no greater than the specified time in milliseconds.

callback(err, position)#

Callback function after the geolocation has beed retrieved

NameTypeDescription
errstringerror string, null when operation is successfull
positionobjectRetrieved geolocation position

position#

NameTypeDescription
coordsobjectObject containing coordinates
timestampnumberLocation timestamp
isBackgroundbooleanIndicates whether location was captured in background
position.coords#
NameTypeDescription
accuracynumberLocation estimated accuracy in meters
latitudenumberLocation latitude
longitudenumberLocation longitude
altitudenumberLocation altitude
altitudeAccuracynumberAltitude accuracy
speednumberMovement speed if device is moving
headingnumberMovement direction as angle

watchPosition()
#

buildfire.geo.watchPosition(options, callback)

Allows you watch the devices location and will trigger every time a location change occurs

buildfire.geo.watchPosition({ timeout: 30000 }, (position) => {
console.log("Position changed");
console.log("New Lat", position.coords.latitude);
console.log("New Lng", position.coords.longitude);
});
tip

You can use watchPosition in combination with background service to track users position in background. Note that additional item BackgroundGeo is needed in plugin.json file.

options#

NameTypeRequiredDescriptionDefault
enableHighAccuracybooleannoProvides a hint that the application needs the best possible results. By default, the device attempts to retrieve a Position using network-based methods. Setting this property to true tells the framework to use more accurate methods, such as satellite positioning.false
timeoutnumbernoThe maximum length of time (milliseconds) that is allowed to pass from the call to geolocation.watchPosition until the corresponding success callback executes. If the success callback is not invoked within this time, the error callback is passed a PositionError.TIMEOUT error code. When used in conjunction with geolocation.watchPosition, the error callback will be called on an interval every timeout milliseconds.
maximumAgenumbernoAccept a cached position whose age is no greater than the specified time in milliseconds.

callback(position)#

Callback function triggered every time a location change occurs on device

position#

Object containing position and watchId.

NameTypeDescription
watchIdnumberRemember the watchId so that you can stop watching position later.
coordsobjectSee position.coords
timestampnumberLocation timestamp
isBackgroundbooleanIndicates whether location was captured in background

clearWatch()
#

buildfire.geo.clearWatch(watchId, callback)

Stops watching the location changes of the device

buildfire.geo.clearWatch(1, () => {
console.log("Stopped watching position");
});

watchId#

The id you were given in the callback of watchPosition

NameTypeRequiredDescriptionDefault
watchIdnumberyesThe id you were given in the callback of watchPosition

callback()#

Optional callback function that is called when the watcher is cleared