Data types

Every type below is a named export re-exported from the package root, so you can import them directly for your own function signatures and component props:

import type { Location, State, Geofence } from '@dc-bgeo/react-native-background-geolocation';

Only the fields the app (and its backend) actually rely on are typed strictly here. A few object-shaped config and options types carry a permissive [key: string]: any index signature — unknown keys pass through uninterpreted rather than causing a type error.

Location & sensors

Location

The core location record. It’s the payload of onLocation and (when a fix exists) onMotionChange and onHeartbeat; the resolved value of getCurrentPosition(), watchPosition(), setOdometer()/resetOdometer(), and sync()/getLocations(); and the accepted shape for insertLocation() (as a Partial<Location>).

Field	Type	Description
uuid	string	Unique record id.
timestamp	string	ISO-8601 UTC.
age	number	Optional. Fix age in milliseconds at the time it was processed.
odometer	number	Cumulative odometer reading, metres.
coords	Coords	Position/motion fields.
activity	MotionActivity	Classified motion activity at the time of the fix.
battery	Battery	Device battery snapshot.
is_moving	boolean | null	Motion-state machine’s verdict at the time of this fix. null while a cold-started session’s first fixes are still in the unconfirmed-MOVING probing window — up to stopTimeout minutes after start(). The engine emits null there by design, so a server falls back to coords.speed instead of trusting a phantom “started moving”. Treat null the same as false.
sample	boolean	Optional. true when this Location was resolved by getCurrentPosition() — either an existing fix served for a fresh-enough maximumAge, or the best (most accurate) of several fixes sampled internally — rather than delivered by the ambient tracking stream. The intermediate fixes collected while sampling for the best one are never themselves surfaced as separate Location records. Also true on the fix resolved by setOdometer()/resetOdometer() — that fix carries event: 'odometer' (see the event field below) rather than coming from getCurrentPosition().
event	string	Optional. Tags why this record was produced when it isn’t a plain tracked fix. Observed values: 'motionchange' (the record captured just before entering the stationary state) and 'odometer' (the fix resolved by setOdometer()/resetOdometer()).
extras	object	Optional passthrough — e.g. { watch: true } on watchPosition() fixes, { heartBeat: true }, { getCurrentPosition: true }. Config-level extras form the base of every record; per-call extras are layered on top.

Snake_case: is_moving mirrors the wire format the native engines emit (camelCase elsewhere in this type, but this one field is snake_case — see also Coords and Battery below, which are almost entirely snake_case).

Coords

Nested inside Location.coords.

Field	Type	Description
latitude	number	Degrees.
longitude	number	Degrees.
accuracy	number	Horizontal accuracy, metres.
altitude	number	Optional. Metres above sea level.
altitude_accuracy	number	Optional. Vertical accuracy, metres.
speed	number	Optional. Metres/second.
speed_accuracy	number	Optional. Metres/second.
heading	number	Optional. Degrees.
heading_accuracy	number	Optional. Degrees.
ellipsoidal_altitude	number	Optional. Metres, WGS84 ellipsoidal (as opposed to altitude, which is mean-sea-level/geoid-based).

Snake_case: altitude_accuracy, speed_accuracy, heading_accuracy, and ellipsoidal_altitude are snake_case — they mirror the wire format the native engines emit, unlike latitude/longitude/accuracy/altitude/speed/heading.

MotionActivity

Nested inside Location.activity. Its type values are also the vocabulary accepted by config.triggerActivities (a CSV of these same strings).

Field	Type	Description
type	'still' | 'on_foot' | 'walking' | 'running' | 'on_bicycle' | 'in_vehicle' | 'unknown'	Classified activity.
confidence	number	Classifier confidence for type.

Snake_case: the field names (type, confidence) are plain camelCase, but three of the type enum values themselves — on_foot, on_bicycle, in_vehicle — are snake_case, again mirroring the native wire format.

Battery

Nested inside Location.battery.

Field	Type	Description
level	number	Battery level, 0.0–1.0.
is_charging	boolean	Whether the device is currently charging.

Snake_case: is_charging mirrors the native wire format.

HeadingEvent

One smoothed compass sample — the payload of watchHeading()’s success callback.

Field	Type	Description
heading	number	Smoothed heading in degrees, 0–360 (0 = north, clockwise).
accuracy	number	Platform-native passthrough, deliberately not harmonized. iOS: CLHeading.headingAccuracy, the maximum deviation in degrees (negative means invalid). Android: the magnetometer calibration level, an int 0–3 (0 unreliable .. 3 high).
isTrue	boolean	true when heading is true north (declination applied from the last known fix on Android / CLHeading.trueHeading on iOS); false — magnetic — before a fix exists or while uncalibrated.

State

The tracker’s state snapshot: resolved by ready(), setConfig(), start(), stop(), and getState(). Every field past enabled is optional — State documents the superset of health/diagnostic fields either native engine may populate, not a fixed cross-platform guarantee, and the type’s own index signature ([key: string]: any) admits further engine-specific fields not listed here.

Field	Type	Description
enabled	boolean	Whether tracking is enabled (the persisted on/off intent).
trackingActive	boolean	Optional. Whether the tracking engine currently has an active location request outstanding.
authorization	number	Optional. One of the AUTHORIZATION_STATUS_* constants.
lastRawFixAge	number | null	Optional, nullable. Diagnostic: age of the last raw fix (before filtering), in seconds. null until one arrives.
lastAcceptedFixAge	number | null	Optional, nullable. Diagnostic: age of the last accepted fix (after filtering), in seconds. null until one arrives.
lastLocationError	string | null	Optional, nullable. Diagnostic: the most recent location error message.
locationFailureCount	number	Optional. Diagnostic counter.
backgroundRearmCount	number	Optional. Diagnostic counter.
watchdogRecoveryCount	number	Optional. Diagnostic counter.
wakeRearmCount	number	Optional. Diagnostic counter.
stationaryRegionArmed	boolean	Optional. Diagnostic.
monitoredWakeRegions	number	Optional. Diagnostic counter.
lastWakeError	string | null	Optional, nullable. Diagnostic: the most recent wake-region error message.
trackingMode	number	Optional. Diagnostic.
isMoving	boolean	Optional. Current motion-state-machine verdict — same value as onMotionChange’s isMoving.
schedulerEnabled	boolean	Optional. Diagnostic.
odometer	number	Optional. Cumulative odometer reading, metres.
geofenceCount	number	Optional. Diagnostic counter.
lastGeofenceError	string | null	Optional, nullable. Diagnostic: the most recent geofence-registration error message.
connected	boolean	Optional. Validated-internet connectivity — see ConnectivityChangeEvent.

Events

ProviderChangeEvent

Payload of onProviderChange and the resolved value of getProviderState() (same shape).

Field	Type	Description
status	number	One of the AUTHORIZATION_STATUS_* constants — 3 is Always.
enabled	boolean	Whether location services are on at all.
gps	boolean	GPS provider enabled.
network	boolean	Network provider enabled.
accuracyAuthorization	number	Optional, iOS only — ACCURACY_AUTHORIZATION_FULL/REDUCED.
insufficientlyInUse	boolean	Optional, iOS 18+ only. true while authorization is granted but iOS refuses background runtime because the app hasn’t been opened since it was relaunched in the background — tracking degrades to short wake bursts. Prompt the user to open the app to restore continuous tracking.

MotionChangeEvent

Payload of onMotionChange.

Field	Type	Description
isMoving	boolean	true on the moving transition, false on the stationary transition.
location	Location	Optional (location?: Location | null) — absent (Android) or null (iOS) on the very first motionchange of a tracking session, before any fix exists yet (the initial probe fires from start() ahead of any location). Guard before dereferencing — see the Events reference for the same caveat.

GeofenceEvent

Payload of onGeofence.

Field	Type	Description
identifier	string	The geofence’s identifier.
action	'ENTER' | 'EXIT' | 'DWELL'	The transition type.
location	Location	The fix that triggered the transition.
extras	object	Optional. The geofence’s own extras, echoed back.

GeofencesChangeEvent

Payload of onGeofencesChange — a delta of the OS-registered subset, not the full persisted set (see Geofence below and the Geofencing guide).

Field	Type	Description
on	Geofence[]	Geofences newly registered with the OS.
off	Geofence[]	Geofences just unregistered.

HttpEvent

Payload of onHttp — fired once per completed location-sync HTTP request (log uploads do not emit this event; see the logging guide).

Field	Type	Description
success	boolean	true when status is 2xx.
status	number	HTTP status code; 0 when the request never got a response (network error).
responseText	string	Response body (or the error message when status is 0), truncated to 1024 characters.

ConnectivityChangeEvent

Payload of onConnectivityChange. Fired on validated-internet transitions (Android NET_CAPABILITY_VALIDATED / iOS NWPath.satisfied — a captive-portal Wi-Fi network reports false); a newly-registered listener also immediately receives the current state as a synthetic first delivery.

Field	Type	Description
connected	boolean	Validated-internet reachability.

CrashEvent

Payload of onCrash — an on-device collision confirmation. Armed only while moving, off by default; see config.crashDetection.

Field	Type	Description
timestamp	string	ISO-8601 UTC, the confirmation moment.
peakG	number	Peak impact magnitude, in g.
impactDurationMs	number	Duration of the impact signature, in ms.
preImpactSpeedMps	number	Speed immediately before impact, in m/s.
location	Location	Optional — the last known fix at confirmation time, or null if none was available.

DistractionEvent

Payload of onDistraction — an on-device distracted-driving episode. Armed only while moving, off by default; see config.distractionDetection. This detects the phone being physically handled at driving speed — see Limitations for what it cannot see.

Field	Type	Description
timestamp	string	ISO-8601, the moment the episode closed.
startTimestamp	string	ISO-8601, the episode start (same instant as the dds extras key below).
durationSec	number	Final episode duration in seconds (same value as the ddd extras key below).
cause	'h' | 's' | 'c'	'h' handling-only (iOS), 's' handling + active screen (Android), 'c' reserved for calls (not implemented).
location	Location	Optional — the last known fix at close time, or null if none was available.

Distraction extras keys

While an episode is open (and never lost to a sparse fix stream), the engine stamps these keys into the extras of every uploaded Location — this is the wire contract a backend parses, independent of the distraction event above:

Key	Type	When present	Meaning
dds	number	On every uploaded fix while an episode is open, and on the closing fix.	Unix seconds of the episode start. This value doubles as the episode id.
ddc	string	Alongside dds.	Cause: 'h' handling-only (iOS), 's' handling + active screen (Android), 'c' reserved for calls (not implemented).
ddd	number	Only on the first fix persisted after the episode ends.	Final episode duration in seconds.

Rules for a backend consuming these keys:

• Group fixes into an episode by equal dds value, not by adjacency in the fix stream — grouping by equal value survives gaps in delivery.
• Episode duration is ddd from the closing fix. If the closing fix never arrives, fall back to the span of fixes carrying that dds — this is only a lower bound.
• A short episode can produce no fixes “inside” it. If an episode is shorter than the interval between fixes, the next persisted fix simply carries dds, ddc and ddd together. Episodes are therefore never lost to a sparse fix stream.
• A pending close wins a race with a new open. If a new episode opens before the previous episode’s close has been flushed to a fix, that fix carries the pending close’s dds/ddc/ddd triple in full; the newly opened episode’s dds/ddc pair is deferred to the next record. Grouping by equal dds (above) is unaffected either way.
• Do not count episodes off the location stream. The closing triple (dds/ddc/ddd) rides every record built between the close and the first record that is actually persisted, so a sample: true one-shot and the location embedded inside another event can each carry it more than once. The uploaded-record contract is unaffected, but a consumer must count episodes from the distraction event instead — it fires once per episode in normal operation, but a rare disarm race can publish a second distraction event for the same episode (same dds/startTimestamp, different durationSec/ddd). A consumer that needs exact counts should dedupe by startTimestamp (equivalently dds).

Geofencing

Geofence

A persisted geofence definition — the shape accepted by addGeofence()/addGeofences() and returned by getGeofences() and the on/off arrays of GeofencesChangeEvent. See the Geofencing guide for validation rules, proximity slicing, and DWELL semantics.

Field	Type	Description
identifier	string	Unique geofence id.
radius	number	Metres.
latitude	number	Degrees.
longitude	number	Degrees.
notifyOnEntry	boolean	Optional.
notifyOnExit	boolean	Optional.
notifyOnDwell	boolean	Optional.
loiteringDelay	number	Optional. Milliseconds; required alongside notifyOnDwell for a DWELL transition.
extras	object	Optional. Echoed back on the corresponding GeofenceEvent.

Positioning options

CurrentPositionOptions

Parameter of getCurrentPosition().

Field	Type	Description
persist	boolean	Optional. Whether the resolved fix is added to the upload queue like a normal tracked point.
samples	number	Optional. Number of fixes to sample before returning the best (most accurate) one.
timeout	number	Optional. Seconds to wait before giving up. Default 30.
maximumAge	number	Optional. Accept a cached fix up to this many milliseconds old instead of sampling a new one.
desiredAccuracy	number	Optional. One of the DESIRED_ACCURACY_* constants.
extras	object	Optional. Merged into the returned location’s extras.

WatchPositionOptions

Parameter of watchPosition().

Field	Type	Description
interval	number	Optional. Desired update interval, milliseconds.
desiredAccuracy	number	Optional. One of the DESIRED_ACCURACY_* constants.
persist	boolean	Optional. Whether fixes are added to the upload queue.
extras	object	Optional. Merged into each returned location’s extras.

HeadingOptions

Parameter of watchHeading(). All fields optional; an omitted field lets the engine’s own default apply.

Field	Type	Description
minIntervalMs	number	Optional. Minimum gap between emitted samples, ms. Default 40 (caps output at 25 Hz).
minDeltaDeg	number	Optional. Minimum heading change to emit, degrees, along the shortest arc. Default 0.5.
smoothingTauMs	number	Optional. Time constant of the exponential smoother on the unit circle, ms — larger is steadier and laggier. Default 120.

The first sample after watchHeading() starts — or restarts after a foreground resume — is always emitted, regardless of minIntervalMs/minDeltaDeg.

Logging

LogEntry

Resolved array-element type of getLog(); written by logger.error/warn/info/debug/verbose and the native engine itself. See the logging guide for retention and upload cadence.

Field	Type	Description
ts	string	ISO-8601 UTC.
level	number	1=ERROR, 2=WARN, 3=INFO, 4=DEBUG, 5=VERBOSE.
src	'native' | 'js'	Whether the line originated in the native engine or app-side JS (logger.* calls).
event	string	Short event tag.
message	string	Optional. Human-readable log line.
data	any	Optional. JSON-serialized data attached to the line.

Headless

HeadlessEvent

Parameter of the task passed to registerHeadlessTask() Android . Unlike every other event type on this page, there is no params/payload wrapper — the event’s payload fields are flattened alongside name directly on the same object (enforced by the type’s [key: string]: any index signature). iOS never invokes a registered headless task at all, since there’s no AppRegistry-driven headless service on that platform — see registerHeadlessTask() and the boot & killed-app guide.

Field	Type	Description
name	'heartbeat' | 'motionchange' | 'geofence' | 'providerchange' | 'powersavechange' | 'http' | 'connectivitychange'	The event type. The union matches the Android engine’s headless dispatch set exactly; 'location' is deliberately not part of it — see below.
[key: string]	any	The rest of the event’s fields, flattened alongside name — e.g. a headless motionchange carries isMoving/location directly on this object, not nested under a params key.

No headless location: the Android engine never dispatches a location event headlessly, and the union reflects that — the runtime set of headless-dispatched event names is exactly heartbeat, motionchange, geofence, providerchange, powersavechange, http, and connectivitychange, so narrowing on event.name is exhaustive. High-frequency location fixes are deliberately excluded to avoid spinning up Android’s HeadlessJsTaskService (and a wakelock) per fix while tracking, which would drain battery and risk ANRs/foreground-service-start restrictions; fixes taken while the JS context isn’t running are still durably queued and uploaded natively. This mirrors the same note under onLocation on the Events reference.

Subscriptions

Subscription

Returned by every on* listener method on the Events reference.

Field	Type	Description
remove	() => void	Detaches this one listener. To tear down every listener at once, call removeListeners() instead.