geohawk 0.1.5

Resilient Android background location tracking — foreground service, watchdog/boot restart, offline cache, and OEM auto-start helpers.

geohawk

Resilient Android background location tracking for Flutter. Built around a typed FOREGROUND_SERVICE_TYPE_LOCATION service with a watchdog alarm, boot restart, offline disk cache, optional HTTPS upload, and OEM auto-start helpers.

Android-only. On iOS / web / desktop the API is a no-op and start() returns false. If you need cross-platform foreground location, pair this with a different plugin per platform.

Install

dependencies:
  geohawk: ^0.1.0

minSdk 24, compileSdk 36. The plugin's AndroidManifest.xml declares every permission it needs (ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION, ACCESS_BACKGROUND_LOCATION, FOREGROUND_SERVICE, FOREGROUND_SERVICE_LOCATION, POST_NOTIFICATIONS, WAKE_LOCK, RECEIVE_BOOT_COMPLETED, REQUEST_IGNORE_BATTERY_OPTIMIZATIONS, INTERNET). They auto-merge into your app — you don't need to redeclare them.

Quick start

import 'package:geohawk/geohawk.dart';

final geohawk = Geohawk.instance;

await geohawk.start(
  interval: const Duration(seconds: 30),
  maxInterval: const Duration(seconds: 60),
  distanceFilterMeters: 0,
  endpointUrl: 'https://your.api/track',
  authHeaders: {'Authorization': 'Bearer $token'},
  notificationTitle: 'Trip in progress',
  notificationText: 'Sharing your location',
);

geohawk.onLocationUpdate.listen((fix) {
  print('${fix.latitude}, ${fix.longitude} (±${fix.accuracy}m)');
});

// Update the foreground notification at any time while running.
await geohawk.updateNotification(text: '12 km · 22 min');

await geohawk.stop();

Runtime permissions

start() checks ACCESS_FINE_LOCATION / ACCESS_COARSE_LOCATION and, if not granted, prompts the user via the bound Activity (Android 13+ also prompts for POST_NOTIFICATIONS). Returns false if the user denies. You don't need to call any other permission library before start() — but if you want to pre-prompt with rationale UI, request location permission yourself first and start() will skip the prompt.

ACCESS_BACKGROUND_LOCATION is not requested by start(). Android requires that as a separate, settings-screen prompt after the foreground grant. Request it yourself from a dedicated screen with prominent disclosure before calling start() if you need true background tracking.

API

Method	Notes
start(...)	Starts the foreground service; returns true on success.
stop()	Stops the service, watchdog, wake lock; cancels boot restart.
updateNotification({title,text,icon})	Updates the FGS notification in place. No restart.
isRunning()	Reads persisted running flag — survives process death.
pendingCacheCount()	Number of fixes buffered on disk (uploads failed or no endpoint set).
requestBatteryOptimizationExemption()	Deep-links to the system battery-exemption prompt.
openAutoStartSettings()	Opens OEM auto-start screen (Xiaomi/Oppo/Vivo/Huawei). false if N/A.
onLocationUpdate	Broadcast Stream<LocationFix>.

LocationFix carries latitude, longitude, accuracy, timestampMs.

Resilience

• Watchdog alarm runs every minute via AlarmManager and restarts the service if it's been killed.
• Boot receiver restarts on BOOT_COMPLETED, LOCKED_BOOT_COMPLETED, and MY_PACKAGE_REPLACED when isRunning() was true.
• Disk cache buffers fixes when the upload endpoint is unreachable and drains opportunistically.
• Wake lock is held while updates are being delivered to prevent doze.

Play Store policy

Apps using this plugin must:

1. Submit the Play Console Location Permission Declaration if requesting ACCESS_BACKGROUND_LOCATION. Background location is on Google's restricted list — your justification must match an approved use case.
2. Show prominent disclosure before the foreground location prompt (Android 14+ requirement).
3. Justify REQUEST_IGNORE_BATTERY_OPTIMIZATIONS — Google only allows this for limited app categories. Call requestBatteryOptimizationExemption() only when justified.

The watchdog and on-task-removed restart use inexact alarms (setAndAllowWhileIdle), so no SCHEDULE_EXACT_ALARM / USE_EXACT_ALARM permission is required.

Example

See example/ for a Flutter app that demonstrates start/stop/updateNotification, shows the live fix, and pending-cache count.

License

See LICENSE.