locus 2.0.0

Background geolocation SDK for Flutter. Native tracking, geofencing, activity recognition, and sync.

Locus

Reliable background geolocation for Flutter apps.
Service-based v2.0.0 API covering tracking, geofencing, sync, privacy, and battery on Android and iOS.
Built for production: deterministic APIs, full test suite, and migration tooling from v1.

---

Key Features

• Continuous Tracking: Reliable background updates with adaptive filters.
• Motion Recognition: Activity detection (walking, running, driving, stationary).
• Geofencing: Circular and polygon geofences with enter/exit/dwell detection.
• Polygon Geofences: Define complex boundaries with arbitrary shapes.
• Geofence Workflows: Multi-step geofence sequences with timeouts.
• Privacy Zones: Exclude, obfuscate, or reduce accuracy in sensitive areas.
• Trip Detection: Automatic trip start/end detection with route recording.
• Battery Optimization: Adaptive profiles based on speed, activity, and battery level.
• Automated Sync: HTTP synchronization with retry logic and batching.
• Offline Reliability: SQLite persistence to prevent data loss.
• Headless Execution: Execute background logic even when the app is terminated.

Documentation

For full documentation, visit locus.dev or check the local docs folder:

• Quick Start - Get running in 5 minutes.
• Migration (v1.x to v2.0) - Move to the service-based API.
• Architecture - Project structure and design.
• Configuration - Configuration options and presets.
• Geofencing - Circular and polygon geofences.
• Privacy Zones - Location privacy features.
• Trip Tracking - Trip detection and recording.
• Battery Optimization - Adaptive tracking.
• Platform Setup - iOS & Android permissions.
• Troubleshooting - Common issues and fixes.
• FAQ - Frequently asked questions.
• Headless Execution - Running logic when the app is terminated.
• Platform Behaviors - Android/iOS runtime differences.
• HTTP Synchronization - Request formats, retry, and batching.
• Performance Optimization - Tuning for battery and accuracy.
• Activity Recognition - Activity types and best practices.
• Event Streams Reference - When streams emit and how to subscribe safely.
• Error Codes - Exception types and recovery guidance.

Quick Start

1. Installation

dependencies:
  locus: ^2.0.0

2. Basic Setup

import 'package:locus/locus.dart';

void main() async {
  // 1. Initialize
  await Locus.ready(ConfigPresets.balanced.copyWith(
    url: 'https://api.yourservice.com/locations',
  ));

  // 2. Start tracking
  await Locus.start();

  // 3. Listen to updates
  Locus.location.stream.listen((location) {
    print('Location: ${location.coords.latitude}, ${location.coords.longitude}');
  });
}

3. Add Geofences

// Circular geofence
await Locus.geofencing.add(Geofence(
  identifier: 'office',
  latitude: 37.7749,
  longitude: -122.4194,
  radius: 100,
  notifyOnEntry: true,
  notifyOnExit: true,
));

// Polygon geofence
await Locus.geofencing.addPolygon(PolygonGeofence(
  identifier: 'campus',
  vertices: [
    GeoPoint(latitude: 37.7749, longitude: -122.4194),
    GeoPoint(latitude: 37.7759, longitude: -122.4184),
    GeoPoint(latitude: 37.7769, longitude: -122.4204),
  ],
));

Project Tooling

Locus includes a CLI to help with configuration and diagnostics:

# Automate native permission setup
dart run locus:setup

# Run environment diagnostics
dart run locus:doctor

# Migration helper (v1.x to v2.0)
dart run locus:migrate --dry-run

Versioning

• Current release: v2.0.0 (service-based API)
• Supports Flutter 3.x / Dart 3.x
• See CHANGELOG.md for details

Tree Shaking

Locus v2.0 is service-based and designed to tree shake unused features in release builds. To keep your app lean:

• Import only what you need from the public barrels.
• Avoid referencing service getters you do not use.

Example:

import 'package:locus/locus.dart' show Locus, Config, Geofence, GeoPoint;

Future<void> initTracking() async {
  await Locus.ready(const Config());
  await Locus.start();
  await Locus.geofencing.add(Geofence(
    identifier: 'office',
    latitude: 37.7749,
    longitude: -122.4194,
    radius: 100,
  ));
}

Architecture

Locus uses a feature-first architecture:

lib/src/
├── features/
│   ├── location/      # Core location tracking
│   ├── geofencing/    # Circular & polygon geofences
│   ├── battery/       # Battery optimization
│   ├── privacy/       # Privacy zones
│   ├── trips/         # Trip detection
│   ├── sync/          # HTTP sync
│   ├── tracking/      # Tracking profiles
│   └── diagnostics/   # Debug tools
├── shared/            # Common models
├── core/              # Infrastructure
└── config/            # Configuration

License

Locus is licensed under the PolyForm Small Business License 1.0.0.

• Free for individuals and small businesses (< $250k annual revenue).
• Professional/Enterprise licenses available for larger organizations.

See LICENSE and LICENSING.md for full terms.