Flutter setup

The Flutter plugin is a thin pass-through over the two native libraries. It uses Pigeon for type-safe MethodChannel + EventChannel and never participates in the persistence write path — that lives in the native libraries because background runtimes aren’t guaranteed to be alive.

Add the dependency

pubspec.yaml

dependencies:
  beekon_flutter: ^0.0.3

flutter pub get

Flutter 3.44+ is recommended (default SwiftPM). On 3.32–3.43 enable it once: flutter config --enable-swift-package-manager. CocoaPods is not supported — Beekon’s iOS dependency resolves via SwiftPM only.

Android side

The plugin pulls in io.github.wayqteam:beekon automatically. Your app must declare minSdk = 26 (Beekon’s minimum) and repeat the permissions in your example/app manifest if you want them visible there.

Permissions

android/app/src/main/AndroidManifest.xml

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

Build setup

android/app/build.gradle.kts

android {
  compileOptions {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
  }
  defaultConfig {
    minSdk = 26
  }
}

iOS side

<!-- ios/Runner/Info.plist -->
<key>NSLocationWhenInUseUsageDescription</key>
<string>Used to show your live position in the app.</string>

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Used to keep tracking your trips when the app is in the background.</string>

<key>UIBackgroundModes</key>
<array>
  <string>location</string>
</array>

iOS 17 minimum. The plugin’s iOS dependency resolves via SwiftPM — there’s no Podfile config to maintain.

Configure once

import 'package:beekon_flutter/beekon_flutter.dart';

Future<void> bootstrap() async {
  await Beekon.instance.configure(
    const BeekonConfig(
      intervalSeconds: 30,
      distanceMeters: 100,
      androidNotification: AndroidNotification(
        title: 'Beekon',
        text: 'Tracking your location',
        smallIcon: 'ic_launcher',
      ),
    ),
  );
}

androidNotification is honoured on Android and silently ignored on iOS. All its fields are optional — leave them null to inherit the host app’s label and launcher icon.

smallIcon is the resource name (e.g. 'ic_launcher', 'ic_stat_beekon') — Beekon resolves it via getIdentifier() at runtime. The drawable must exist in your Android res/drawable* folders.

Permissions

Beekon does not request runtime permissions — your app drives the dialog (use permission_handler or platform-channel calls of your own). Android needs locationAlways + notification; iOS needs locationAlways (with the standard two-step whenInUse → always dance).

Start tracking and observe

try {
  await Beekon.instance.start();
} on PermissionDenied {
  // request runtime permissions; on iOS, drive the Always prompt
} on LocationServicesDisabled {
  // Location Services off (or no Google Play Services on Android)
}

Beekon.instance.state.listen((BeekonState s) {
  // Idle, Tracking, or Stopped(reason)
});

Beekon.instance.locations.listen((Location loc) {
  // emits only while Flutter is alive — read history(...) for persisted fixes
});

History reads cross the channel (history(from:, to:) returns Future<List<Location>>); the live stream does not buffer across Flutter-engine restarts.

When start() will fail

Throws	Meaning
PermissionDenied	runtime location permission missing
LocationServicesDisabled	system Location Services off, or no Google Play Services on Android
StorageFailure	SQLite/filesystem failure — log and surface

See Errors for full handling.

Next

• Lifecycle & states — the state machine you’ll observe.
• Background execution — what’s keeping your app alive on each platform.
• Persistence & history — what the history query returns.