geofencer

Geofencer

Convenience library to receive user location updates and geofence events with minimal effort. Survives app kills and device reboots.

---

Table of Contents

• Features
• Location Filtering
• Installation
• Initialization
• Quick Start
  • Geofencing
  • Location Tracking
• API Reference
• Permissions
• Maestro UI Tests
• Contributing
• License

---

Features

• Kotlin-first API with DSL builders and coroutines
• Geofence transitions: enter, exit, dwell
• Continuous location updates via SharedFlow
• Survives app kill and device reboot (via WorkManager)
• Auto-initializes via built-in ContentProvider (no external dependencies)
• Configurable update intervals, displacement, and priority
• Custom actions for geofence and location events
• minSdk 23, targets Android 15+

Location Filtering

Raw GPS is noisy — especially indoors, where fixes can drift hundreds of meters. The library runs every location update through a filtering pipeline before it reaches your code or triggers a geofence event.

FusedLocationProvider
  → Accuracy gate         — reject fixes worse than a threshold
  → Speed check           — reject teleportation (configurable m/s cap)
  → Accuracy-weighted     — ignore movement within the error radius
  → Provider quality      — reject garbage network-provider fixes
  → Consistency buffer    — require N consecutive samples before flipping state
  → Dwell confirmation    — require the device to *stay* before emitting
  → Event deduplication   — prevent double-fires from Play Services + client-side

All filters have sensible defaults and are configurable via LocationConfig and GeofenceBuilder. Unfiltered data is still available via LocationTracker.rawLocations.

Installation

Maven Central

implementation("net.kibotu:geofencer:3.0.0")

JitPack

Add the JitPack repository to your settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        maven { url = uri("https://jitpack.io") }
    }
}

Then add the dependency:

implementation("com.github.kibotu:geofencer:latest")

Initialization

The library auto-initializes using a ContentProvider — no manual setup needed.

Customizing init order

The ContentProvider uses android:initOrder to control initialization priority relative to other providers. The default value is 100. Higher values mean the provider is initialized earlier.

Override the priority in your app’s res/values/integers.xml (or any values resource file):

<resources>
    <integer name="geofencer_init_priority">200</integer>
</resources>

Disabling auto-initialization

Add a boolean resource override in your app’s res/values/ to disable the ContentProvider from initializing the library:

<resources>
    <bool name="geofencer_auto_init_enabled">false</bool>
</resources>

Then initialize manually in your Application.onCreate():

Geofencer.init(applicationContext)

Alternatively, you can remove the provider entirely via manifest merging:

<provider
    android:name="net.kibotu.geofencer.internal.GeofencerInitializer"
    android:authorities="${applicationId}.geofencer-init"
    tools:node="remove" />

Quick Start

Geofencing

1. Add a geofence

Geofencer.add {
    latitude = 52.520008
    longitude = 13.404954
    radius = 200.0
    label = "Berlin"
    message = "Welcome to Berlin!"
    transitions = setOf(Geofence.Transition.Enter, Geofence.Transition.Exit)
    action<NotificationAction>()
}

2. Observe events

lifecycleScope.launch {
    Geofencer.events.collect { event ->
        Log.d("Geofence", "${event.transition.name} ${event.geofence.label}")
    }
}

3. Create a custom action

Actions run even when the app is killed:

class NotificationAction : GeofenceAction() {
    override fun onTriggered(context: Context, event: GeofenceEvent) {
        // send notification, log analytics, etc.
    }
}

4. Manage geofences

// list all active geofences
val all: List<Geofence> = Geofencer.geofences.value

// observe changes
Geofencer.geofences.collect { list -> /* update UI */ }

// look up by id
val fence: Geofence? = Geofencer["some-id"]

// remove
Geofencer.remove("some-id")
Geofencer.removeAll()

Location Tracking

1. Start tracking

LocationTracker.start(context) {
    interval = 10.seconds
    fastest = 5.seconds
    displacement = 50f
    action<LocationLogAction>()
}

2. Observe locations

lifecycleScope.launch {
    LocationTracker.locations.collect { location ->
        Log.d("Location", "${location.latitude}, ${location.longitude}")
    }
}

3. Create a custom action

class LocationLogAction : LocationAction() {
    override fun onUpdate(context: Context, result: LocationResult) {
        // persist, upload, etc.
    }
}

4. Stop tracking

LocationTracker.stop(context)

API Reference

Class	Description
Geofencer	Singleton to add/remove geofences and observe events via SharedFlow
Geofence	Data class holding coordinates, radius, transitions, and metadata
GeofenceBuilder	DSL builder for Geofence instances
GeofenceEvent	Emitted event containing the geofence, transition type, and triggering location
GeofenceAction	Abstract class for custom geofence event handlers (survives app kill)
LocationTracker	Singleton to start/stop location updates and observe via SharedFlow
LocationConfig	DSL builder for location request parameters
LocationAction	Abstract class for custom location update handlers (survives app kill)

Permissions

The library declares these permissions in its manifest (merged automatically):

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

Your app must request ACCESS_FINE_LOCATION (and ACCESS_BACKGROUND_LOCATION on Android 10+) at runtime before adding geofences or starting location tracking.

Maestro UI Tests

The demo app includes Maestro flows in the .maestro/ directory.

Prerequisites

1. Install Maestro:

curl -Ls "https://get.maestro.mobile.dev" | bash

2. Connect an Android device or start an emulator.

3. Install the debug build:

./gradlew :app:installDebug

Running the tests

Run all flows in the .maestro/ directory:

maestro test .maestro/

Run a specific flow:

maestro test .maestro/geofence_full_test.yaml

What the test covers

Area	Details
Recording toggle	Toggles location tracking off and on
Battery / Performance	Switches between high-frequency and battery-saving mode
My location	Centers the map on the current position
Map styles	Cycles through all 5 styles (Pokemon GO, Steampunk, Light, Dark 3D, Satellite)
Event log	Opens the bottom sheet, verifies it shows, clears entries, closes
Geofence at current location	Runs the full wizard (location → radius → message)
Search + geofence	Searches for “Alexanderplatz Berlin”, selects the result, completes the wizard

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT License

Copyright (c) 2026 Geofencer Developers

See LICENSE for the full text.