Live location tracking in ThingsBoard PE Mobile Application

Live location tracking turns the phone into a moving sensor. A dashboard widget action starts a session; the app then streams GPS fixes — including while it is in the background — and writes each one to a ThingsBoard entity as attributes or time series.

Typical uses are field-worker check-ins, delivery routes, and any case where the thing you want to track is a person carrying a phone rather than a device with its own modem.

1. A user taps a widget action configured as Start live location tracking on a dashboard opened in the app.
2. The dashboard resolves the target entity and the data key names, and hands the app one complete configuration. The app never has to look anything up mid-session.
3. The app asks for location permission if it does not have it yet, then starts streaming fixes and saving each one to the target entity.
4. A tracking bar appears across the app for as long as the session runs.
5. The session ends when the user stops it, when a Stop live location tracking action is triggered, or when the configured maximum duration is reached.

Everything the session does — which entity it writes to, which data keys it uses, how accurate the fixes are, and how long it may run — comes from the widget action. Configure it on the platform side first: see Location tracking.

---

While a session runs, a bar sits across the top of the app on every main page. Tap it to open the tracking page.

Element	Meaning
Live location tracking / Live tracking paused	Current session state
Fixes	Positions received from the device
Saved	Positions successfully written to the target entity
Errors	Saves that failed. Appears only once at least one save has failed

A gap between Fixes and Saved is the quickest signal that something is wrong with saving rather than with the GPS.

The bar has three buttons:

Control	Effect
Pause / Resume	One button that suspends and resumes position updates without ending the session. Pausing writes gpsActive as false; resuming writes it back as true
Stop	Ends the session and writes gpsActive as false
Hide	Collapses the bar to a thin strip with a pulsing icon. Tap the strip to bring the bar back — the session keeps running

A session can also enter the paused state on its own, when location becomes unavailable — services switched off, or permission revoked mid-session.

---

Field	Shows
Save location to entity	The target entity. A device, asset or customer is a link — a device opens its profile dashboard, an asset or a customer its details page. Any other entity type is shown as plain text
Dashboard	The dashboard the session was started from. Tap it to go back
Status	Tracking or paused
Start time	When the session started
Last fix	Time and coordinates of the most recent position
Fixes / Saved / Errors	The same counters as the tracking bar
Last error	The most recent failure, if any

The page shows the Last session summary — target entity, start and end time, end reason, the three counters, and the last error. A Start again button restarts tracking with the same configuration, so a user who stopped by mistake does not have to find the dashboard again.

The summary is stored on the device, so it survives an app restart. If there has never been a session, the page reads “No active tracking and no recent session.”

---

The app asks for location permission the first time a session starts. Background tracking needs the Always permission — “while using the app” is not enough once the phone is locked or the app is backgrounded.

Platform	What to expect
Android	Precise location is requested on every Android version, including API 36 and later. While tracking is active, a foreground-service notification is shown — this is required by the system and cannot be dismissed
iOS	The permission prompt explains background live tracking. While tracking, iOS shows its own system location indicator in the status bar

If a user denies the permission permanently, the app cannot re-prompt — the message points them to the app settings instead.

---

Each fix is written to the target entity under the data keys configured in the widget action. gpsActive and gpsTrackedBy are the exception: they describe the session rather than a position, so neither is written per fix. gpsActive is written whenever the session state changes — start, pause, resume and stop. gpsTrackedBy is written alongside it when tracking starts or resumes.

For the full list of fields, their default data key names and whether each is saved as a server attribute or time series, see Saved keys.

---

The end reason is recorded with the session and shown on the tracking page afterwards:

End reason	Meaning
Stopped manually	A user tapped Stop, or a Stop live location tracking action was triggered
Reached max duration	The maximum duration configured in the widget action elapsed. The session ends by itself
Interrupted	The session did not end cleanly — for example, the app was killed while tracking

Logging out stops an active session and clears the stored last-session record.

---

Save failures do not end the session. The app keeps tracking and retries with the next fix, so a tunnel or a dropped connection costs you a few points rather than the whole session.

Message	What it means
Can’t save to this entity — it no longer exists	The target entity was deleted. Tracking continues, but nothing is saved. A session keeps the target it started with, so update the dashboard action, then stop the session and start a new one
No connection to the server	These fixes were not saved. Saving resumes when the device is back online
Your session ended	The login session expired. Sign in again to keep saving location
Can’t save to this entity — you don’t have permission	Your role does not allow writing to the target entity. Tracking continues, but nothing is saved until an administrator grants access
Couldn’t save this fix to the server	A transient server-side failure. Saving retries with the next fix
Location services are turned off on this device	Turn location on in the system settings
Location permission was denied	Grant the app location permission
Location permission is permanently denied	Enable it in the app settings — the app can no longer prompt
Couldn’t get a location fix	The device could not determine a position