AFCore/com.advantahealth.api.geofencing.model/AFGeofenceEvent

AFGeofenceEvent

A discrete event emitted by the geofencing service over its event stream.

Consumers observe these to drive UI, analytics, or recovery logic. Each variant is a distinct state in the geofencing lifecycle:

Idle — the stream's initial / quiescent state before any activity.
Registered / Unregistered — geofences added to or removed from monitoring.
RegistrationFailed — partial registration failure (some IDs rejected) so consumers can retry only the failed IDs.
Entered / Exited / Dwell — boundary transitions and dwell milestones.
Heartbeat — periodic liveness signal carrying the current location.
Error — a service-level error.

Typical flows

Monitoring lifecycle: Idle → Registered → Entered → Dwell → Exited → Unregistered.
Recovery: on RegistrationFailed, re-register only failedIds; on Error, surface the failure and decide whether to restart monitoring.

when (event) {
    is AFGeofenceEvent.Entered -> onEnter(event.geofenceId)
    is AFGeofenceEvent.Dwell -> recordVisit(event.geofenceId, event.dwellDurationSeconds)
    is AFGeofenceEvent.Exited -> onExit(event.geofenceId)
    is AFGeofenceEvent.RegistrationFailed -> retry(event.failedIds)
    is AFGeofenceEvent.Error -> log(event.throwable)
    AFGeofenceEvent.Idle -> { /* no activity yet */}
    else -> { /* Registered / Unregistered / Heartbeat */}
}

Inheritors

Types

Dwell

data class Dwell(val geofenceId: String, val location: AFGeoLocation?, val dwellDurationSeconds: Long = 0) : AFGeofenceEvent

Indicates that the device has dwelled within a geofence for the specified duration.

Entered

data class Entered(val geofenceId: String, val location: AFGeoLocation?, val synthesized: Boolean = false) : AFGeofenceEvent

Indicates that the device has entered a geofence.

Error

data class Error(val throwable: Throwable) : AFGeofenceEvent

Signals an error that occurred within the geofencing service.

Exited

data class Exited(val geofenceId: String, val location: AFGeoLocation?) : AFGeofenceEvent

Indicates that the device has exited a geofence.

Heartbeat

data class Heartbeat(val location: AFGeoLocation?) : AFGeofenceEvent

A periodic event providing the device's current location, or null if location is unavailable. This serves as a heartbeat to indicate the geofencing service is active and to provide location updates.

Idle

data object Idle : AFGeofenceEvent

The stream's initial, quiescent state — emitted as the seed value before any geofencing activity has occurred (e.g. immediately after the event flow is created and before any geofences are registered or any transition is detected). Carries no payload; treat it as "nothing to report yet" and take no action.

Registered

data class Registered(val geofenceIds: List<String>) : AFGeofenceEvent

Indicates that one or more geofences have been successfully registered with the system.

RegistrationFailed

data class RegistrationFailed(val failedIds: List<String>, val cause: Throwable? = null) : AFGeofenceEvent

Indicates a partial registration failure: some geofences in a batched registration call were rejected by the platform while others succeeded. Distinct from Error so consumers can implement targeted retry logic (re-register only the failed IDs) instead of falling back to a full stop/start cycle.

Unregistered

data class Unregistered(val geofenceIds: List<String>? = null) : AFGeofenceEvent

Indicates that geofences have been unregistered.