Quickstart

Four steps to your first fix: install → configure → start → subscribe. Pick your platform once — the tabs stay synced as you read.

OS permissions first

Beekon ships no permission API — your app requests location (and notification/background) permission itself. The per-OS declarations and runtime flows are on Platform setup.

1. Install

Android

app/build.gradle.kts

dependencies {
  implementation("io.github.beekonlabs:beekon:0.1.1")
}

minSdk 26, JDK 17, Kotlin 2.x. Maven Central is included by default — no extra repository needed.

iOS

In Xcode: File → Add Package Dependencies… and paste:

https://github.com/beekonlabs/beekon-ios-binary.git

Select version 0.1.1 and add BeekonKit to your app target. The package ships as a signed .xcframework — set it to Embed & Sign on your app target. iOS 17 minimum.

Flutter

pubspec.yaml

dependencies:
  beekon_flutter: ^0.1.1

flutter pub get

Dart ^3.9, Flutter >=3.32. Android minSdk 26, iOS 17.

React Native

npm install @wayq/beekon-rn

On iOS, install pods:

cd ios && pod install

Requires the React Native New Architecture (RN 0.76+). Android links automatically.

2. Configure

configure is optional — call it before start() to set the gate. Without it, Beekon uses sensible defaults (30 s / 100 m, balanced, pause). Every field is documented on Configuration.

Android

There’s no initialize(...) — the SDK auto-initializes via AndroidX Startup. Call configure once in Application.onCreate.

import in.wayq.beekon.Beekon
import in.wayq.beekon.BeekonConfig

class App : Application() {
  override fun onCreate() {
    super.onCreate()
    Beekon.configure(
      BeekonConfig.SelfManaged(
        minTimeBetweenLocationsSeconds = 30,
        minDistanceBetweenLocationsMeters = 100.0,
        accuracyMode = AccuracyMode.Balanced,
        whenStationary = StationaryMode.Pause,
        notification = NotificationConfig(
          title = "Tracking location",
          text = "Capturing your trip",
        ),
      ),
    )
  }
}

iOS

There’s no initialize() — Beekon.shared is an actor, auto-initialized. configure is async throws.

import BeekonKit

@main
struct MyApp: App {
  init() {
    Task {
      try await Beekon.shared.configure(
        BeekonConfig.selfManaged(
          minTimeBetweenLocationsSeconds: 30,
          minDistanceBetweenLocationsMeters: 100,
          accuracyMode: .balanced,
          whenStationary: .pause
        )
      )
    }
  }
  var body: some Scene { WindowGroup { ContentView() } }
}

Flutter

There’s no initialize() — the native SDKs auto-initialize. configure is async.

import 'package:beekon_flutter/beekon_flutter.dart';

Future<void> main() async {
  await Beekon.instance.configure(
    const BeekonConfig.selfManaged(
      minTimeBetweenLocationsSeconds: 30,
      minDistanceBetweenLocationsMeters: 100,
      accuracyMode: AccuracyMode.balanced,
      whenStationary: StationaryMode.pause,
    ),
  );
  runApp(const MyApp());
}

React Native

There’s no initialize() — the native SDKs auto-initialize. configure is async.

import { Beekon } from '@wayq/beekon-rn';

await Beekon.configure({
  mode: 'selfManaged',
  minTimeBetweenLocationsSeconds: 30,
  minDistanceBetweenLocationsMeters: 100,
  accuracyMode: 'balanced',
  whenStationary: 'pause',
});

3. Start tracking

start() brings up the platform’s background machinery (Android foreground service, iOS CLBackgroundActivitySession). On native it’s suspend/async and never throws — a missing permission or a platform refusal surfaces as Stopped(reason) on the state stream, not an exception.

Android

lifecycleScope.launch {
  Beekon.start() // never throws
}

iOS

await Beekon.shared.start() // never throws

Flutter

await Beekon.instance.start(); // never throws

React Native

await Beekon.start(); // never throws

4. Subscribe to locations

The locations stream delivers each admitted fix. Consume it the idiomatic way for your platform.

Android

// locations is a SharedFlow (replay 1, DROP_OLDEST)
Beekon.locations.collect { loc ->
  Log.d("beekon", "${loc.latitude}, ${loc.longitude}  acc=${loc.accuracy ?: "—"}m")
}

// observe why tracking stopped, if it does
Beekon.state.collect { s ->
  if (s is BeekonState.Stopped) when (s.reason) {
    StopReason.PermissionDenied -> { /* request permission, then start() again */ }
    StopReason.LocationServicesDisabled -> { /* Location Services off */ }
    else -> {}
  }
}

iOS

Task {
  for await loc in await Beekon.shared.locations {
    let acc = loc.accuracy.map { "\($0)" } ?? "—"
    print("\(loc.latitude), \(loc.longitude)  acc=\(acc)m")
  }
}

// observe why tracking stopped, if it does
Task {
  for await s in await Beekon.shared.state {
    if case let .stopped(reason) = s {
      switch reason {
      case .permissionDenied: break // drive the Always prompt, retry
      case .locationServicesDisabled: break // Location Services off
      default: break
      }
    }
  }
}

Flutter

// Each subscription returns an unsubscribe; on* / .listen both work.
Beekon.instance.locations.listen((loc) {
  print('${loc.latitude}, ${loc.longitude}');
});

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

React Native

// Each subscription returns an unsubscribe function.
const offLocation = Beekon.onLocation((loc) => {
  console.log(loc.latitude, loc.longitude);
});

const offState = Beekon.onState((state) => {
  if (state.kind === 'stopped' && state.reason === 'permissionDenied') {
    // Request permission, then start() again.
  }
});

That’s the whole loop. Fixes also land in an on-device SQLite history that survives process death — read ranges with getLocations(from, to). See Locations & history.

Next

1. Wire the OS-level config: Platform setup.
2. Tune the gate: every field on Configuration.
3. Send fixes to your backend — turn on sync and build the ingest endpoint.
4. Read Lifecycle & states — the state machine behind state.