You are here:
getCurrentPosition()
Gets the current device GPS position of a mobile device by querying the device’s location services and returns coordinates if available. By default, if high accuracy using GPS is not available, the mobile app switches to coarse location using cell or WiFi.
Required Editions
| Available in Lightning Experience in Enterprise and Unlimited Editions with Consumer Goods Cloud enabled |
Parameters
optionsobject: Optional. Geolocation configuration object. Defaults to empty object {}.The options object may contain the following properties:maximumAge: Integer. Maximum age (in milliseconds) of a cached position. If 0, the app ignores the cache and retrieves a fresh position. Default is 60000.timeout: Integer. Maximum time (in milliseconds) to wait for position. If 0, the app returns a position immediately or times out. Default is 5000.isHighAccuracyOnly: Boolean. Iftrue, the app attempts to retrieve the location using only high-accuracy sources (GPS) and doesn't fall back to network-based location sources such as cellular or WiFi. Default isfalse.
Returns
- Promise: A promise that resolves with one of the following:
- The
Positionobject uses these four properties to capture the device location:latitude: (Number) The latitude coordinate in decimal degrees.longitude: (Number) The longitude coordinate in decimal degrees.accuracy: (Number) The accuracy level of the latitude and longitude coordinates in meters.altitude: (Number) The altitude or height of position in meters.
- null: If location services are disabled, unavailable, or the API timed out.
- Rejects with error message: If validation of the
optionsparameter fails.
- The
Considerations
When configuring location services in Consumer Goods Cloud, consider these key points to ensure optimal performance and accuracy:
- Default behavior: If GPS fails, the system uses network-based location (which is less accurate) to ensure better reliability for general use cases.
- High accuracy requirement: For situations where high accuracy is needed, set a timeout
of 30 seconds or higher and
isHighAccuracyOnlyis true because GPS satellite acquisition takes longer than network location. - Fresh data: Setting a lower
maximumAgeensures that the system always uses the recent and most up-to-date coordinates for time-sensitive operations.
Example Sample snippet using default
options
// Uses default options as documented
// If high accuracy GPS fails or times out, automatically falls back to low accuracy
// network-based location (cell towers/WiFi) for better reliability
Utils.getCurrentPosition().then(
function(position) {
if (Utils.isDefined(position)) {
AppLog.info("Latitude: " + position.latitude);
AppLog.info("Longitude: " + position.longitude);
AppLog.info("Accuracy: " + position.accuracy + " meters");
} else {
// Location services are completely disabled on device
AppLog.info("Location services are disabled");
}
},
function(error) {
AppLog.info("Failed to get position: " + error);
}
);Example Combined Options for Critical
Operations
// Fresh position (max 10s old), 30 second timeout, GPS only - for precision-critical operations
// Higher timeout (30s) is crucial: GPS requires more time to acquire satellite fix
// for high accuracy positioning compared to network-based location
// Low maximumAge ensures fresh coordinates, not stale cached data
// isHighAccuracyOnly: true prevents fallback to less accurate network location
Utils.getCurrentPosition({
maximumAge: 10000, // Accept position cached max 10 seconds ago
timeout: 30000, // Wait up to 30 seconds for GPS satellite fix
isHighAccuracyOnly: true // No fallback to network location
}).then(
function(position) {
if (Utils.isDefined(position)) {
// Use highly accurate, fresh position for critical operations
var coords = {
lat: position.latitude,
lon: position.longitude,
accuracy: position.accuracy,
altitude: position.altitude
};
processHighAccuracyLocation(coords);
}
},
function(error) {
AppLog.info("Failed to get accurate position: " + error);
}
);Example Validation Error Handling
// Invalid options will be caught and rejected with detailed validation error message
Utils.getCurrentPosition({ timeout: "fast" }).then(
function(position) {
// Won't reach here if validation fails
},
function(error) {
// Error message will indicate: "Geolocation validation failed: timeout: must be integer"
// Ensure maximumAge and timeout are positive integers, isHighAccuracyOnly is boolean
AppLog.info(error);
}
);Did this article solve your issue?
Let us know so we can improve!
