beekon_flutter 0.6.0
beekon_flutter: ^0.6.0 copied to clipboard
Flutter plugin for the Beekon location SDK (Android + iOS).
[Beekon]
beekon_flutter
Background location tracking for Flutter.
Keeps working in the background — and after the app is closed.
Docs · getbeekon.com · GitHub
Beekon tracks location on Android and iOS — in the foreground, in the background, and after the app is swiped away. Every fix lands in a 7-day on-device history you can query any time. Point it at a backend you control and it uploads for you; leave that unset and nothing ever leaves the device.
Features #
- 📍 Background tracking — keeps logging in the background and after termination
- 🔋 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 own endpoint
- 📊 Rich fixes — accuracy, speed, bearing, altitude, motion, and activity
- 🪵 Diagnostic logging — on-device log buffer, runtime level, NDJSON export
Install #
dependencies:
beekon_flutter: ^0.6.0
minSdk 26 (Android 8) · iOS 17+. See Setup for the per-platform OS config.
Quick start #
import 'package:beekon_flutter/beekon_flutter.dart';
// Configure is optional — these are the defaults.
await Beekon.instance.configure(
BeekonConfig.local(
tracking: TrackingConfig(
minTimeBetweenLocationsSeconds: 30,
minDistanceBetweenLocationsMeters: 100,
),
),
);
// Receive live fixes.
Beekon.instance.locations.listen((loc) {
print('${loc.latitude}, ${loc.longitude}');
});
// Start tracking. (Request location permission first — see Setup.)
await Beekon.instance.start();
start() and stop() never throw. Watch state for 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.
}
});
Send to your backend #
Give Beekon an endpoint and it uploads fixes for you — batched, in the background, with automatic retries. Without a sync config, all data stays on the device.
await Beekon.instance.configure(
BeekonConfig.custom(
sync: SyncConfig(url: 'https://api.example.com/locations'),
),
);
Your server receives a small JSON envelope and acknowledges it with a status code. Build your ingest endpoint is a complete, working example. Need authenticated uploads? Pass SyncConfig.auth and the SDK attaches and refreshes the token natively, even in the background — see Auth & token refresh.
Tag each fix with your own user: await Beekon.instance.setUserId('usr_8f3a2c'). Send an opaque stable identifier (a database key), never an email or phone number: Beekon Cloud stores the id as sent.
More #
// One-shot fix, independent of tracking (null on timeout).
final fix = await Beekon.instance.getCurrentLocation(
timeout: const Duration(seconds: 15),
);
// Query the on-device history.
final fixes = await Beekon.instance.getLocations(
from: DateTime.now().subtract(const Duration(days: 1)),
to: DateTime.now(),
);
// Geofences — enter/exit events survive app launches.
await Beekon.instance.addGeofences([
const BeekonGeofence(id: 'home', latitude: 37.7749, longitude: -122.4194, radiusMeters: 150),
// Attach a notification and the SDK renders it natively at crossing time —
// offline, and even when the app is killed.
const BeekonGeofence(
id: 'office',
latitude: 37.7858,
longitude: -122.4064,
radiusMeters: 200,
notification: GeofenceNotification(
onEnter: NotificationContent(
title: 'Welcome to the office',
body: 'Clocking you in.',
deepLink: 'myapp://office/checkin',
),
onExit: NotificationContent(title: 'Heading out', body: 'See you tomorrow.'),
// delivery defaults to NotificationDelivery.local (offline, device-rendered).
),
),
]);
Beekon.instance.geofenceEvents.listen((e) => print('${e.type.name} → ${e.geofenceId}'));
// Pre-start permission check (the app still owns the request).
final status = await Beekon.instance.getPermissionStatus();
// Permission "doctor" — what the *current config* actually needs. Call after
// configure(); read-only, never prompts. start() does not preflight permissions.
for (final req in await Beekon.instance.getRequiredPermissions()) {
if (!req.satisfied) {
print('${req.permission.name} (${req.importance.name}): ${req.rationale}');
}
}
// Diagnostics — runtime level, live tail, NDJSON export for bug reports.
await Beekon.instance.setLogLevel(LogLevel.debug);
final logPath = await Beekon.instance.exportLog();
License (optional) #
A license key is optional and purely observational — an absent, expired, or invalid key never blocks, degrades, or delays tracking. Supply one and watch the status:
await Beekon.instance.configure(
// App- and product-bound, so it's safe to commit to source control.
BeekonConfig.local(licenseKey: 'eyJ…'),
);
// One-shot, or subscribe to Beekon.instance.licenseStatusUpdates for live changes.
final LicenseStatus status = await Beekon.instance.licenseStatus();
// NotDetermined | Licensed(tier, entitlements) | Evaluation | Expired
// | UpdateEntitlementLapsed | Invalid(reason)
Without a key, Beekon runs in evaluation mode — fully functional. Details: docs.getbeekon.com/reference/licensing.
Full API and guides: docs.getbeekon.com.
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(orACCESS_COARSE_LOCATION)POST_NOTIFICATIONSon 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>com.getbeekon.sdk.sync</string>
</array>
iOS uses Swift Package Manager. On Flutter older than 3.44, enable it once:
flutter config --enable-swift-package-manager
Device integrity · Beekon Cloud only
In cloud mode the native SDK can prove that uploads come from your genuine app on a real device
(hardware key attestation on Android, App Attest on iOS). It attests in the background, at most
once a day, and never blocks or delays tracking. A device that can't attest (an emulator or
simulator, for example) stays unverified. There is no Dart API for it. Requires native 0.6.0.
iOS: add the App Attest capability to the Runner target (Xcode → Signing & Capabilities →
- Capability → App Attest), so
ios/Runner/Runner.entitlementscontains:
<key>com.apple.developer.devicecheck.appattest-environment</key>
<string>production</string>
Use production for App Store, TestFlight, ad-hoc and Enterprise builds. Without the
capability the app still tracks and syncs, but its uploads stay unverified.
Android: no setup in the app. The SDK attests with hardware key attestation: a per-install Android Keystore key whose certificate chain the device's secure hardware signs. Beekon Cloud checks the signing certificate the device reports against your app identity, so register it in the console: for apps installed from Google Play that is the Play App Signing certificate; register any other certificate used for builds that should attest too (sideloaded, internal-store or debug builds).
The SDK keeps its install id out of backup and device transfer by itself, and its manifest sets
no backup attributes, so your own android:fullBackupContent / android:dataExtractionRules
merge as they are (no tools:replace). Optionally, to keep the SDK's prefs out of your app's
backup payload, add these lines to your rules (inside <full-backup-content>, and inside both
<cloud-backup> and <device-transfer> of <data-extraction-rules>):
<exclude domain="sharedpref" path="beekon_prefs.xml" />
<exclude domain="sharedpref" path="beekon_secure_prefs.xml" />
<exclude domain="sharedpref" path="beekon_cloud_secure_prefs.xml" />
<exclude domain="sharedpref" path="beekon_headers_secure_prefs.xml" />
Register your app's identities and choose whether to require attestation in the console, under Project settings → App integrity.
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.
Beekon Cloud #
Prefer managed ingest, a console, and server-owned config instead of running your own backend? Beekon Cloud is in private beta — see the docs.
License #
Beekon is licensed for evaluation use. See LICENSE, or contact WayQ Technologies for production licensing.
© WayQ Technologies Pvt Ltd