This plugin brings the Traccar Client SDK to Flutter applications. It provides background location tracking on Android and iOS, uploading positions over the same simple HTTP protocol used by Traccar and compatible servers. The plugin is a thin layer over the native SDK, so its behavior, configuration, and reliability characteristics are those described on the main SDK page; this guide covers what is specific to Flutter.
The plugin supports Android API level 24 and above and iOS 15 and above.
Add the plugin to your pubspec.yaml:
dependencies:
traccar_client_sdk: ^1.0.5
Create a tracker and initialize it with a configuration that specifies the server address and a device identifier. Initialization is idempotent, so it is safe to call on every launch; use setConfig afterwards to change settings on a tracker that is already running.
import 'package:traccar_client_sdk/traccar_client_sdk.dart';
final tracker = TraccarClientSdk();
await tracker.init(Config(
serverUrl: 'https://demo.traccar.org',
deviceId: '123456',
));
await tracker.start();
Call tracker.stop() to stop tracking. Starting requires location permission; if it is denied, start throws a PlatformException.
The plugin exposes the full SDK surface as asynchronous methods:
init(Config) initializes the tracker, and is safe to call repeatedly.setConfig(Config) replaces the configuration of a running tracker.start() begins tracking, requesting any missing permissions first.stop() stops tracking while retaining the saved configuration.requestPosition({String? alarm}) takes a single fix and uploads it independently of start and stop, returning whether the upload succeeded. The optional alarm tags the report with the Traccar alarm field.isTracking() reports whether tracking is currently active.getLogs() returns recent diagnostic entries, each with a timestamp in milliseconds and a message.clearLogs() empties the diagnostic log.The Config object accepts the same fields as the native SDK. It contains a LocationConfig with the location pipeline parameters, a buffer flag that switches between reliable queued upload and real-time-only delivery, the Android-only wakeLock and preferPlatformProviders options, and a NotificationConfig for the Android foreground-service text.
See the main SDK page for the full configuration reference, including every field, its default value, and how the accuracy levels map to each platform.
On Android the plugin requests the location, notification, and activity-recognition permissions at runtime, and on the first start it opens the battery-optimization exemption screen once. No manifest changes are required.
On iOS, add the following keys to your app's Info.plist:
NSLocationAlwaysAndWhenInUseUsageDescriptionNSLocationWhenInUseUsageDescriptionNSMotionUsageDescriptionThen enable the Location updates background mode in your target's capabilities. If you set heartbeatIntervalSeconds, also add fetch to the background modes and register org.traccar.client.heartbeat under BGTaskSchedulerPermittedIdentifiers; iOS schedules those wakes at its own discretion.