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

activeGeofencesFlow

actual val activeGeofencesFlow: StateFlow<List<AFActiveGeofence>>

Reactive view of getActiveGeofences. Re-emits whenever a membership state changes (Enter / Exit / Dwell / didDetermineState on iOS) or the active geofence set is updated. Replays the latest snapshot to new collectors.

expect val activeGeofencesFlow: StateFlow<List<AFActiveGeofence>>

actual val activeGeofencesFlow: StateFlow<List<AFActiveGeofence>>

events

actual val events: SharedFlow<AFGeofenceEvent>

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

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>

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

actual val events: SharedFlow<AFGeofenceEvent>

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

statusFlow

actual val statusFlow: StateFlow<AFGeofencingStatus>

Live geofencing status. Replays the latest value to new collectors and emits whenever the SDK transitions between states (e.g., user grants Always location after only While Using, revokes location in Settings, geofencing fails to start, etc.). Use this to drive reactive UI without polling getStatus.

expect val statusFlow: StateFlow<AFGeofencingStatus>

actual val statusFlow: StateFlow<AFGeofencingStatus>

Functions

getActiveGeofences

actual fun getActiveGeofences(): List<AFActiveGeofence>

Snapshot of every currently monitored geofence and the device's last-known membership state for each. Useful for rendering "you're at this facility" UI immediately after registration without waiting for a transition event.

expect fun getActiveGeofences(): List<AFActiveGeofence>

actual fun getActiveGeofences(): List<AFActiveGeofence>

getStatus

actual fun getStatus(): AFGeofencingStatus

Returns the current geofencing status for this device.

expect fun getStatus(): AFGeofencingStatus

Returns the current geofencing status for this device.

actual fun getStatus(): AFGeofencingStatus

Returns the current geofencing status for this device.

actual fun getStatus(): AFGeofencingStatus

Returns the current geofencing status for this device.

hasPermissions

actual fun hasPermissions(): Boolean

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

expect fun hasPermissions(): Boolean

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

actual fun hasPermissions(): Boolean

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

actual fun hasPermissions(): Boolean

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

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

Starts monitoring a list of geofences.

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

Starts monitoring a list of geofences.

stop