beekon_flutter 0.0.3

Flutter plugin for the Beekon location SDK (Android + iOS).

beekon_flutter

Flutter plugin for the Beekon location SDK. Thin pass-through over the Android .aar and the iOS BeekonKit Swift module.

Hosts read history and observe live state/positions. Writes never cross into Dart — in background, the Flutter engine is not guaranteed to be alive, so the native libraries own the persistence path end-to-end.

Install

dependencies:
  beekon_flutter: ^0.0.3

Native SDKs are pulled in transitively — Android via Maven Central (io.github.wayqteam:beekon), iOS via SwiftPM (BeekonKit from wayqteam/beekon-ios-binary). See the release process docs.

Usage

import 'package:beekon_flutter/beekon_flutter.dart';

await Beekon.instance.initialize();
await Beekon.instance.configure(
  const BeekonConfig(
    preset: BeekonPreset.balanced,
    androidNotification: AndroidNotification(
      channelId: 'beekon-tracking',
      channelName: 'Tracking',
      notificationId: 7411,
      title: 'Beekon',
      text: 'Tracking your location',
      smallIcon: 'ic_launcher',
    ),
  ),
);

// Observe state (replay-1 — late subscribers get the current state).
Beekon.instance.state.listen((BeekonState s) => print(s));

// Observe live positions (broadcast, no replay).
Beekon.instance.positions.listen((Position p) => print(p));

await Beekon.instance.start();
// … later …
await Beekon.instance.stop();

// Read persisted history (works regardless of whether Flutter was alive).
final List<Position> rows = await Beekon.instance.history(
  from: DateTime.now().subtract(const Duration(hours: 1)),
  to: DateTime.now(),
);

Public types

Dart	Mirrors native
Beekon.instance	Beekon (Android object) / Beekon.shared (iOS actor)
BeekonConfig	both
AndroidNotification	Android NotificationConfig (no iOS analogue)
BeekonPreset { saver, balanced, precision }	both
Position	both
sealed BeekonState (Idle/Starting/Tracking/Paused(reason)/Stopped)	both
PauseReason { permissionRevoked, locationDisabled, unknown }	both
sealed BeekonException (PermissionDenied, NotInitialised, NotConfigured, InternalError, plus platform-specific cases)	both

Required platform setup

Android

The plugin's manifest is empty — the SDK AAR's manifest declares the foreground service and all permissions. They merge into your app automatically. Your app's AndroidManifest.xml does NOT need to redeclare them, but doing so is harmless and makes the requirement explicit.

Beekon.instance.start() should be called while the Flutter activity is foregrounded. Android 14+ FGS rules require foreground state for location service type. Calling start() from background will fail with ServiceFailed.

iOS

Flutter version requirement. The iOS native dependency is distributed via Swift Package Manager. This works automatically on Flutter 3.44+ (where SwiftPM is the default). On Flutter 3.32–3.43, consumers must enable SwiftPM once with:

flutter config --enable-swift-package-manager

CocoaPods is not supported. (CocoaPods Trunk goes read-only on 2026-12-02; SwiftPM is the long-term path.)

Add to ios/Runner/Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Why your app needs in-use location.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Why your app needs background location.</string>
<key>UIBackgroundModes</key>
<array>
  <string>location</string>
</array>

Without these, iOS silently refuses background fixes.

Caveats

• Root isolate only. Beekon.instance works on the main Flutter isolate. Method channels are not auto-wired into background isolates (flutter_workmanager and similar are not supported in v0.1).
• Live streams stop in background. When the Flutter engine is suspended, state and positions go quiet. Native persistence keeps running. Use history(from, to) to retrieve points captured while you weren't subscribed.
• Hot restart. The Dart-side singleton is recreated; the EventChannel re-subscribes natively. In-flight Futures from the previous Dart VM are orphaned. All operations are designed to be idempotent.
• shutdown() is for full process exit. Don't call it on hot-reload teardown.
• EventChannel buffering is best-effort. Native side caps at 64 (matches the iOS/Android SharedFlow/AsyncStream config). A slow Dart consumer can still see drops — use history(from, to) if you need complete coverage.

Layout

beekon_flutter/
├── pubspec.yaml
├── pigeons/beekon_messages.dart      # Pigeon spec — re-generate via tool/pigeon.sh
├── lib/                              # public Dart API
├── android/                          # Kotlin plugin glue (depends on the .aar)
├── ios/                              # Swift plugin glue (SwiftPM only)
└── example/                          # Flutter sample app

See REQUIREMENTS.md for the cross-platform behavioural contract.