Callbacks & events

The SDK delivers events to your application through two complementary mechanisms:

1. RoadSaveListener — direct callbacks on the main thread (recommended for new integrations)
2. LocalBroadcast intents via RoadSaveBroadcastConstants (backward-compatible, retained from 3.x)

Both mechanisms coexist in 4.0.0 via the CompositeEventDispatcher.

---

RoadSaveListener interface

Register with RoadSave.setRoadSaveListener(listener) before calling configurationSetup.

sdk.setRoadSaveListener(object : RoadSaveListener {

    override fun onConfigurationSuccess() { }

    override fun onConfigurationError(errorCode: Int, message: String) { }

    override fun onTripStarted(startInfo: TripStartInfo) { }

    override fun onTripEnded(tripInfo: TripInfo) { }

    override fun onTripMonitoringUpdate(currentTripInfo: CurrentTripInfo) { }

    override fun onCrashDetected(crashInfo: CrashInfo) { }

    override fun onLocationChanged(location: RoadSaveLocation) { }

    override fun onLocationEnabledChanged(enabled: Boolean) { }

    override fun onSdkError(errorCode: Int) { }
})

Remove the listener when it is no longer needed:

sdk.removeRoadSaveListener()

---

Callback reference

onConfigurationSuccess()

Called when configurationSetup completes and the SDK is registered with the server. Monitoring starts immediately after this callback.

---

onConfigurationError(errorCode: Int, message: String)

Called when configurationSetup fails. errorCode is in the range 100–107. message is a human-readable description from the server, suitable for logging.

---

onTripStarted(startInfo: TripStartInfo)

Called when the SDK detects the start of a vehicle trip (speed exceeds the configured threshold).

Field	Type	Description
startInfo.startLocation	RoadSaveLocation	Location where the trip began
startInfo.startTimeStamp	Long	Epoch milliseconds

---

onTripEnded(tripInfo: TripInfo)

Called when the trip ends (vehicle stops for the configured idle duration).

Field	Type	Description
tripInfo.distance	Double	Total distance in metres
tripInfo.averageSpeed	Double	Average speed in m/s
tripInfo.startTimeStamp	Long	Epoch milliseconds
tripInfo.endTimeStamp	Long	Epoch milliseconds
tripInfo.wayPoints	ArrayList<RoadSaveLocation>	Route waypoints

---

onTripMonitoringUpdate(currentTripInfo: CurrentTripInfo)

Called approximately every second during an active trip.

Field	Type	Description
currentTripInfo.currentLocation	RoadSaveLocation	Live location
currentTripInfo.startTripInfo	TripStartInfo	Trip origin
currentTripInfo.wayPoints	ArrayList<RoadSaveLocation>	Route so far

---

onCrashDetected(crashInfo: CrashInfo)

Called after the SDK detects a threshold breach and the server evaluates the event.

Field	Type	Description
crashInfo.confidence	CrashConfidence	HIGH / LOW / UNKNOWN
crashInfo.crashSpeed	Double	Speed at the breach point (m/s)
crashInfo.crashMaxGForce	Double	Peak G-force reading
crashInfo.crashTimeStamp	Long	Epoch milliseconds
crashInfo.crashLocation	RoadSaveLocation	Location at breach
crashInfo.CrashEvaluationGUID	String?	Unique crash ID — pass to setCrashFalsePositive

---

onLocationChanged(location: RoadSaveLocation)

Called whenever the device location updates.

Field	Type	Description
location.latitude	Double	WGS-84 latitude
location.longitude	Double	WGS-84 longitude
location.speed	Float	Speed in m/s
location.accuracy	Float	Horizontal accuracy in metres
location.bearing	Float	Direction of travel in degrees
location.altitude	Double	Altitude in metres
location.time	Long	Epoch milliseconds

---

onLocationEnabledChanged(enabled: Boolean)

Called when the device's location services are toggled by the user. Use this to prompt the user to re-enable location when enabled is false.

---

onSdkError(errorCode: Int)

Called for all runtime errors after initial configuration. See ErrorCode for the full list.

---

ErrorCode reference

Configuration errors (100–107) — delivered via onConfigurationError

Code	Constant	Description
100	ConfigErrorOSNotSupported	OS version not supported
101	ConfigErrorDeviceNotSupported	Device model not supported
102	ConfigErrorAuthorisationDenied	Invalid or revoked credentials
103	ConfigErrorUserLimit	Application ID user limit reached
104	ConfigErrorSDKDenied	Application ID disabled or not found
105	ConfigErrorLocationDenied	Invalid location data at configuration time
106	ConfigErrorInvalidParams	Empty or invalid parameters passed to configurationSetup
107	ConfigErrorUnknown	Unknown registration error

Crash evaluation / sensor errors (300–301) — delivered via onSdkError

Code	Constant	Description
300	EvaluationError	Error evaluating a potential crash event
301	AccelerometerError	Accelerometer data feed interrupted or sensor unavailable

Service lifecycle / runtime errors (500–505) — delivered via onSdkError

Code	Constant	Description
500	SdkStopped	Primary monitoring service stopped unexpectedly
501	CrashEvaluateError	Exception in crash evaluation service
502	CrashEvaluateCurrentLocation	Current location was null at evaluation time
503	CrashEvaluateStartLocation	Trip start location was null at evaluation time
504	ActivityMonitorStartError	Activity monitor service could not start
505	ForegroundServicePermissionError	Foreground location service blocked by missing permission

---

Broadcast receiver reference

For integrations using the legacy broadcast mechanism, the action strings and extra key constants are defined in RoadSaveBroadcastConstants.

Action constant	Description	Data extra key
CRASH_DETECTED	Crash evaluated	CRASH_DETECTED_DATA → CrashInfo
TRIP_MONITORING_START	Trip started	TRIP_MONITORING_START_DATA → TripStartInfo
TRIP_MONITORING_ENDS	Trip ended	TRIP_MONITORING_ENDS_DATA → TripInfo
TRIP_MONITORING	Live trip update (~1 Hz)	TRIP_MONITORING_DATA → CurrentTripInfo
ON_LOCATION_CHANGED	Location update	ON_LOCATION_CHANGED_DATA → RoadSaveLocation
CONFIG	Registration result	CONFIG_STATUS → Boolean
CONFIG_ERROR	Registration failed	CONFIG_ERROR_CODE → Int, CONFIG_ERROR_MSG → String
LOCATION_ENABLED	Location toggle	LOCATION_ENABLED_DATA → Boolean
SDK_ERROR	Runtime error	SDK_ERROR_CODE → Int