baaba_location #

Foreground location for Flutter that never throws. One call runs the whole flow — permission, location services, precision, the fix, a fallback to the last known location, and the address — and returns one typed result.

final result = await BaabaLocation.instance.get(withAddress: true);

if (result.isSuccess) {
  print(result.address?.formatted ?? result.position);
} else if (result.failure!.resolution != LocationResolution.none) {
  await BaabaLocation.instance.resolve(result.failure!); // one button: "Turn on location"
}

• The package does the work. get() asks for permission (rationale, prompt, Settings with steps, via baaba_permission_handler), turns location on, upgrades to precise when the profile needs it, reuses a recent fix, falls back to the last known location, and looks up the address. result.steps says what it did.
• Two dialogs never stack. Several get() calls at once — two widgets on one screen — share one flow.
• A last known location that is almost always there. The package keeps its own copy, and picks the newer of it and the OS's.
• Filters drop bad accuracy, impossible jumps, mocked fixes, 0,0 and duplicates before your code sees them.
• Geocoding with the hard parts handled: a queue, back-off when throttled, a cache, locales (ur-PK addresses), cancellation, and pluggable providers with fallbacks.
• A setup doctor. diagnose() prints exactly what to add to your manifest or Info.plist.
• Nothing throws. Every failure is a typed LocationFailure with a resolution, reported once to your observer.
• A test double (FakeBaabaLocation) that runs the real flow without a device.

Built on geolocator and geocoding. Android and iOS; on web and desktop every call returns notApplicable.

Contents #

• 60-second setup
• Platform setup per feature
• Choosing a profile
• Getting a location
• Streams
• Background tracking (opt-in)
• Last known location
• Geocoding
• Permissions
• Setup doctor
• Error handling
• Troubleshooting
• Gotchas
• Testing
• Configuration reference

60-second setup #

1. Add the package.

dependencies:
  baaba_location: ^0.1.0

2. Android — android/app/src/main/AndroidManifest.xml, inside <manifest>:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

and in android/app/build.gradle(.kts): compileSdk = 37 (needed by permission_handler, through baaba_permission_handler).

3. iOS — ios/Runner/Info.plist, inside <dict>:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Your location is used to show where you are.</string>

4. Call it.

final result = await BaabaLocation.instance.get(withAddress: true);

No init needed. If something is missing, the result is a misconfigured failure whose details['fix'] is the exact snippet to add — and BaabaLocation.instance.diagnose() prints a checklist.

Platform setup per feature #

baaba_location declares no permissions of its own. Your app declares exactly what it uses:

What merges into your app from the plugins: geolocator's GeolocatorLocationService element (a location foreground service, started only by BackgroundLocation) and the Play services meta-data. No permissions — tool/check_merged_manifest.sh builds the example and fails if ACCESS_BACKGROUND_LOCATION or a library-added foreground-service permission appears.

ACCESS_BACKGROUND_LOCATION and "Always" permission are never needed.

Choosing a profile #

Profiles set accuracy, interval, distance filter, filters and precision together. Accuracy is always your choice: override it per call (get(accuracy: LocationAccuracy.high)) or copy a profile (LocationProfile.delivery.copyWith(interval: Duration(seconds: 10))).

For attendance with a tight radius, use LocationProfile.checkIn.copyWith(accuracy: LocationAccuracy.high).

Getting a location #

final r = await BaabaLocation.instance.get(
  profile: LocationProfile.checkIn,
  withAddress: true,
  locale: const Locale('ur', 'PK'),   // address language
  context: context,                    // optional: where dialogs appear
);

The flow, in order — each step only when needed:

1. Configuration — a missing manifest / Info.plist entry fails with misconfigured before anything is asked (on iOS that would otherwise be a silent denial).
2. Permission — the baaba_permission_handler flow. handlePermission: false skips it; LocationConfig.permissionStep replaces it with your own UI.
3. Services — Android's in-app "turn on location" dialog (with Play services), otherwise a dialog that opens location settings and waits for the return. Switching location on from the notification shade also counts. handleServices: false skips it.
4. Precision — if the profile wants precise and only approximate is allowed, it asks once; if the user keeps approximate, the result is still a success with isApproximate: true (or approximateOnly for PrecisionNeed.required).
5. Fix — a fix younger than the profile's maxAge is reused without waking the GPS (source: cached), otherwise one is requested.
6. Fallback — no fix in time? The last known location up to maxFallbackAge (30 min) is returned as a success, source: lastKnownOs or lastKnownStored, with its age.
7. Address — with withAddress. A geocoding failure never fails the result: address is null and addressFailure says why.

LocationResult carries position, address, addressFailure, source, age, isApproximate, isMocked, and steps. Read position only after isSuccess (or use positionOrNull).

The widget for the common case:

LocationBuilder(
  withAddress: true,
  builder: (context, result) =>
      Text(result.address?.formatted ?? result.position.toString()),
  // loadingBuilder / failureBuilder are optional; the default failure view
  // shows the message and a button that runs resolve(failure).
)

Streams #

// High level: setup once, then results (with the address if asked).
BaabaLocation.instance.watch(profile: LocationProfile.delivery, withAddress: true);

// Low level: fixes only, no UI.
BaabaLocation.instance.positionStream(
  accuracy: LocationAccuracy.high,
  distanceFilter: 20,
  interval: const Duration(seconds: 5),
);

• Every listener shares one platform subscription that uses the most demanding settings; each listener still gets its own distance filter, interval and filters. The last cancel stops it.
• Streams never error and never end because of state. When location services go off, permission changes or the app goes to the background, they pause; statusStream says why; they resume by themselves.
• watch(withAddress: true) looks up the address again only after moving 50 m or after 10 minutes (GeocodingConfig.watchRegeocodeMeters / watchRegeocodeTtl), never per fix.

Background tracking (opt-in) #

By default streams pause in the background. Pass BackgroundLocation to keep one running — a delivery trip, a patrol, a run:

BaabaLocation.instance.positionStream(
  accuracy: LocationAccuracy.high,
  distanceFilter: 15,
  background: const BackgroundLocation(
    notificationTitle: 'Trip in progress',
    notificationText: 'Your location is shared until you end the trip.',
    notificationIcon: 'drawable/ic_tracking',
  ),
);

• Android runs a location foreground service with that notification. Start the stream while the app is visible. Declare FOREGROUND_SERVICE and FOREGROUND_SERVICE_LOCATION; Google Play then asks for a foreground-service declaration in the Console.
• iOS keeps updating in the background with the blue indicator. Needs UIBackgroundModes → location; without it the stream stays foreground-only and positionStream reports misconfigured.
• While-in-use permission is enough.

BackgroundLocation also takes notificationChannelName ('Location'), notificationIcon ('mipmap/ic_launcher', as type/name in res/), notificationColor, ongoing (true), wakeLock / wifiLock (false; Android) and showIosIndicator (true).

What it does not do: fixes live only while the process lives. If the OS or the user kills the app, tracking stops, nothing is buffered on disk, and it does not restart after a reboot. Apps that need that use a dedicated background-location package.

Last known location #

final r = await BaabaLocation.instance.lastKnownPosition(maxAge: const Duration(hours: 1));
// r.source: lastKnownOs or lastKnownStored; r.age; r.address (if one was looked up)

The OS's last known location is often missing (new device, after a reboot, after location was off) or old, so the package keeps its own copy of the latest accepted fix (and its address), and returns the newer of the two — the more accurate one when they are within 30 s.

• Stored in the app's cache directory, which neither Android Auto Backup nor iCloud backs up: a location is never restored onto another device. The OS may clear it when storage runs low.
• Written at most every 25 m or 10 s (storeWriteMinDistance / storeWriteMinInterval), and when the app pauses.
• Only fixes that pass LocationConfig.filters are stored — with rejectMocked, a spoofed fix is never kept.
• On logout and account switch, call clearStoredLocation(). It deletes the stored copy and the address cache. Turn storing off with persistLastKnown: false. Nothing stored is ever sent anywhere.

Geocoding #

final address = await BaabaLocation.instance.addressFrom(position);
final address2 = await BaabaLocation.instance.addressFrom(null, lat: 31.52, lng: 74.35);
final places = await BaabaLocation.instance.positionsFrom('Mall Road, Lahore');

Address has formatted (one display line, built from the parts when the provider has none), name, street, houseNumber, subLocality, locality, subAdministrativeArea, administrativeArea, postalCode, country, countryCode, raw. Missing parts are null, never '', and nothing is invented — a city-only or plus-code-only answer still gives a usable formatted.

Handled for you:

• Queue and throttling — one request at a time per provider; on rateLimited it backs off (1 s, doubling, up to maxBackoff) instead of failing every call.
• Cache — reverse results by a ~20 m grid cell + locale, forward results by the normalised query + locale, with a TTL and a size cap. A stream drifting a few metres never triggers a lookup.
• Cancellation — pass consumer:; a newer call with the same consumer completes the older one at once with superseded (a search box typing quickly sends only what's needed).
• Locale — per call, then GeocodingConfig.locale, then the device's. Part of the cache key.
• Fallback providers — on notSupported, network or rateLimited the next provider is tried; never on noResult.

The default provider is the platform geocoder (Android Geocoder, iOS CLGeocoder: free, no key). Plug in your own backend, Google or Mapbox:

class MyBackendGeocoder extends GeocodingProvider {
  @override
  String get name => 'backend';

  @override
  Future<AddressResult> reverse(double lat, double lng, {Locale? locale}) async { ... }

  @override
  Future<PositionsResult> forward(String query, {Locale? locale}) async { ... }
}

BaabaLocation.init(LocationConfig(
  geocoding: GeocodingConfig(fallbackProviders: [MyBackendGeocoder()]),
));

The example app has a complete OpenStreetMap Nominatim provider.

Permissions #

LocationAccess reports state and precise. Approximate-only access (Android 12+ "Approximate", iOS 14+ Precise off) is its own state: access.approximateOnly. requestPrecise() asks for the upgrade (Android re-request; iOS temporary full accuracy, with iosPrecisePurposeKey).

Setup doctor #

final report = await BaabaLocation.instance.diagnose();
print(report.toChecklist());

In debug builds it also prints the checklist. It reports: missing manifest / Info.plist entries with the snippet to add, the iOS purpose key and background mode, permission and precision, location services, a short test fix (no UI), whether the geocoder is present and answering, the stored last known location, device model and OS version, and battery-optimisation state on Android.

With baaba_app_config, drop it into the debug panel in one line:

DebugSection.info('Location', () => report.toMap())

Error handling #

No public method throws. Each returns a result, and every failure:

• has a reason from one closed enum, LocationFailureReason;
• has a message for developers (not end users);
• has a resolution — requestPermission, requestPrecise, openAppSettings, openLocationSettings, updatePlayServices, fixConfiguration, retryLater or none — that resolve(failure) performs;
• carries details (the missing key, the snippet, the provider) and error / stackTrace where relevant;
• reaches LocationObserver.onError(operation, failure, stack) exactly once, with a stable operation name: get, get.address, watch, watch.address, currentPosition, lastKnownPosition, positionStream, addressFrom, positionsFrom, serviceEnabled, checkPermission, ensurePermission, requestPrecise, openLocationSettings, openAppSettings, resolve, diagnose, storage.corrupt, storage.write, callback.permissionStep.

Nothing hangs: every platform call has a timeout, and a whole get() flow is bounded by flowTimeout (3 min). State changes — services off, permission downgraded — arrive on statusStream, not as errors.

Troubleshooting #

playServicesMissing, playServicesOutdated, startNotAllowed, storageFull, limitReached and cancelledByUser are reserved and never returned today; a switch over the enum still has to cover them.

Gotchas #

• position throws on a failure. Check isSuccess first, or use positionOrNull.
• balanced is about 100 m. Attendance with a tight radius needs high.
• Geolocator allows one position stream per app. If your own code also calls Geolocator.getPositionStream(), the two share it — use BaabaLocation.instance.positionStream() instead.
• iOS doesn't open location settings directly. The services dialog opens the app's Settings page; the user goes back to Privacy → Location Services from there.
• Ages use the device clock (geolocator has no monotonic time). A clock moved backwards marks a stored value's age as unreliable instead of guessing.
• A permission dialog still on screen when flowTimeout passes stays there until the user answers; the flow has already returned timeout and ignores the late answer.
• Background tracking stops if the app is killed. See Background tracking.

Testing #

import 'package:baaba_location/testing.dart';

final location = FakeBaabaLocation(permission: LocationAccess.denied)
  ..simulateUserResponse(FakeUserResponse.grantPrecise)
  ..setCurrentFix(Position(latitude: 31.52, longitude: 74.35, timestamp: DateTime.now()));

final r = await location.get();
expect(r.isSuccess, isTrue);
expect(r.steps, contains(LocationStep.requestedPermission));
expect(location.callsTo('get'), hasLength(1));

FakeBaabaLocation is the real implementation on a simulated device, so the flow, filters, fallback, cache and geocoding queue behave as in production. Script it with emit, playRoute, setServiceEnabled, setPermission, setLastKnown / setOsLastKnown / setStoredLastKnown, failNext(reason), timeoutNext, setMisconfigured, setBackground, stubAddress, stubPositions, geocodingFails, setOnline and simulateUserResponse. Every call is recorded in calls. Use it in widget tests with LocationBuilder(location: fake, …) or BaabaLocation.instance = fake.

Configuration reference #

LocationConfig #

GeocodingConfig #

PositionFilters #

PositionFilters.standard is the default; PositionFilters.none turns every filter off.

Helpers #

BaabaLocation.distanceBetween(a, b) (metres) and BaabaLocation.bearingBetween(a, b) (degrees from north) take two LatLngs and work on every platform.

License #

MIT