Tracelet #

Production-grade background geolocation for Flutter — fully open-source.

Battery-conscious motion-detection intelligence, geofencing, SQLite persistence, HTTP sync, and headless Dart execution for iOS & Android.

Features #

• Background location tracking — continuous GPS with configurable distanceFilter and desiredAccuracy
• Motion-detection intelligence — accelerometer + activity recognition automatically toggle GPS to save battery
• Geofencing — circular geofences with enter/exit/dwell events
• SQLite persistence — all locations stored locally, queryable
• HTTP auto-sync — batch upload with retry, exponential backoff, offline queue
• Headless execution — run Dart code in response to background events
• Scheduling — time-based tracking windows (e.g., "Mon–Fri 9am–5pm")
• Start on boot — resume after device reboot
• Debug sounds — audible feedback during development

Quick Start #

1. Add the dependency #

dependencies:
  tracelet: ^0.1.0

2. Platform setup #

• Android Setup Guide
• iOS Setup Guide

3. Use the API #

import 'package:tracelet/tracelet.dart' as tl;

// 1. Subscribe to events
tl.Tracelet.onLocation((tl.Location location) {
  print('${location.coords.latitude}, ${location.coords.longitude}');
});

tl.Tracelet.onMotionChange((tl.Location location) {
  print('Moving: ${location.isMoving}');
});

// 2. Initialize
final state = await tl.Tracelet.ready(tl.Config(
  geo: tl.GeoConfig(
    desiredAccuracy: tl.DesiredAccuracy.high,
    distanceFilter: 10.0,
  ),
  app: tl.AppConfig(
    stopOnTerminate: false,
    startOnBoot: true,
  ),
  logger: tl.LoggerConfig(
    debug: true,
    logLevel: tl.LogLevel.verbose,
  ),
));

// 3. Start tracking
await tl.Tracelet.start();

API Overview #

Lifecycle #

Location #

Geofencing #

Persistence & Sync #

Events #

Configuration #

Configuration is organized into logical groups:

Config(
  geo: GeoConfig(                    // Location accuracy & sampling
    desiredAccuracy: DesiredAccuracy.high,
    distanceFilter: 10.0,
    stationaryRadius: 25.0,
  ),
  app: AppConfig(                    // Lifecycle behavior
    stopOnTerminate: false,
    startOnBoot: true,
    heartbeatInterval: 60,
  ),
  http: HttpConfig(                  // Server sync
    url: 'https://example.com/locations',
    method: HttpMethod.post,
    autoSync: true,
    batchSync: true,
  ),
  motion: MotionConfig(              // Motion detection
    stopTimeout: 5,
  ),
  geofence: GeofenceConfig(          // Geofence behavior
    geofenceProximityRadius: 1000,
    geofenceInitialTriggerEntry: true,
  ),
  logger: LoggerConfig(              // Logging
    debug: true,
    logLevel: LogLevel.verbose,
    logMaxDays: 3,
  ),
)

Architecture #

This is the app-facing package in a federated plugin:

License #

Apache 2.0 — see LICENSE for details.