DOCSEARCHbyAlgolia
Submit Docs

Traccar Client

repository·main·Indexed 41 days ago

https://github.com/traccar/traccar-client

A mobile GPS tracking application for Android and iOS built with Flutter that sends real-time location data to a Traccar server. It features background operation, customizable update intervals, and support for programmatic configuration via URIs, maps, and deep links.

Tokens
2.1K
Snippets
8
Records
10
Agent score
52%

What's inside Traccar Client

  1. Overview of Traccar Client

    main
    Traccar Client is a GPS tracking application for Android and iOS designed to send real-time location updates to a Traccar server. It operates in the background and allows for high customization of update intervals, accuracy, and data usage. The app is privacy-focused, sending data only to the server address you specify.

  3. Set up Traccar Client for tracking

    main

    To start tracking your device, follow these steps:

    1. Install the app on your Android or iOS device.
    2. Enter your Traccar server address in the app configuration.
    3. Grant the necessary location permissions.
    4. The app will then automatically send periodic location reports in the background.

  4. Control Traccar Client via Deep Links

    main

    The Traccar Client supports deep linking via URI schemes to perform specific actions or configure the application.

    Action Links

    Links with the host action can trigger geolocation tracking directly:

    • [scheme]://action/start: Starts the geolocation tracker.
    • [scheme]://action/stop: Stops the geolocation tracker.

    Note: These actions may fail with a PlatformException if permissions are denied or if there is a startup error.

    Configuration Links

    Other URIs are treated as configuration updates. When a non-action URI is received:

    1. An alert dialog is shown to the user with a configuration message.
    2. If the user confirms, ConfigurationService.applyUri(uri) is called to apply the new settings.
    3. The MainScreen is refreshed to reflect changes.
    // Example Action URIs:
[scheme]://action/start
[scheme]://action/stop

// Example Configuration URI:
[scheme]://your-server.com/config-params

  5. Initialize Traccar Client services

    main

    The application entrypoint performs a sequence of asynchronous initializations required for the client to function correctly. If you are integrating or extending the startup logic, ensure the following services are initialized in order:

    1. Firebase.initializeApp(): Initializes Firebase for crash reporting.
    2. Preferences.init(): Loads local user preferences.
    3. GeolocationService.tracker.init(Preferences.buildConfig()): Initializes the GPS tracking engine using the loaded configuration.
    4. PasswordService.migrate(): Handles migration of stored credentials.
    5. PushService.init(): Sets up push notification handling.
    6. ManagedConfigService.init(): Initializes managed configuration settings.
    void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  // ... error handling ...
  await Preferences.init();
  await GeolocationService.tracker.init(Preferences.buildConfig());
  await PasswordService.migrate();
  await PushService.init();
  await ManagedConfigService.init();
  runApp(const MainApp());
}

  6. Build a Config object from local preferences

    main

    Once initialized, use Preferences.buildConfig() to generate a Config object. This object is populated with the current values stored in the device's local storage, including server URL, device ID, and location settings. This is the primary way to retrieve the application's current operational state.

    await Preferences.init();
final config = Preferences.buildConfig();
print(config.serverUrl);

  7. Initialize the Preferences service

    main

    Before accessing or building configurations, you must initialize the Preferences service. This ensures the underlying SharedPreferencesWithCache instance is created and the local storage is ready. Call Preferences.init() and await its completion.

    await Preferences.init();

  8. Configure the Traccar Client via URI or Map

    main

    The ConfigurationService allows you to programmatically configure the client's settings (such as server URL, reporting interval, and accuracy) using either a Uri or a Map<String, dynamic>.

    • Using a URI: Use applyUri(Uri uri) to parse configuration from a URI. If the scheme is http or https, the origin and path are used as the server URL. Otherwise, it looks for a url query parameter.
    • Using a Map: Use applyManagedConfig(Map<String, dynamic> config) or applyParameters(Map<String, dynamic> parameters, {String? url}) to apply settings directly from a configuration map.
    // Example: Applying configuration from a Map
await ConfigurationService.applyParameters({
  'url': 'https://your-traccar-server.com',
  'id': 'device_id_123',
  'interval': 60,
  'accuracy': 'high',
});

// Example: Applying configuration from a URI
await ConfigurationService.applyUri(Uri.parse('https://your-traccar-server.com/config?id=device_id_123&interval=60'));

  9. Reference: Configuration Parameter Keys

    main

    When passing a configuration map to ConfigurationService.applyParameters, use the following keys to set specific client behaviors. Note that types must match the expected format (String, int, or bool).

    ### String Parameters
- `id`: The unique identifier for the device.
- `accuracy`: The GPS accuracy setting.
- `url`: The server address (can be passed separately or within the map).

### Integer Parameters
- `distance`: Distance threshold for updates.
- `interval`: Time interval between updates.
- `angle`: Angle threshold for updates.
- `heartbeat`: Heartbeat interval.

### Boolean Parameters
- `buffer`: Whether to buffer data.
- `wakelock`: Whether to use a wakelock to keep the device active.
- `stopDetection`: Whether to stop detection.
- `preferPlatformProviders`: Whether to prefer platform-specific location providers.

  10. Reference: Preference keys

    main

    The following keys are used by the Preferences class to store and retrieve configuration data in local storage:

    static const String id = 'id';
static const String url = 'url';
static const String accuracy = 'accuracy';
static const String distance = 'distance';
static const String interval = 'interval';
static const String angle = 'angle';
static const String heartbeat = 'heartbeat';
static const String buffer = 'buffer';
static const String wakelock = 'wakelock';
static const String stopDetection = 'stop_detection';
static const String preferPlatformProviders = 'prefer_platform_providers';
static const String password = 'password';