Geolocation.watchPosition()

The Geolocation method watchPosition() method is used to register a handler function that will be called automatically each time the position of the device changes. You can also, optionally, specify an error handling callback function.

This method returns a watch ID value that then can be used to unregister the handler by passing it to the Geolocation.clearWatch() method.

Syntax

var id = navigator.geolocation.watchPosition(success[, error[, options]])

Parameters

• success A callback function that takes a Position object as an input parameter.
• error Optional An optional callback function that takes a PositionError object as an input parameter.
• options Optional An optional PositionOptions object that provides configuration options for the location watch.

Return value

An integer ID that identifies the registered handler. The ID can be passed to the Geolocation.clearWatch() to unregister the handler.

Example

var id, target, options;

function success(pos) {

var crd = pos.coords;

if (target.latitude === crd.latitude && target.longitude === crd.longitude) {

console.log('Congratulations, you reached the target');

navigator.geolocation.clearWatch(id);

}

}

function error(err) {

console.warn('ERROR(' + err.code + '): ' + err.message);

}

target = {

latitude : 0,

longitude: 0

};

options = {

enableHighAccuracy: false,

timeout: 5000,

maximumAge: 0

};

id = navigator.geolocation.watchPosition(success, error, options);

By default, KaiOS 2.5.x only allows watching positioning update when the app stays in the foreground. For reducing power consumption, the system would pause the positioning when it's put into the background. When the app is backed to the foreground, the system automatically resumes positioning.

If your application want to keep the positioning service running even when it's in the background, please request a gps wakelock before calling watchPosition() or getCurrentPosition().

// Hold a gps wakelock if your application want getting position updates while it's in the background.

// The function returns a 'lock' variable that can be accessed later to unlock wakelock.

var lock = navigator.requestWakeLock('gps');

// Release the gps wakelock when the backgroud positioning is not needed.

lock.unlock();