startWatchingPosition(options, callback)

Subscribes to asynchronous location updates for the mobile device.

This function will be retired in a future release. From feedback, we’ve determined that the limitations of the API render it unsuitable for many customer use cases. Additional Android and iOS platform constraints require us to fully reevaluate our approach. We’re exploring the possibility of replacing this API in a future release.
  • options—(Required) A LocationServiceOptions object to configure the location request.
  • callback—(Required) A function to handle location update responses.

An integer identifier for the location subscription, which you can use to end the subscription when you want to stop receiving location updates.

This function creates a subscription to significant location updates, where “significant” is determined by the operating system. See usage notes below.

Receiving location updates with startWatchingPosition() is suitable for components that remain on the screen while receiving updates. If the user puts the mobile app into the background, location tracking can, and likely will, stop shortly afterward. If the user navigates away from the page, but remains in the mobile app, your component can continue to receive location updates, but can also be deallocated by the framework.

In other words, while the user remains on the same page, position tracking works as expected. If the user leaves the page or the app, the behavior is undefined.

Your callback function will be called initially to provide the current location, similar to getCurrentPosition(). After that, it’s called whenever there’s a significant location change.

  • Retain the watchId for use in a stopWatchingPosition() call when you’re ready to stop receiving updates.
  • Your callback function receives a Location object, or a LocationServiceFailure if there’s an error.
  • There’s no specific timing for receiving position updates via your callback function. They happen when the underlying operating system location feature detects a significant change, where “significant” is influenced by a number of external factors, such as the accuracy you requested, reliability of the underlying location hardware, velocity or rate of change, and so on.
  • Creating a location subscription with startWatchingPosition() allocates resources that aren’t released automatically. Call stopWatchingPosition() to release those resources when appropriate. Failing to release resources can (eventually) result in errors, such as your app being terminated by the operating system.

See Also