geofence_sdk

Geofencing for Flutter over native iOS & Android region monitoring. Fences are managed on the server (the GeofenceKit dashboard) and synced to the device — the SDK registers the nearest ones with the OS and delivers enter / exit / dwell events in the background, even when your app is suspended or terminated.

All logic lives in the native Swift and Kotlin cores; the Dart layer is a thin MethodChannel wrapper.

Features

  • Server-managed fences — define zones once in the dashboard; devices pull the nearest ones on start() (bounded by fenceLimit).
  • Background monitoring — Core Location region monitoring on iOS, the Geofencing API on Android.
  • Offline queue — transitions captured without connectivity are persisted and flushed when the network returns.
  • Local notifications on geofence transitions.
  • iOS + Android behind one small Dart API.

Install

flutter pub add geofence_sdk

or add it to pubspec.yaml:

dependencies:
  geofence_sdk: ^0.2.0

Quick start

import 'package:geofence_sdk/geofence_sdk.dart';

final sdk = GeofenceSdk();

// 1. Configure once, before any other call.
await sdk.configure(const GeofenceConfig(
  baseUrl: 'https://api.geofencekit.com',
  apiKey: 'sdk_xxxxxxxxxxxxxxxxxxxxxxxx', // your SDK key from the dashboard
  userId: 'user_42',                     // optional: ties events to a user
));

// 2. Ask for location (and notification) permission.
final status = await sdk.requestPermissions();
if (status == PermissionStatus.grantedAlways) {
  // 3. Sync + register the nearest fences and start monitoring.
  final fences = await sdk.start();
  print('Monitoring ${fences.length} fence(s)');
}

// Later, to stop monitoring:
await sdk.stop();

Background enter/exit/dwell monitoring requires Always location permission. With only grantedForeground the OS delivers transitions solely while the app is in the foreground.

API

GeofenceSdk

Method Returns Description
configure(GeofenceConfig config) Future<void> Configure the SDK. Call first, before anything else.
requestPermissions() Future<PermissionStatus> Prompt for location (and notification) permission. iOS runs the two-step When-In-Use → Always flow; on Android the host Activity drives the dialogs.
permissionStatus() Future<PermissionStatus> Current permission status without prompting.
start() Future<List<Fence>> Sync the nearest fences, register them with the OS, start monitoring, and return the registered fences.
stop() Future<void> Remove regions and stop monitoring.

GeofenceConfig

Field Type Description
baseUrl String (required) Backend base URL, e.g. https://api.geofencekit.com.
apiKey String (required) SDK key from the dashboard.
userId String? Associates events with a user.
fenceLimit int? Max number of fences to register with the OS at once.
resyncDistanceM int? Distance (meters) the device may travel before re-syncing fences.

Fence

id, name, latitude, longitude, radiusM, and distanceM (distance from the device at sync time, when available).

PermissionStatus

grantedAlways, grantedForeground, denied, notDetermined.

Platform setup

The plugin cannot declare these for you — add them to your host app.

iOS — ios/Runner/Info.plist

<key>NSLocationWhenInUseUsageDescription</key>
<string>We use your location to monitor geofences.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Background location lets us notify you when you enter or leave a zone.</string>
<key>UIBackgroundModes</key>
<array>
  <string>location</string>
</array>

Minimum iOS deployment target: 14.0.

Android — android/app/src/main/AndroidManifest.xml

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

Register the SDK's GeofenceBroadcastReceiver and BootReceiver inside your <application> element, and request the runtime location permissions from your Activity before calling start().

Example

A runnable example lives in example/ — it wires up every method against the live backend. Run it with:

cd example
flutter run

License

MIT — see LICENSE.

Libraries

geofence_sdk
Flutter API for the native Geofence SDK. A thin MethodChannel wrapper — all logic runs in the native Swift (GeofenceSDK) and Kotlin (GeofenceSdk) cores. See bindings/README.md.