beekon_flutter 0.0.9

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

[Beekon]

beekon_flutter

Background location tracking for Flutter.
Keeps working when your app is in the background — or closed.

Docs · Console · getbeekon.com · Umbrella

---

Beekon tracks location reliably on Android and iOS, keeps a 7-day history on the device, and can optionally watch geofences and upload fixes to your server — all from one small, consistent API.

Features

• 📍 Background tracking — keeps logging in the background and after the app is terminated
• 🔋 Battery-aware — accuracy presets and automatic pause while stationary
• 💾 On-device history — 7 days of fixes, queryable any time, survives restarts
• 🗺️ Geofencing — enter/exit events that keep firing across app launches
• ☁️ Server sync — optional batched, self-retrying upload to your endpoint
• 📊 Rich fixes — accuracy, speed, bearing, altitude, motion and activity
• ☁️ Beekon Cloud mode — server-owned config, geofences and license via a bkproj_ project key (BeekonConfig.cloud)
• 🪵 Diagnostic logging — on-device log ring buffer, runtime log level, NDJSON export (getLog/exportLog/setLogLevel/logs)

Install

dependencies:
  beekon_flutter: ^0.0.9

Quick start

import 'package:beekon_flutter/beekon_flutter.dart';

// Configure is optional — these are the defaults.
await Beekon.instance.configure(
  const BeekonConfig.selfManaged(
    minTimeBetweenLocationsSeconds: 30,
    minDistanceBetweenLocationsMeters: 100,
  ),
);

// Receive live fixes.
Beekon.instance.locations.listen((location) {
  print('${location.latitude}, ${location.longitude}');
});

// Start tracking. (Request location permission first — see Setup.)
await Beekon.instance.start();

Starting and stopping never throw. Instead, watch state — it tells you whether tracking is live and why it stopped:

Beekon.instance.state.listen((state) {
  if (state is Stopped && state.reason == StopReason.permissionDenied) {
    // Ask for location permission, then call start() again.
  }
});

On-demand location

Need a single fresh fix right now — without starting a tracking session? getCurrentLocation() returns one immediately. It works whether or not tracking is running, never disturbs an active session, and the fix is returned only here (it is not persisted and does not appear on locations).

final fix = await Beekon.instance.getCurrentLocation(
  timeout: const Duration(seconds: 15),
  accuracy: AccuracyMode.high, // optional — defaults to the configured mode
);
if (fix != null) {
  print('${fix.latitude}, ${fix.longitude}');
}

Returns null if no usable fix arrives within timeout. Throws LocationUnavailable if permission is missing or location services are off.

History

The last 7 days live on the device and survive app restarts — including fixes captured while your app was closed.

final fixes = await Beekon.instance.getLocations(
  from: DateTime.now().subtract(const Duration(days: 1)),
  to: DateTime.now(),
);

Geofences

await Beekon.instance.addGeofences([
  const BeekonGeofence(
    id: 'home',
    latitude: 37.7749,
    longitude: -122.4194,
    radiusMeters: 150,
  ),
]);

Beekon.instance.geofenceEvents.listen((event) {
  print('${event.type.name} → ${event.geofenceId}'); // enter / exit
});

Server sync

Give Beekon an endpoint and it uploads fixes for you — batched, in the background, with automatic retries.

await Beekon.instance.configure(
  const BeekonConfig.selfManaged(
    sync: SyncConfig(url: 'https://api.example.com/locations'),
  ),
);

Need authenticated uploads? Pass SyncConfig.auth: AuthConfig(...) with seed tokens and a refreshUrl, and the SDK attaches the access token and refreshes it natively — proactively before expiry, reactively on 401/403 — even in the background. Rotations surface on Beekon.instance.authChanges (Stream<AuthTokens>); mirror them into your own session store.

License key

Supply a production license token with BeekonConfig.licenseKey (it overrides any value set in the Android manifest or iOS Info.plist). It is safe to commit — the token is bound to your app id and to Flutter.

await Beekon.instance.configure(
  const BeekonConfig.selfManaged(licenseKey: 'eyJ…'), // a license-format-v1 token
);

The license is purely observational — no status ever blocks, degrades, or delays the SDK; without a key it runs in evaluation mode. Read the current status if you want to surface it:

final status = await Beekon.instance.licenseStatus();
final live = Beekon.instance.licenseStatusUpdates; // Stream<LicenseStatus>

switch (status) {
  case Licensed(:final tier):
    print('licensed: $tier');
  case Evaluation():
    print('evaluation mode');
  case Invalid(:final reason):
    print('invalid license: ${reason.name}');
  case _:
    break;
}

Android and iOS verify independently, so the same app may legally report different statuses on each platform.

Setup

Request location permission in your app before calling start(), then add the platform configuration below.

Android  ·  minSdk 26

Beekon merges its permissions and foreground service into your app automatically. At runtime, request:

• ACCESS_FINE_LOCATION (or ACCESS_COARSE_LOCATION)
• POST_NOTIFICATIONS on Android 13+

A notification is shown while tracking — customise it with NotificationConfig.

iOS  ·  iOS 17+

Add to ios/Runner/Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Used to show your location in the app.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Used to keep tracking your trips in the background.</string>
<key>UIBackgroundModes</key>
<array>
  <string>location</string>
  <string>fetch</string>
</array>
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
  <string>in.wayq.beekon.sync</string>
</array>

iOS uses Swift Package Manager. On Flutter older than 3.44, enable it once:

flutter config --enable-swift-package-manager

How it works

Live updates flow to locations only while your app is running, but the native engine keeps recording in the background and stores every fix on the device. That's why getLocations() returns the whole window — there may be gaps in the live stream, but not in your history.

License

Beekon is licensed for evaluation use. See LICENSE, or contact wayqteam for production licensing.

---

© WayQ Technologies Pvt Ltd