Overview
The controlLiveLocation action manages the device's continuous GPS tracking session. Unlike a one-shot location read (available via the getDeviceLocation action), this action sets up a recurring poll that fires the onLocation callback each time a new position fix arrives. The tracking session persists until you explicitly stop it with operation: "stop", even if the user navigates to a different page within the app.
Warning: Platform permissions required. On Android, declare ACCESS_FINE_LOCATION or ACCESS_COARSE_LOCATION in the app manifest. On iOS, add NSLocationWhenInUseUsageDescription (and optionally NSLocationAlwaysUsageDescription for background tracking) to Info.plist. The action automatically triggers the system permission dialog on first use if the permission has not yet been granted. If the user denies permission, the action fires the onError callback with code: "PERMISSION_DENIED".
Parameters
| Parameter | Type | Required | Default | Description |
| operation | "start" | "stop" | Required (required) | — | start begins a new tracking session. If a session is already active, calling start again updates the session parameters (interval, accuracy) without restarting. stop terminates the current session; subsequent location callbacks are cancelled. |
| interval | number (ms) | Optional (optional) | 5000 | How frequently to request a location update, in milliseconds. The device may deliver updates less frequently if movement is slow and power-saving is active. Minimum: 1000 ms. Recommended range for field operations: 5000–15000 ms. |
| accuracy | "high" | "balanced" | "low" | Optional (optional) | "balanced" | high uses GPS + Wi-Fi/cell — best accuracy, highest battery use. balanced uses network-assisted GPS — good accuracy, moderate battery use. low uses cell towers and Wi-Fi only — rough accuracy (100–3000 m), minimal battery impact. |
| onLocation | ActionChain | Optional (optional) | — | Callback action chain fired on each location update. Receives a location object: { lat: number, lng: number, accuracy: number, altitude: number | null, speed: number | null, heading: number | null, timestamp: number }. Access values with {{ onLocation.location.lat }}. |
| onError | ActionChain | Optional (optional) | — | Fires on permission denial or if GPS is unavailable. Receives { code: string, message: string }. Common codes: PERMISSION_DENIED, POSITION_UNAVAILABLE, TIMEOUT. |
Location Callback Payload
| Field | Type | Description |
| lat | number | Latitude in decimal degrees (WGS84). |
| lng | number | Longitude in decimal degrees (WGS84). |
| accuracy | number | Horizontal accuracy radius in metres. Lower is better. |
| altitude | number | null | Altitude above sea level in metres. null if unavailable. |
| speed | number | null | Ground speed in metres per second. null if unavailable. |
| heading | number | null | Bearing in degrees (0–360, clockwise from true north). null if not moving. |
| timestamp | number | Unix timestamp (ms) of the location fix. |
Step-by-Step Usage Guide
Configure platform permissions: In App Settings → Mobile → Permissions, enable Location (Fine). This adds the necessary manifest entries for Android and iOS. Provide a clear permission rationale message that explains why the app needs location access.
Create a Start Tracking button: Add a Button block labelled "Start Tracking". In its
onClickevent, add a Control Live Location action withoperation: "start", your desired interval, and theonLocationcallback chain.Define the onLocation callback: Inside the callback, add a Trigger Data Source action that POSTs to your location-tracking API endpoint. Pass
{{ onLocation.location.lat }},{{ onLocation.location.lng }}, and{{ onLocation.location.timestamp }}as parameters.Stop tracking when done: Add a Stop Tracking button with a Control Live Location action with
operation: "stop". Also firestopin the page'sonPageUnmountevent to prevent stale tracking sessions when the user navigates away.
Examples
Start tracking and send updates to an API
{ "actionType": "controlLiveLocation", "payload": { "operation": "start", "interval": 10000, "accuracy": "high", "onLocation": [ { "actionType": "triggerDataSource", "payload": { "dataSourceId": "ds_updateWorkerLocation", "params": { "lat": "{{ onLocation.location.lat }}", "lng": "{{ onLocation.location.lng }}", "timestamp": "{{ onLocation.location.timestamp }}", "workerId": "{{ appUser.id }}" } } } ], "onError": [ { "actionType": "showNotification", "payload": { "type": "error", "title": "Location unavailable", "description": "{{ onError.message }}" } } ] } }
Stop tracking on page unmount
// Wire to onPageUnmount event: { "actionType": "controlLiveLocation", "payload": { "operation": "stop" } }
Tip: Battery optimisation: Use accuracy: "balanced" and intervals of 10–30 seconds for most field use cases. Reserve accuracy: "high" only when sub-10-metre precision is required (e.g. indoor navigation, precise geofencing). High accuracy on a 5-second interval can drain a mobile battery in under 4 hours.