AFCore/com.advantahealth.api.geofencing/AFGeofencing

AFGeofencing

Provides an interface for managing geofences for facility monitoring.

This object allows starting and stopping geofencing services, and provides a Flow to observe geofence events. It uses Google Play Services for geofencing and a foreground service to maintain functionality when the app is in the background.

Geofences are persisted to disk so they can be re-registered after device reboot or app update via AFGeofenceBootReceiver.

expect object AFGeofencing

Expect declaration for geofencing management. Platform-specific implementations should handle setup, registration, and event emission.

This object provides a unified API for interacting with the geofencing capabilities of the underlying platform. It allows for the registration of geofence and emits events when these geofence are entered or exited.

Usage example:

// Define geofence
val geofence1 = AFGeofence(id = "work", latitude = 37.7749, longitude = -122.4194, radius = 100f)
val geofence2 = AFGeofence(id = "home", latitude = 37.3318, longitude = -122.0312, radius = 150f)

// Start monitoring
try {
    AFGeofencing.startGeofencing(listOf(geofence1, geofence2))
} catch (e: Throwable) {
    // Handle exceptions during geofencing setup
    println("Error starting geofencing: ${e.message}")
}

// Collect events
CoroutineScope(Dispatchers.Main).launch {
    AFGeofencing.events.collect { event ->
        when (event) {
            is AFGeofenceEvent.GeofenceRegistered -> {
                println("Geofence registered: ${event.geofenceId}")
            }
            is AFGeofenceEvent.GeofenceRegistrationFailed -> {
                println("Failed to register geofence ${event.geofenceId}: ${event.errorMessage}")
            }
            is AFGeofenceEvent.GeofenceTransition -> {
                val transitionType = when (event.transitionType) {
                    AFGeofenceTransitionType.ENTER -> "entered"
                    AFGeofenceTransitionType.EXIT -> "exited"
                    AFGeofenceTransitionType.DWELL -> "dwelling in"
                }
                println("User $transitionType geofence: ${event.geofenceId}")
            }
         }
      }
 }

actual object AFGeofencing

AFGeofencing is the main entry point for interacting with the geofencing functionality.

It provides methods to start and stop geofencing, and a flow to observe geofence events.

Example usage:

AFGeofencing.events.onEach { event ->
   when (event) {
      is AFGeofenceEvent.Enter -> println("Entered geofence: ${event.geofence.id}")
     is AFGeofenceEvent.Exit -> println("Exited geofence: ${event.geofence.id}")
    is AFGeofenceEvent.Error -> println("Geofencing error: ${event.throwable.message}")
   else -> {}
}
}.launchIn(coroutineScope)

AFGeofencing.startGeofencing(listOf(
  AFGeofence(id = "home", latitude = 37.7749, longitude = -122.4194, radius = 100f),
 AFGeofence(id = "work", latitude = 37.7839, longitude = -122.4013, radius = 200f)
))

actual object AFGeofencing

watchOS stub for AFGeofencing. Geofencing is not supported on watchOS — all methods return failure/inactive results and events never emits.

Properties

events

actual val events: SharedFlow<AFGeofenceEvent>

expect val events: SharedFlow<AFGeofenceEvent>

Flow of geofencing events such as registration, transitions, and errors. Collect this flow to receive real-time updates.

actual val events: SharedFlow<AFGeofenceEvent>

Functions

getStatus

actual fun getStatus(): AFGeofencingStatus

expect fun getStatus(): AFGeofencingStatus

Returns the current geofencing status for this device.

actual fun getStatus(): AFGeofencingStatus

hasPermissions

actual fun hasPermissions(): Boolean

expect fun hasPermissions(): Boolean

Checks if all necessary permissions (e.g., location) are granted.

actual fun hasPermissions(): Boolean

start

actual fun start(geofences: List<AFGeofence>): AFGeofencingResult

Starts the geofencing service with the given list of geofences. Geofences are validated, persisted to disk, and registered with Google Play Services. A foreground service is started to ensure reliable background operation.

expect fun start(geofences: List<AFGeofence>): AFGeofencingResult

Starts monitoring a list of geofences.

actual fun start(geofences: List<AFGeofence>): AFGeofencingResult

stop

actual fun stop(): AFGeofencingResult

Stops the geofencing service. Removes all registered geofences, stops the foreground service, and clears persisted state.

expect fun stop(): AFGeofencingResult

Stops all active geofence monitoring.

actual fun stop(): AFGeofencingResult

updateGeofences

fun updateGeofences(newGeofences: List<AFGeofence>)

Replaces the current set of monitored geofences with a new list. If geofencing is not active, this call is ignored.