The one idea to hold in your head

A background location app does NOT stay running the whole time. It cannot. Both Android and iOS will kill it. So instead of staying alive, it hands a few smart triggers to the phone's operating system and then lets itself die. The OS keeps those triggers and wakes the app back up at exactly the right second. Accuracy does not come from running 24x7. It comes from being clever about WHEN to wake up and switch on GPS.

Read that twice. Once you accept that the app is supposed to die, everything else makes sense. Beginners usually assume the app is secretly running in a corner forever. It is not. It is mostly dead, and that is the whole trick.

Before you start: there are three ways to build this

This blog covers all three, so pick the one that fits you before you follow the code.

1. The plugin way (flutter_background_geolocation), covered in "Step by step: build this yourself in Flutter". Fastest to ship and the best battery behaviour. It is a paid plugin from Transistorsoft, free in debug builds, but a release build needs a license key tied to your package id or bundle id.

2. The Dart-only way (geolocator plus your own foreground service), covered in the teardown section. Free, simpler, but weaker at surviving a force quit.

3. The native way (your own Kotlin and Swift code over method and event channels), also in the teardown section. Free, most control, most work.

So if you are building your own tracking from scratch, options 2 and 3 need no license key at all. The key is only for option 1.

Why you cannot just keep the app running

Imagine if any app could run GPS forever in the background. Your battery would be gone by lunch, and every shady app would be following you around. So phone makers put a hard stop on it. Two things happen:

1. The OS kills background apps. When your phone needs memory, or you swipe the app away, or it just decides your app has been idle too long, the operating system shuts your app down. You do not get a vote.

2. GPS is expensive. The GPS chip is one of the hungriest things on the phone. Keep it on continuously and the battery melts.

So the plugin works WITH these rules instead of fighting them. It assumes it will be killed, and it plans for resurrection. Think of it like leaving a note for a friend that says "wake me up when I cross this line." You can go to sleep. The friend (the OS) holds the note and shakes you awake at the right moment.

The heart of it: be lazy to be accurate

Here is the clever bit that makes both battery life AND accuracy possible at the same time. It sounds backwards but stay with me.

When you are standing still, GPS is turned OFF. The app drops an invisible circle around your current spot (this circle is called a geofence) and goes to sleep. The phone uses almost no battery. The app process can even die. Nobody cares, because nothing is moving.

The moment you start moving and step outside that circle, the OS notices and wakes the app up. Now the app turns on high-accuracy GPS and records every point while you travel. When you stop again, it drops a fresh circle, switches GPS off, and goes back to sleep.

So it is accurate BECAUSE it is lazy. It does not waste GPS while you sit at your desk, which keeps the battery happy, which means the OS does not feel the urge to kill it aggressively, which means it is alive and precise the moment you actually move. Battery saving and accuracy are the same feature here, not a trade off.

Now the part everyone asks about: what happens when the app dies

This is where Android and iOS go in totally different directions. Let me do them one at a time, simply.

Android: a permanent worker plus notes held by the system

While your app is alive in the background, Android keeps it tracking using something called a foreground service. You have seen it. It is that notification that says "App is using your location" which you cannot swipe away. That notification is not annoying-for-no-reason. It is literally the deal you make with Android: "show the user a notification, and in exchange I let you keep running and reading GPS in the background." No notification, no permission. That is the rule on modern Android.

This foreground service is set to restart itself if Android kills it for memory reasons. So far so good. But what about when your app process is FULLY dead? This is the magic part.

The plugin registers two kinds of "notes" with Google Play Services, which is a separate system app that does NOT die when your app dies:

• Geofence triggers. "Hey Play Services, when this phone crosses this circle, wake my app."

• Activity Recognition triggers. "Hey Play Services, when this phone goes from still to walking or driving, wake my app."

When one of those conditions happens, Play Services reaches into your dead app and cold-starts a tiny piece of it called a BroadcastReceiver. Your app gets a few seconds of life, the tracking engine wakes up, grabs the location, and does its job. Your Flutter and Dart code can be completely shut down and this still works. That is what people mean by headless mode. The native engine runs without the rest of your app being awake.

And if the phone reboots? The plugin also registers a "on boot" note, so when the phone turns back on, it re-arms everything automatically.

iOS: the system relaunches your app for you

iOS is much stricter. You genuinely cannot run forever in the background, end of story. But Apple gives location tracking one special superpower: a couple of services are allowed to relaunch your app even after it has been force-quit, and even after a reboot. Almost nothing else on iOS can do this.

The two services are:

• Region Monitoring, which is iOS's version of geofences. Cross a monitored circle and iOS relaunches your app in the background.

• Significant Location Change (SLC), which fires when you move a meaningful distance, detected cheaply using cell towers and wifi instead of GPS.

When one of these fires, iOS quietly relaunches your app in the background, hands it a little flag that says "you woke up because of location," gives you a short moment to act, and then suspends you again. Important detail: plain continuous GPS does NOT survive a force-quit on iOS by itself. So the plugin uses regions and SLC as the "wake me up" layer, and only switches on full precise GPS once it is already awake and senses real movement.

This is also why, on iOS, the very first point after a kill can feel a little delayed. The app had to be relaunched by an event before it could even start tracking.

"Terminated" is not just one thing

A big source of confusion for beginners is treating "closed" as a single state. It is actually a ladder, and behaviour changes at each rung.

So when someone asks "does it work after the app is closed," the honest answer is "yes, but the mechanism that revives it depends on exactly how it was closed."

The last piece: never lose a single point

Accuracy is not only about capturing locations. It is about not dropping them. What if the phone is in a tunnel, or has no signal, or your server is down for a minute?

The plugin handles this by writing every location into a small local database (SQLite) on the phone FIRST, before doing anything else. Then a separate part of the system tries to upload those saved points to your server. If the upload fails because there is no internet, the points just wait in the local database and get uploaded later, in the correct order, once the connection is back.

Golden rule to copy for any tracking app: record locally first, sync as a totally separate concern. A dead zone should never punch a hole in your track.

The full picture in one diagram

That loop is the entire product. Sleep cheaply, wake on a real signal, track precisely while moving, save everything, repeat.

Step by step: build this yourself in Flutter

This section is a complete walk through using the flutter_background_geolocation package, since that is the battle-tested way to get all of the above without writing the native code yourself. Follow it top to bottom.

Step 0: understand what you are signing up for

This package is free to fully test in DEBUG builds. For a RELEASE build on Android, and for the App Store on iOS, you need a paid license key tied to your app's package id (Android) or bundle id (iOS). So you can build and test everything for free, and only pay when you ship to production. Plan for that.

Step 1: add the package

In your pubspec.yaml:

dependencies:
  flutter_background_geolocation: ^4.16.0
  # the package also needs its companion, added automatically in most cases

Then run flutter pub get. Always check pub.dev for the latest version number rather than copying mine.

Step 2: Android setup

2a. Permissions in AndroidManifest.xml

Inside android/app/src/main/AndroidManifest.xml, above the <application> tag, declare what you need. Each line has a reason:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- lets you track while the app is in the background -->
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<!-- the permanent notification that keeps you alive -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
<!-- detect still vs walking vs driving -->
<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
<!-- re-arm tracking after the phone reboots -->
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

2b. License key (only needed for release)

Inside the <application> tag, add your license key as a meta-data line:

<meta-data
  android:name="com.transistorsoft.locationmanager.license"
  android:value="YOUR_LICENSE_KEY" />

2c. Gradle repository

The package pulls its native engine from Maven. In most recent versions this is wired up for you, but if a build fails saying it cannot find tslocationmanager, make sure your android/build.gradle (or settings.gradle) has mavenCentral() and the JitPack repo listed under repositories.

Step 3: iOS setup

3a. Info.plist text

In ios/Runner/Info.plist, add the permission descriptions. iOS shows these sentences to the user, so write them in plain language explaining WHY:

<key>NSLocationWhenInUseUsageDescription</key>
<string>We use your location to track field visits while you use the app.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We track your location in the background to log field activity.</string>
<key>NSMotionUsageDescription</key>
<string>We use motion data to save battery while tracking.</string>

3b. Background modes

Still in Info.plist, switch on the background abilities:

<key>UIBackgroundModes</key>
<array>
  <string>location</string>
  <string>fetch</string>
</array>

You can also enable these by ticking "Location updates" and "Background fetch" under Signing and Capabilities in Xcode.

Step 4: ask for permission the right way

Do not ask for background location on the very first screen. Both stores dislike that and users reject it. Ask for "while in use" first, explain why in your own UI, and only then request "always." The plugin will request what it needs when you call ready, but a gentle in-app explanation screen before that hugely improves acceptance.

Step 5: configure and start tracking (the Dart part)

Here is a minimal but complete setup. Read the comments, they explain each choice.

import 'package:flutter_background_geolocation/flutter_background_geolocation.dart' as bg;

Future<void> initTracking() async {
  // 1. Listen for each new location
  bg.BackgroundGeolocation.onLocation((bg.Location location) {
    print('New location: ${location.coords.latitude}, ${location.coords.longitude}');
  });

  // 2. Listen for the still <-> moving switch
  bg.BackgroundGeolocation.onMotionChange((bg.Location location) {
    print('Moving state changed. isMoving = ${location.isMoving}');
  });

  // 3. Configure the engine
  await bg.BackgroundGeolocation.ready(bg.Config(
    desiredAccuracy: bg.Config.DESIRED_ACCURACY_HIGH, // best GPS while moving
    distanceFilter: 10,            // record a point every 10 meters of movement
    stopOnTerminate: false,        // keep tracking after the app is killed
    startOnBoot: true,             // re-arm after the phone reboots
    enableHeadless: true,          // allow waking with no UI alive
    foregroundService: true,       // the persistent notification on Android
    url: 'https://your-server.com/locations', // where to upload points
    autoSync: true,                // upload automatically
    batchSync: false,              // send points one by one (or batch them)
  )).then((bg.State state) {
    if (!state.enabled) {
      // 4. Actually start it
      bg.BackgroundGeolocation.start();
    }
  });
}

The two settings that make it survive being killed are stopOnTerminate: false and startOnBoot: true. The one that makes it work with no UI is enableHeadless: true.

Step 6: handle the headless wake-up (Android)

When the OS wakes your dead app, your normal Dart code is not running. You register a separate tiny function that the engine can call in that headless moment. Put this at the very top level of your main.dart, outside any class.

// must be a top-level function
@pragma('vm:entry-point')
void headlessTask(bg.HeadlessEvent headlessEvent) async {
  switch (headlessEvent.name) {
    case bg.Event.LOCATION:
      bg.Location location = headlessEvent.event;
      print('Headless location: $location');
      break;
    case bg.Event.MOTIONCHANGE:
      print('Headless motionchange');
      break;
  }
}

void main() {
  runApp(const MyApp());
  // register the headless handler
  bg.BackgroundGeolocation.registerHeadlessTask(headlessTask);
}

The @pragma('vm:entry-point') line is not optional. It tells Flutter not to throw this function away during release optimization, because the engine needs to find it by name when the app is otherwise dead.

Step 7: test it properly

Do not just test by leaving the app open. That proves nothing. Real tests:

1. Start tracking, then swipe the app out of recents. Walk around the block. Check your server received points.

2. Reboot the phone without opening the app. Move. Confirm tracking re-armed itself.

3. Sit still for ten minutes and watch the battery. It should barely move. If GPS is stuck on, your config is wrong.

4. Turn on airplane mode, move around, then turn internet back on. Confirm the queued points upload in order.

Step 8: survive the cheap-phone problem (very important in India)

Many budget Android phones (Xiaomi, Oppo, Vivo, Realme and others) run aggressive "battery saver" software that kills background apps no matter what the rules say. This is the number one reason field-tracking apps fail in the real world here. Defenses:

• Guide the user to disable battery optimization for your app. The plugin has a helper, bg.DeviceSettings, that can open the right settings screen.

• For company-owned devices, look into Android Device Owner or a managed enrollment. When your app is the device owner, the OEM battery killers no longer apply, and force-quit and optimization simply stop being a problem. For a controlled fleet like field agents, this is the most reliable answer by far.

• Always show the user a clear one-time screen explaining they must allow background location and turn off battery optimization, or tracking will be unreliable.

Quick mental checklist

1. The app is meant to die. Plan for resurrection, do not fight it.

2. Sleep with GPS off behind a geofence. Wake on geofence exit or motion.

3. Android revives via a foreground service plus Play Services geofence and activity triggers, re-armed on boot.

4. iOS revives via Region Monitoring and Significant Location Change, which can relaunch even after force-quit.

5. Save every point to local SQLite first, upload as a separate retrying step.

6. stopOnTerminate: false, startOnBoot: true, enableHeadless: true are the three settings that matter most.

7. On cheap Android phones, defeat the OEM battery killer or your tracking dies silently.

When does the foreground service actually show up? (clearing the confusion)

This part confuses almost everyone, so let us nail it down. First, remember one thing: that notification IS the foreground service. They are the same thing wearing two faces. Notification visible means the service is running. Notification gone means the service has stopped.

When it starts

The foreground service starts only when the app is actively tracking, which means when the person is in the MOVING state. The flow looks like this:

So the notification is not meant to be visible all the time. It comes and goes depending on whether the person is moving. This is not a bug. It is deliberate, to save battery. When the person is sitting still, both GPS and the service shut down, the phone sleeps, and the battery is safe.

If it stops (notification disappears), is that a problem?

No. This is the real source of the confusion. The notification disappearing does NOT mean tracking has died. It only means the app has gone to sleep (stationary mode). The operating system still holds the two triggers, the geofence and the motion trigger. The moment the person moves again, the OS wakes the app, the service starts again, and the notification comes back.

So during testing, if you notice the notification vanish, do not panic. Move around and it will reappear. Tracking is still alive the whole time, it is just sleeping cheaply.

If you want the notification to stay visible always

If you do not like this come-and-go behavior and prefer the user to always see that tracking is on, the plugin can be configured so the foreground service runs continuously the entire time tracking is enabled. Then the notification stays permanent. The trade off is more battery usage.

So there are two modes to choose between:

• Battery friendly: notification appears only while moving. Best battery life.

• Always visible: notification stays up the whole time tracking is enabled. More transparent and more reliable on aggressive phones, but uses more battery.

One caution: on newer Android (12 and above) Google restricts starting a foreground service from the background, so the exact come-and-go behavior can vary a little by Android version and plugin version. The plugin handles this internally, but always test on your real target phones to confirm the notification behaves the way you expect.

When does the foreground service start, and is it a problem if it stops?

This part confuses almost everyone, so let us settle it cleanly. First, the single most important fact:

That notification IS the foreground service. They are the same thing in two forms. Notification visible means the service is running. Notification gone means the service has stopped. There is no hidden third state.

When does it start?

The foreground service starts only when the plugin is actively tracking with GPS, which is when the person is in the moving state. It does not run all the time. Here is the lifecycle:

So the notification naturally comes and goes depending on whether the person is moving. This is not a bug. It is deliberate, and it is exactly how the battery gets saved. When the agent is sitting still, both GPS and the service shut down, the phone sleeps, and almost no battery is used.

Is it a problem when the notification disappears?

No. This is the key point that causes the confusion. The notification disappearing does not mean tracking has died. It only means the app has gone to sleep in stationary mode. The two wake-up triggers (the geofence and the motion sensor) are still armed and held by the operating system. The moment the person moves again, the OS wakes the app, the service restarts, and the notification comes back on its own.

So during testing, if you see the notification vanish while standing still, do not panic. Move around and it will reappear. Tracking was alive the whole time, just sleeping cheaply.

If you want the notification to stay visible all the time

If this come-and-go behaviour is not what you want, and you would prefer the user always sees that tracking is on, the plugin can be configured to keep the foreground service running continuously for as long as tracking is enabled. The notification then stays permanent. The trade-off is higher battery usage.

So you are choosing between two modes:

1. Battery-friendly mode: notification appears only while moving, disappears while still. Best battery life.

2. Always-on mode: notification stays visible the entire time tracking is enabled. Higher battery use, but more transparent and more resistant to being killed.

One caveat worth knowing: on newer Android (12 and above) Google restricts starting a foreground service from the background, so the exact behaviour depends on the Android version and plugin version. The plugin handles this internally, but always test on your real target devices to confirm the notification behaves as expected.

A different way real apps do this (a teardown story)

Everything above uses flutter_background_geolocation, which is the gold standard. But when you actually pull apart other tracking apps in the wild, many of them do NOT use it. They build a simpler version by hand. It helps to understand that version too, because you will meet it far more often than you expect, and it comes with very different trade-offs.

Here is the common pattern you find inside a lot of HR and field-attendance apps once you look under the hood.

There are actually two different ways to build this simpler version. One stays entirely in Dart and leans on the geolocator plugin. The other drops down into native Android and iOS code and talks to Flutter through channels, which hands you far more control and lets you read signals the plugin never surfaces. Let us walk through both, one after the other.

Way 1: The Dart-only approach (the geolocator plugin)

Instead of the clever geofence-sleep engine, these apps use the basic geolocator package to read positions, and wrap it in their own foreground service that simply stays on the whole time tracking is enabled. There is no "sleep behind a geofence" trick. The service starts, holds a wake lock, and streams positions on a distance filter until tracking is turned off.

Why do people build it this way? Because it is simple, it has no license cost, and for many use cases you do not actually need the app to survive a full swipe-away for days. You just need reliable tracking during an active shift, which this handles fine.

The trade-offs you must know:

• It burns more battery, because GPS and the service run continuously instead of sleeping behind a geofence.

• Surviving a hard force-quit is weaker. These apps lean onstopWithTask=false, a boot receiver and a battery-optimisation exemption, but they do not have the Play Services geofence resurrection trick. So a fully killed process can simply stop until the user opens the app again.

• It is much easier to reason about and debug, which is a real advantage when you are shipping fast.

Tip

If your tracking only needs to be reliable during a known active window, like a shift, a delivery, or a site visit, the simple always-on service is often the pragmatic choice. Save the full geofence engine for true all-day passive tracking where battery life is the main worry.

Way 2: The native approach with method and event channels

The Dart-only way is easy, but it can only give you what the plugin chooses to expose. When you want full control, you drop into native code. You write the location logic in Kotlin on Android and Swift on iOS, run your own foreground service, and send the results up to Flutter through a channel. This is the approach a serious field-ops app usually lands on, because the richest signals live in the native layer, not in Dart.

Method channel versus event channel, in one line each

• A MethodChannel is a request and a response. Dart calls something likestartTracking, native runs it and replies once. It is made for commands: start, stop, or ask a one-time question.

• An EventChannel is a continuous stream. Native keeps pushing values, and Dart keeps listening. This is the perfect fit for a live location feed, because points arrive again and again.

The signals you can grab natively, and why they matter

Once you are in native code, each location update can carry much more than latitude and longitude. These are exactly the extra fields that make a track trustworthy and easy to debug:

• Speed in metres per second, taken straight from the GPS fix. Handy to catch impossible jumps and to tell walking from driving.

• isMocked, the real spoof flag, read right at the source instead of through a wrapper.

• Device info like model and manufacturer, so you can spot the cheap OEM phones that love to kill background apps.

• Battery level and charging state, so your server understands that a dead battery, not a bug, is why the points stopped arriving.

Bundling all of these into every event turns a plain coordinate into a record you can actually trust.

Android native (Kotlin)

Inside your own foreground service, you use the FusedLocationProviderClient. On each update, you build a map with the extra signals and push it into the EventChannel sink.

// inside your location EventChannel StreamHandler
private val locationCallback = object : LocationCallback() {
    override fun onLocationResult(result: LocationResult) {
        val location = result.lastLocation ?: return

        // read the spoof flag at the source
        val isMock = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
            location.isMock              // API 31 and above
        } else {
            @Suppress("DEPRECATION")
            location.isFromMockProvider  // older devices
        }

        // battery level right now
        val bm = context.getSystemService(Context.BATTERY_SERVICE) as BatteryManager
        val batteryLevel = bm.getIntProperty(BatteryManager.BATTERY_PROPERTY_CAPACITY)

        val data = mapOf(
            "latitude" to location.latitude,
            "longitude" to location.longitude,
            "speed" to location.speed,          // metres per second
            "accuracy" to location.accuracy,
            "isMocked" to isMock,
            "deviceModel" to Build.MODEL,
            "manufacturer" to Build.MANUFACTURER,
            "batteryLevel" to batteryLevel,
            "timestamp" to location.time
        )

        // send this event up to Dart
        eventSink?.success(data)
    }
}

iOS native (Swift)

On iOS you use CLLocationManager. The mock story is different here. Plain iOS does not hand you a mock provider flag the way Android does, but from iOS 15 you can check whether a fix was produced by a simulator through the location's sourceInformation.

func locationManager(_ manager: CLLocationManager,
                     didUpdateLocations locations: [CLLocation]) {
    guard let location = locations.last else { return }

    // spoof hint on iOS 15 and above
    var isMocked = false
    if #available(iOS 15.0, *) {
        isMocked = location.sourceInformation?.isSimulatedBySoftware ?? false
    }

    // battery level right now
    UIDevice.current.isBatteryMonitoringEnabled = true
    let batteryLevel = Int(UIDevice.current.batteryLevel * 100)

    let data: [String: Any] = [
        "latitude": location.coordinate.latitude,
        "longitude": location.coordinate.longitude,
        "speed": location.speed,             // metres per second, -1 if unknown
        "accuracy": location.horizontalAccuracy,
        "isMocked": isMocked,
        "deviceModel": UIDevice.current.model,
        "batteryLevel": batteryLevel,
        "timestamp": location.timestamp.timeIntervalSince1970
    ]

    // send this event up to Dart
    eventSink?(data)
}

The Dart side, just listening

On the Flutter side you do almost nothing. You open the same two channels and listen to the stream. All the heavy lifting already happened natively, so Dart only reads a clean event.

class NativeTracking {
  static const _commands = MethodChannel('app/tracking/commands');
  static const _events = EventChannel('app/tracking/events');

  Future<void> start() => _commands.invokeMethod('startTracking');
  Future<void> stop() => _commands.invokeMethod('stopTracking');

  Stream<Map<String, dynamic>> get locationStream =>
      _events.receiveBroadcastStream().map((e) => Map<String, dynamic>.from(e));
}

// usage
final tracking = NativeTracking();
tracking.locationStream.listen((data) {
  if (data['isMocked'] == true) {
    // reject, native already flagged this point as fake
    return;
  }
  print('lat ${data['latitude']}, speed ${data['speed']}, '
      'battery ${data['batteryLevel']}, device ${data['deviceModel']}');
});

Tip

Do the mock check, the speed sanity check, and the device and battery reads in native code, not in Dart. That is where the real signals live, and it means the event that reaches Dart is already clean and trustworthy. The Dart layer should just consume a validated event, not try to police it after the fact.

Which way should you pick?

Most apps start on Way 1 and move to Way 2 only when they hit a wall, like needing a signal the plugin does not expose, or needing tighter control over the service and the anti-spoof checks.

The piece the earlier sections skipped: stopping fake GPS

Everything above quietly assumed that the location you receive is honest. In the real world, especially for attendance and field apps, it often is not. An employee can install a fake-GPS app and punch in from home while the map shows the office. If you are building anything where location decides money, like attendance, travel allowance, or delivery proof, you have to defend against this or the whole feature is meaningless.

Every Android location object carries a simple flag that tells you whether it came from a mock provider. In the geolocator package, each Position exposes isMocked. Checking it is the cheapest first line of defence you can add.

import 'package:geolocator/geolocator.dart';

Future<void> readLocation() async {
  Position position = await Geolocator.getCurrentPosition(
    desiredAccuracy: LocationAccuracy.high,
  );

  // Android marks positions that came from a fake GPS app
  if (position.isMocked) {
    // do not trust this point, flag the user and reject it
    print('Mocked location detected, rejecting this point');
    return;
  }

  print('Trusted location: ${position.latitude}, ${position.longitude}');
}

Real apps go further and refuse to run at all on devices that make spoofing easy:

• Rooted or jailbroken devices are blocked, because root makes faking location trivial and hard to detect.

• Emulators are blocked, since an emulator can report any coordinate you type into it.

• Developer Mode being switched on is flagged, because most mock-location apps need it enabled.

Tip

isMocked is necessary but not enough on its own. A rooted device can hide the mock flag entirely. That is why serious apps combine the flag with root and emulator checks, and add a server-side sanity check too, like rejecting impossible speed between two points or a location that jumps across cities in a few seconds. Trust a position only after it clears all of these gates.

Live tracking versus store and forward

Earlier we said: save every point to SQLite first, then sync it up separately. That is the right pattern for route logging, where you care about a complete and gap-free history.

But some apps have a different need. An admin wants to watch a live map and see field agents move in real time, right now. For that, the store-and-forward queue is too slow. These apps push each position straight into a realtime database, and Firebase Realtime Database is the common choice, so the admin dashboard updates the instant a new point arrives.

The two are not enemies. A robust app can do both at once: push live for the dashboard, and still keep a local SQLite copy so a dead zone never punches a hole in the recorded history. Live for the eyes, local for the record.

What to copy and what to avoid from real apps

Good ideas worth stealing from apps that ship this successfully:

• Check isMocked on every point and reject mocked ones.

• Block, or at least flag, rooted and emulator devices for any money-critical tracking.

• Consider a live push to a realtime database when someone genuinely needs to watch a map, but keep the local queue as well.

• Use stopWithTask=false plus a boot receiver so a swipe-away or a reboot does not silently end a shift.

Mistakes worth avoiding, all of which show up in real shipped apps if you look closely:

• Shipping cleartext HTTP (usesCleartextTraffic=true) so that location data travels unencrypted. Always send coordinates over HTTPS.

• Leaving a developer's local test URL, like an http://192.168.x.x endpoint, hardcoded in the release build.

• Hardcoding unrestricted map API keys in the app. Restrict every key by package name and signing certificate, and by the specific API it is allowed to call, or someone will run up your billing.

• Trusting the phone's location blindly with no spoof defence at all.

The one line to remember from this teardown

The fancy plugin is not the only way, and it is not always the right way. Pick your architecture from the need. Simple always-on service for a bounded shift, full geofence engine for all-day passive tracking. And whatever you build, if location decides money, never trust a coordinate until it has proven it is not faked.

The third wake-up style: timer-driven periodic sampling

So far the blog has shown two ways an app gets woken up. The geofence and motion approach, where the OS wakes you because you moved. And the continuous foreground service, where you simply stay awake the whole time. There is a third style you will meet in real apps, and it answers a very specific question: "the phone is in deep sleep, but I still want a location every few minutes." This is called timer-driven or periodic sampling, and it is built from two Android pieces working together, SCHEDULE_EXACT_ALARM and WAKE_LOCK.

First, why a normal timer does not work

Your instinct might be to write a simple loop or a Timer that fires every five minutes and grabs a location. In the background this quietly fails, and it is important to understand why.

When the phone goes idle with the screen off, it enters a power saving state called Doze. In Doze the CPU is put to sleep to save battery. While that happens, your app's own timers, Future.delayed calls, and background loops are all frozen. They do not fire until something wakes the CPU. Your app process can even be killed entirely. So a plain "every five minutes" timer inside your app is simply not running when the phone is asleep, which is exactly when you needed it.

The key realisation

Anything that must fire while the phone sleeps cannot live inside your app's own timers. It has to be handed to the operating system, because the OS does not sleep the way your app does. That is what AlarmManager is for.

Piece one: SCHEDULE_EXACT_ALARM, the part that wakes the phone

AlarmManager is a system service that runs a small piece of your code at a chosen time, whether your app is alive or dead. Think of it as leaving an alarm clock with the operating system instead of trying to stay awake yourself.

There are two flavours, and the difference matters:

• A normal (inexact) alarm gets batched and delayed by Doze to save battery. A five minute alarm might actually fire twenty minutes later. For location sampling this is useless.

• An exact alarm, using setExactAndAllowWhileIdle, is allowed to fire on time even in Doze.

To use exact alarms on Android 12 and above (API 31), you must declare the SCHEDULE_EXACT_ALARM permission. Without it the system only gives you the inexact kind. This is exactly why field-tracking apps request it.

A catch worth knowing

An exact alarm is one-shot. It fires once and forgets. So every time it fires, you must schedule the next one yourself, or the cycle stops after a single tick. The pattern is: wake up, do the work, then set the next alarm before going back to sleep.

Piece two: WAKE_LOCK, the part that keeps the phone awake long enough

Here is the subtle part that trips people up. When your alarm fires, the system gives your BroadcastReceiver only a very short window to run, roughly ten seconds, and it expects you to finish quickly.

But getting a GPS fix is slow and asynchronous. A cold fix can take five to thirty seconds. If you request a location and then let your receiver return, the CPU goes straight back to sleep before the fix arrives. Your location callback never completes, or your upload dies halfway.

The fix is to grab a partial wake lock the moment your receiver runs. A partial wake lock keeps the CPU awake while the screen stays off, using very little battery. You hold it while you request the location, wait for the fix, save it, and upload it. Then you release it so the phone can sleep again.

One line to remember

The alarm wakes the phone at the right second. The wake lock keeps it awake just long enough to finish the job. One is about when, the other is about how long.

The full loop

What it looks like in Kotlin

// 1. Schedule the next wake-up
fun scheduleNextWakeup(context: Context) {
    val am = context.getSystemService(Context.ALARM_SERVICE) as AlarmManager
    val intent = Intent(context, LocationAlarmReceiver::class.java)
    val pi = PendingIntent.getBroadcast(
        context, 0, intent,
        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
    )
    val triggerAt = System.currentTimeMillis() + 5 * 60 * 1000 // 5 minutes later

    // exact, and allowed to fire even in Doze (needs SCHEDULE_EXACT_ALARM)
    am.setExactAndAllowWhileIdle(AlarmManager.RTC_WAKEUP, triggerAt, pi)
}

// 2. The receiver: stay awake, get a location, re-arm, then sleep
class LocationAlarmReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        val pm = context.getSystemService(Context.POWER_SERVICE) as PowerManager
        val wakeLock = pm.newWakeLock(
            PowerManager.PARTIAL_WAKE_LOCK, "app:LocationWakeLock"
        )
        wakeLock.acquire(60_000) // safety timeout, hold at most 60 seconds

        val fused = LocationServices.getFusedLocationProviderClient(context)
        fused.getCurrentLocation(Priority.PRIORITY_HIGH_ACCURACY, null)
            .addOnSuccessListener { location ->
                saveAndUpload(location) // your own save plus upload
            }
            .addOnCompleteListener {
                scheduleNextWakeup(context)          // re-arm the next alarm
                if (wakeLock.isHeld) wakeLock.release() // let the phone sleep
            }
    }
}

Two caveats you must plan for

• Doze rate-limits even exact alarms. In deep Doze, setExactAndAllowWhileIdle will reliably fire only about once every nine minutes or so. So you cannot get a location every thirty seconds this way. For short intervals or continuous tracking you still need a foreground service. This is why real apps often combine both: a foreground service for dense tracking while the person is active, and alarm-based sampling for occasional check-ins while the phone is idle.

• Battery optimisation can block it. Requesting REQUEST_IGNORE_BATTERY_OPTIMIZATIONS and guiding the user to allow it makes these alarms fire far more reliably, especially on the aggressive cheap OEM phones we keep coming back to.

So where does this fit among the three styles?

The takeaway

Exact alarms plus a wake lock are the tool when you want a location on a schedule rather than on movement. The alarm handles when to wake, the wake lock handles staying awake long enough to finish, and you re-arm the alarm on every tick. Just remember Doze will not let you sample faster than roughly every nine minutes, so pair it with a foreground service whenever you need something tighter.

Some plugins solve this in a way that looks like magic. You install them, they work perfectly, and yet the actual clever logic is nowhere to be found in the source. People assume the code must be downloaded secretly at runtime and run off some server. That guess is wrong, and getting it wrong matters, because if you ever want to protect your own code the same way, you would build the wrong thing entirely.

Here is what is really going on, and how you can use the exact same pattern to ship a paid feature without handing over your source.

The myth, killed quickly

The valuable code is already sitting inside your APK before the app even launches. It gets baked in when you build the app, not while a user is running it. Build time, not run time. The secret sauce ships with the app, just in a form that is hard to read.

This distinction is not just trivia. If a plugin really did download and run fresh code at runtime, Google Play would flag it. The Device and Network Abuse policy does not allow apps to fetch and execute code (a DEX file or a native library) from outside the app after install. So even if you wanted to do the runtime download thing, you should not. The build-time approach is the safe, standard one, and it is what these plugins actually do.

Source code vs binary, in plain language

When you write Dart, Kotlin, or Swift, that is source code. Anyone can open the file and read exactly what it does.

Before your app ships, a compiler chews through that source and spits out a binary. A binary is a packed file full of low-level instructions. A person can still pry it open with the right tools, but it is slow, messy, and most people will not bother. Think of source code as a recipe written out step by step, and a binary as that same recipe blended into a smoothie. Everything is still in there. Good luck reading it back out.

So a package author has two choices:

1. Ship the source. This is what almost every pub.dev package does. Open the folder, read every line, copy it freely.

2. Ship only the binary and keep the source private.

That second option is the whole trick. Nothing fancier than that.

What is actually inside a plugin like this

A plugin built this way is three layers stacked together. Only one of them is open.

The Dart layer is a thin remote control. It holds none of the clever logic. It just forwards your calls down to the native binary through Flutter platform channels. All the brains live in the .aar and the .xcframework. That is exactly why an author can leave the Dart part open on GitHub and lose nothing. The valuable part is not there.

A quick aside that trips people up: an AAR is not the same as a JAR. A JAR is just compiled Java or Kotlin classes. An AAR is an Android Archive, so it can also bundle resources, a manifest, and native .so files. That extra packaging is why a full Android engine can ship as a single dependency.

How the binary lands inside your app

Here is the line that does the heavy lifting. The plugin ships a small Gradle file that your app applies, and inside it there is basically this:

dependencies {
    // Pull the closed-source engine
    api(group: 'com.yourcompany', name: 'yourengine', version: '1.0.0')
}

When you run flutter build apk, Gradle reads that line, reaches out to a Maven repository, downloads the AAR, and bundles it straight into your APK. After that the binary is part of your app, sitting on the phone like any other code. No network call when the app runs.

The AAR can sit on a fully public Maven repo, and that is fine, because the file is useless to anyone without a valid license. We will get to that in a second.

The user never downloads the engine separately. It travelled inside the APK the entire time.

Tip: you will often see a version written as '1.+', which means "give me the latest 1.x". Convenient, but it quietly breaks reproducible builds, because two people building the same commit on different days can pull different binaries. For anything you ship to production, pin the exact version and bump it on purpose. Future you, staring at a bug that only shows up on one machine, will be grateful.

The one thing that runs at runtime: the license check

If the binary is free to download, how does anyone make money from it? A license gate baked inside the binary.

You drop a license key into your AndroidManifest.xml:

<meta-data
  android:name="com.yourcompany.engine.license"
  android:value="YOUR_LICENSE_KEY_HERE" />

When the app starts, the native binary reads that key and checks it against your app's package name. The key is generated for one specific package id, tied to a buyer account. If the key is missing or wrong, the engine refuses to run in a release build. In debug builds it works without any key, so a developer can try before they buy.

The check is offline friendly. The key works like a signed certificate that says "this package id is allowed," and the binary verifies it locally. It does not phone home on every launch.

Hard-won gotcha: because debug builds skip the license entirely, everything works beautifully in development, and then your first release build silently kills the feature. People lose hours to this. Always smoke-test a real signed release build before you assume licensing is wired up correctly.

So, two clean phases. Build time bakes in the binary. Run time verifies a key. Neither phase downloads code over the network.

How to hide your own code the same way

Say you build something genuinely valuable, like a custom anti-spoofing module or a pricing engine, and you want to license it to other companies without handing over the source. Here is the full recipe.

Step 1: Pull the secret logic into a native module

Do not leave the valuable logic in Dart. Dart in a plugin is readable. Move it down into native code.

On Android, create an Android Library module and write the logic in Kotlin or Java. For the most sensitive parts, drop into C or C++ with the NDK, which compiles to a .so file that is far harder to reverse than Kotlin bytecode. On iOS, create a Framework target and write it in Swift or Objective-C.

Step 2: Compile it into a binary

On Android, run the assembleRelease task to get a .aar. Turn on R8 or ProGuard with minifyEnabled true so the bytecode gets obfuscated and your method names collapse into a, b, c. On iOS, set BUILD_LIBRARY_FOR_DISTRIBUTION = YES, archive, and build an .xcframework, then zip it.

Two tips most tutorials skip. First, obfuscation will happily rename the methods your platform channel calls by reflection, and then everything breaks at runtime with no compile error. Add explicit keep rules (or the @Keep annotation) for your public API and any entry points. Second, after you build native .so files, run strip on them to remove debug symbols. Smaller file, and you stop handing a reverse engineer a map with all the street names on it.

Step 3: Wrap it in a thin Flutter plugin

Create a normal Flutter plugin package. The Dart side is just the remote control. It exposes friendly methods and forwards calls to your binary over a MethodChannel. This Dart code can stay open, because it holds nothing worth stealing. Your Gradle file and podspec point at the binary instead of bundling source.

Step 4: Add your own license gate

Inside the binary, before doing the real work, check something the buyer cannot fake. Read the app's package id and compare it against a signed key you generated for them. Verify that key with public-key cryptography, so a buyer cannot forge their own. They would need your private key, which never ships. Optionally do a light online activation the first time the app runs.

Keep the check inside the native binary, never in Dart, otherwise anyone can simply delete it.

The sharpest version of this: do not write the gate as a plain if (!valid) return;. That is one line for someone to NOP out in a patched binary. Instead, make the license key actually do work the feature needs. Use it to derive a value, or to decrypt a config blob the engine cannot function without. Now patching out the check does not unlock the feature, it just breaks it. You have tied the lock to the engine instead of bolting it onto the door.

Step 5: Publish the binary and reference it from Gradle

Upload your AAR to a Maven repo, then your plugin's Gradle does the same move:

dependencies {
    api(group: 'com.yourcompany', name: 'yourengine', version: '1.0.0')
}

That is the entire pattern. Dart stays open and friendly, the brains stay locked in a binary, and a license key controls who gets to run it.

Where to host your binary

For Android the binary lives in a Maven repository. For iOS it lives wherever CocoaPods or Swift Package Manager can reach a zipped xcframework, usually a plain file URL. Here are the real options, from laziest to most controlled.

JitPack. You push a library to a GitHub repo and JitPack compiles and serves it as a Maven dependency automatically. Public repos are free, great for moving fast. The catch is that JitPack builds from source, so for a closed product your source has to live somewhere JitPack can read it, which usually means a paid private repo.

Maven Central (Sonatype Central Portal). The industry-standard home, and where most serious Android libraries live. Free to publish, and every Android project can pull from it with zero config. The trade-off is that the binary becomes fully public, so all your security has to come from the license gate, not from hiding the file. Setup is a one-time chore (verify a namespace, sign artifacts with GPG), but smooth after that.

GitHub Packages. A Maven repo attached to your GitHub account. Free for public packages. Private packages work too, but consumers need a token in their Gradle to authenticate, which is annoying to hand out to external buyers. Good for internal use where your own team holds the tokens.

Self-hosted on your own server. A Maven repo is literally a folder of files served over HTTPS in a specific directory layout, so any web server does the job. Drop the files behind nginx on a VPS you already pay for and point Gradle at https://maven.yourdomain.com. Cloudflare R2 is even better for downloads, since it speaks the S3 API and charges zero egress fees. Plain AWS S3 works, but you pay for every gigabyte downloaded, which can sting if the file gets popular.

For iOS, zip the xcframework and host that single file (R2, S3, a VPS, or a GitHub Release asset), then point your CocoaPods podspec or SPM binaryTarget at the URL.

SPM tip: a binaryTarget requires a checksum of the zip, and the build fails if it does not match. That is a feature, not a hassle. It means a buyer (or an attacker on the network) cannot quietly swap your binary for a tampered one. Generate it with swift package compute-checksum yourframework.zip and commit the value.

What it costs to host (2026 prices)

An AAR or xcframework is tiny, usually a few megabytes, and a niche product does not pull much download traffic. So at this scale almost everything here is effectively free.

The honest summary: hosting the file is the cheap part. R2 stands out because storage is almost nothing and downloads are genuinely free, so the bill never surprises you even if the product takes off. S3 is the one to watch, because egress is metered.

Which option to actually pick

Two situations, two answers.

If this is internal tooling that only your own apps use, self-host on a VPS or push to a private GitHub Packages repo. You control the tokens, nobody outside sees it, and it costs nothing extra. Keep the license gate simple, since you trust the consumers anyway.

If this becomes a real product you sell to other developers, go Maven Central for Android plus a zipped xcframework on R2 for iOS. Maven Central gives buyers the frictionless install they expect, and R2 keeps iOS downloads free. Then put your real effort into the license gate and key generation, because once the file is on Maven Central it is public, and the gate is your only lock.

The catch nobody likes to admit

A binary is harder to read, not impossible. Anyone can run a tool like jadx on an AAR and get back obfuscated bytecode, or pull the .so files out and study them. A determined person with time can work through it, and a simple license check can be patched out by someone skilled enough.

So be honest about what this actually buys you. It stops casual copy-paste. A regular developer cannot just lift your code. That is real and worth something. It does not stop a serious reverse engineer who has decided to crack it.

A couple of things that make their life harder, none of which make it impossible:

• Strings in a binary are trivially greppable. Run strings on any compiled file and out come your URLs, error messages, and any secret you were naive enough to hardcode. Never assume a value is safe just because it is compiled. If it must stay secret, it does not belong on the device.

• A native check of the app's signing certificate at startup raises the bar on repackaging. It is not unbeatable, but it filters out the low-effort attempts.

If the logic is truly your crown jewels, the strongest move is to keep the heavy lifting on a server you control and have the app call an API. The client only ever sees inputs and outputs, never the algorithm. The binary trick is the right middle ground when the logic has to run on-device, which is the case for things like location tracking or offline detection. For that on-device case, binary plus obfuscation plus a license gate is the sensible setup.

Quick checklist if you want to build your own

1. Move the secret logic out of Dart into a native Android library and iOS framework.

2. Compile to .aar and .xcframework with R8 or ProGuard obfuscation on, and keep rules for your public API.

3. Strip debug symbols from native .so files.

4. Write a thin open Dart wrapper that talks to the binary over a MethodChannel.

5. Add a license gate inside the binary, verified with public-key crypto, tied to the package id, and woven into something the feature needs so it cannot be cleanly patched out.

6. Publish the AAR (Maven Central or private GitHub Packages) and host the xcframework zip (R2 is ideal), with a pinned version and an SPM checksum.

7. Remember the limit. This protects against casual copying, not a determined attacker. Keep the truly priceless stuff server-side.

TL;DR — This guide covers everything you need to rebrand a Flutter app for a new client: changing the app name, swapping the icon with flutter_launcher_icons, renaming the package ID with change_app_package_name, and a checklist of things most developers miss. Whether you're white-labeling for the first time or the tenth, this is the reference you'll keep coming back to.

So you built something. An app that actually works, looks good, and solves a real problem. Now a client or company comes along and says — "Can we have this, but with our name and logo?"

That's a great problem to have. But if you've never done a Flutter app rebrand before, it can feel oddly intimidating for something that sounds simple. Change the name, swap the icon, rename the package... how hard can it be?

Turns out, if you don't know where to look, it can get messy fast. This guide walks you through the complete Flutter white-label rebranding process — step by step, cleanly and confidently.

What Does "Rebranding a Flutter App" Actually Mean?

When you hand off a white-labeled version of your Flutter app to another company, there are three things that almost always need to change:

1. The app name — what users see on their home screen
2. The app icon — the visual identity of the brand
3. The package name / bundle ID — the unique identifier used by the Google Play Store, Apple App Store, and the OS itself

Most developers forget that third one until something breaks. Let's not do that.

Each of these changes targets a different part of your project, and skipping even one can cause build failures, store rejections, or worse — your app and the client's app sharing the same identifier in production.

Step 1 — How to Change the Flutter App Name

The display name (the label that appears under the icon on a user's phone) lives in two platform-specific files.

Android — AndroidManifest.xml

Open android/app/src/main/AndroidManifest.xml and update the android:label attribute on the <application> tag:

<application
    android:label="ClientAppName"
    ...>

iOS — Info.plist

Open ios/Runner/Info.plist and update the CFBundleDisplayName key:

<key>CFBundleDisplayName</key>
<string>ClientAppName</string>

That covers both platforms. It's simple, but missing one of them means the rebrand looks half-done on one OS — and clients notice.

Step 2 — How to Change the Flutter App Icon

Manually resizing icons for every screen density is the kind of thing that used to take an hour and still somehow looked wrong on one device. Skip all of that.

The flutter_launcher_icons package handles icon generation for every size and density on both Android and iOS from a single source image.

Setup

Add it to your pubspec.yaml:

dev_dependencies:
  flutter_launcher_icons: ^0.13.1

flutter_launcher_icons:
  android: true
  ios: true
  image_path: "assets/icons/client_icon.png"
  min_sdk_android: 21

Use a high-quality PNG at 1024x1024 pixels as your source. Then run:

dart run flutter_launcher_icons

That single command generates all the required icon sizes for both platforms. No Photoshop, no manual asset folders.

Things to Watch Out For

• Transparent backgrounds on Android 7 or below — they'll render as a black square. Use a solid background color instead.
• Adaptive icons for Android 13+ — you can configure adaptive_icon_background and adaptive_icon_foreground separately in the config for a better look on modern Android.
• Always test on a real device — the icon preview during config doesn't represent how it actually renders on every launcher.

Step 3 — How to Change the Flutter Package Name (The Critical Step)

The package name on Android (e.g., com.yourcompany.appname) and the bundle identifier on iOS are what uniquely identify your app across the entire ecosystem. If two apps share the same ID, the Play Store and App Store will treat them as the same app — which causes real problems during submission.

When rebranding a Flutter app for a new client, this must change.

Doing it manually means touching AndroidManifest.xml, build.gradle, every directory path under kotlin/ or java/, the package declarations inside those files, and iOS project settings in Xcode. Miss one file and you're looking at a cryptic build error and 20 minutes of head-scratching.

The cleaner way is the change_app_package_name pub package.

Setting It Up

Add it to dev_dependencies in your pubspec.yaml:

dev_dependencies:
  change_app_package_name: ^1.5.0

Then run a single command:

dart run change_app_package_name:main com.clientcompany.appname

Replace com.clientcompany.appname with the new package name. The convention is reverse domain notation — use the client's domain if they have one (e.g., com.acmecorp.deliveryapp).

What the Package Does Automatically

• Updates applicationId in android/app/build.gradle
• Renames the directory structure under android/app/src/main/kotlin/ (or java/)
• Updates the package declaration inside all affected Kotlin/Java files
• Updates AndroidManifest.xml

What You Still Need to Do on iOS

The package doesn't touch iOS. For the bundle identifier, open your project in Xcode, go to Runner > Signing & Capabilities, and update the Bundle Identifier field. It takes about 10 seconds.

Step 4 — The Rebranding Checklist (Things Most Developers Miss)

The three steps above get the visible stuff done. But before you hand off the build to a client, run through this checklist.

Firebase / Backend Config If your app uses Firebase, the new package name won't be registered in the existing Firebase project. You'll need a new google-services.json (Android) and GoogleService-Info.plist (iOS) from a Firebase project linked to the new package ID. Skipping this breaks push notifications, analytics, and auth.

Deep Links and Custom URL Schemes If your app handles universal links or custom URL schemes (e.g., yourapp://), those are tied to the package name and domain. Update them in the manifest, entitlements, and wherever they're configured on your server.

App Store and Play Store Listings A new package name means a completely new store listing — it's not an update to the original app. The client will need their own developer accounts (or you submit under yours with their details). Plan for a fresh review cycle.

Keystore and Signing Certificates Never sign a client's build with your own personal keystore. Either generate a new keystore for them or have them generate one themselves. The same applies to iOS provisioning profiles and distribution certificates.

Environment Variables and API Keys If the original app points to your own backend or uses your API keys, the rebranded version needs its own config. The cleanest way to manage this is with Flutter's --dart-define flags or a flavor-based environment config — more on that below.

Splash Screen Don't forget to update the splash screen if it includes your logo or the original app name. The flutter_native_splash package makes this just as easy as flutter_launcher_icons.

Bonus: Set Up Flutter Flavors for Multi-Client Workflows

If rebranding is something you're going to do more than once — multiple clients, same core codebase — it's worth setting up Flutter flavors (called build variants on Android).

Flavors let you maintain a single codebase and produce completely different builds — different names, icons, package names, API endpoints, and feature flags — just by switching a build target:

flutter run --flavor clientA -t lib/main_clientA.dart
flutter run --flavor clientB -t lib/main_clientB.dart

The initial setup takes a few hours, but once it's in place, onboarding a new client becomes a matter of adding a new flavor config rather than manually cloning and modifying the entire project.

The flutter_flavorizr package automates most of the boilerplate for setting up flavors across both platforms. It's worth an afternoon of your time if you're building a white-label business around your app.

Quick Reference — Flutter Rebranding Checklist

Frequently Asked Questions

Can I use the same Firebase project for multiple rebranded apps? Technically yes, but it's not recommended. Each rebranded app should ideally have its own Firebase project to keep analytics, crash reports, and user data separate per client.

Does change_app_package_name work with flavors? It works on the default app config. If you're using flavors, you'll want to manage package names per-flavor in your build.gradle directly rather than running the package command.

Do I need a separate Apple Developer account for each client? Not necessarily. You can distribute under your own account and list the client as the seller, or you can submit through their account. This is a business/contractual decision more than a technical one.

Will changing the package name affect existing users of the original app? No — your original app is untouched. The rebranded version is effectively a brand new app. Existing users of the original won't see any difference.

What's the difference between package name and app name in Flutter? The app name is what users see on their screen. The package name is an internal identifier used by the OS and app stores — users never see it, but it has to be unique.

Wrapping Up

Rebranding a Flutter app for a client isn't complicated once you know the three core things to change — app name, icon, and package ID. The right packages handle most of the mechanical work, and a solid checklist takes care of the rest.

The real leverage comes when you start thinking about this at architecture time. Building flavor support into your project from day one means you're never scrambling when the second client shows up.

If you've done this before and ran into something I didn't cover here — a quirky edge case, a platform-specific gotcha — drop it in the comments. This kind of shared experience is what makes these guides actually useful over time.

And if this saved you some time or headache, share it with a Flutter dev who's about to go through their first white-label project. They'll owe you one.

Meet Lumi and Nyx. They share one Flutter app. Lumi prefers light mode — bright cards, cheerful blues, a UI that feels open. Nyx wants the opposite — calm grays, a dark background, something easier on the eyes at night.

Your job as the developer? One app, two moods, zero duplication.

That's what theming is for. In this article, we'll build a clean, production-ready theme system that:

• switches between light, dark, and system modes,
• centralizes colors, typography, shapes, and spacing,
• supports quick toggles and persistence, and
• scales with Theme Extensions for custom brand tokens.

Theme 101: What Actually Is a Theme?

Before writing any code, it's worth getting the terminology straight:

• ThemeData — the master container for all visual settings: colors, typography, shapes, component styles.
• ColorScheme — the Material 3 color palette. Always prefer this over manual color assignments.
• ThemeMode — tells Flutter which theme to use: light, dark, or system.
• Theme.of(context) — how you read the active theme from inside any widget.
• AnimatedTheme — wraps widgets and animates smoothly when the theme changes.
• ThemeExtension — lets you attach custom design tokens (like spacing or border radii) directly to the theme.

Project Skeleton

We'll start with Material 3, wire up a ColorScheme, add a quick toggle, and persist the user's choice.

import 'package:flutter/material.dart';
import 'package:shared_preferences/shared_preferences.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final prefs = await SharedPreferences.getInstance();
  final saved = prefs.getString('themeMode') ?? 'system';
  final initialMode = _parseThemeMode(saved);

  runApp(AppRoot(initialMode: initialMode, prefs: prefs));
}

ThemeMode _parseThemeMode(String s) => switch (s) {
  'light' => ThemeMode.light,
  'dark' => ThemeMode.dark,
  _ => ThemeMode.system,
};

class AppRoot extends StatefulWidget {
  const AppRoot({super.key, required this.initialMode, required this.prefs});
  final ThemeMode initialMode;
  final SharedPreferences prefs;

  @override
  State<AppRoot> createState() => _AppRootState();
}

class _AppRootState extends State<AppRoot> {
  late ThemeMode _mode = widget.initialMode;

  Future<void> _setMode(ThemeMode m) async {
    setState(() => _mode = m);
    await widget.prefs.setString('themeMode', switch (m) {
      ThemeMode.light => 'light',
      ThemeMode.dark => 'dark',
      ThemeMode.system => 'system',
    });
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Lumi & Nyx',
      debugShowCheckedModeBanner: false,
      themeMode: _mode,
      theme: AppTheme.light,
      darkTheme: AppTheme.dark,
      home: HomeScreen(
        mode: _mode,
        onChangeMode: _setMode,
      ),
    );
  }
}

A few things worth noting here:

• We read SharedPreferences on startup to restore the user's last chosen mode.
• MaterialApp takes three separate knobs: theme, darkTheme, and themeMode.
• Calling _setMode triggers a rebuild and also writes the choice to disk.

Your Design Tokens: ColorScheme-First (Material 3)

class AppTheme {
  static const _seed = Color(0xFF4F46E5);
  static const _error = Color(0xFFB00020);

  static final ColorScheme _lightScheme = ColorScheme.fromSeed(
    seedColor: _seed,
    brightness: Brightness.light,
    error: _error,
  );

  static final ColorScheme _darkScheme = ColorScheme.fromSeed(
    seedColor: _seed,
    brightness: Brightness.dark,
    error: _error,
  );

  static ThemeData get light => ThemeData(
        useMaterial3: true,
        colorScheme: _lightScheme,
        scaffoldBackgroundColor: _lightScheme.background,
        appBarTheme: AppBarTheme(
          backgroundColor: _lightScheme.surface,
          foregroundColor: _lightScheme.onSurface,
          elevation: 0,
          centerTitle: false,
        ),
        textTheme: _textTheme(_lightScheme),
        cardTheme: CardTheme(
          elevation: 0,
          margin: const EdgeInsets.all(12),
          shape: RoundedRectangleBorder(
            borderRadius: BorderRadius.circular(16),
          ),
        ),
        extensions: const <ThemeExtension<dynamic>>[
          AppSpacing.compact,
        ],
      );

  static ThemeData get dark => ThemeData(
        useMaterial3: true,
        colorScheme: _darkScheme,
        scaffoldBackgroundColor: _darkScheme.background,
        appBarTheme: AppBarTheme(
          backgroundColor: _darkScheme.surface,
          foregroundColor: _darkScheme.onSurface,
          elevation: 0,
          centerTitle: false,
        ),
        textTheme: _textTheme(_darkScheme),
        cardTheme: CardTheme(
          elevation: 0,
          margin: const EdgeInsets.all(12),
          shape: RoundedRectangleBorder(
            borderRadius: BorderRadius.circular(16),
          ),
        ),
        extensions: const <ThemeExtension<dynamic>>[
          AppSpacing.compact,
        ],
      );

  static TextTheme _textTheme(ColorScheme scheme) {
    return Typography.material2021().black.apply(
      bodyColor: scheme.onBackground,
      displayColor: scheme.onBackground,
    );
  }
}

ColorScheme.fromSeed does a lot of heavy lifting — it derives a full, harmonious palette (primary, secondary, surface, background, and their "on" counterparts) from a single brand color, for both light and dark. You wire it in once and everything else just works.

Pro Move: ThemeExtension for Brand Tokens

The built-in ThemeData covers most cases, but real apps often need things like consistent spacing values, custom border radii, or brand-specific shadow levels. ThemeExtension is the right way to handle this — it keeps your tokens in the theme tree, not scattered as constants across the codebase.

@immutable
class AppSpacing extends ThemeExtension<AppSpacing> {
  final double xs, sm, md, lg, xl;
  const AppSpacing({
    required this.xs,
    required this.sm,
    required this.md,
    required this.lg,
    required this.xl,
  });

  static const compact = AppSpacing(xs: 4, sm: 8, md: 12, lg: 16, xl: 24);

  @override
  AppSpacing copyWith({double? xs, double? sm, double? md, double? lg, double? xl}) {
    return AppSpacing(
      xs: xs ?? this.xs,
      sm: sm ?? this.sm,
      md: md ?? this.md,
      lg: lg ?? this.lg,
      xl: xl ?? this.xl,
    );
  }

  @override
  AppSpacing lerp(ThemeExtension<AppSpacing>? other, double t) {
    if (other is! AppSpacing) return this;
    double lerpDouble(double a, double b) => a + (b - a) * t;
    return AppSpacing(
      xs: lerpDouble(xs, other.xs),
      sm: lerpDouble(sm, other.sm),
      md: lerpDouble(md, other.md),
      lg: lerpDouble(lg, other.lg),
      xl: lerpDouble(xl, other.xl),
    );
  }
}

extension SpacingX on BuildContext {
  AppSpacing get space => Theme.of(this).extension<AppSpacing>()!;
}

Using it in widgets is clean and readable:

Padding(
  padding: EdgeInsets.all(context.space.lg),
  child: const Text('Consistent spacing everywhere.'),
)

Quick Theme Switching UI (With Animation)

class HomeScreen extends StatelessWidget {
  const HomeScreen({super.key, required this.mode, required this.onChangeMode});
  final ThemeMode mode;
  final ValueChanged<ThemeMode> onChangeMode;

  @override
  Widget build(BuildContext context) {
    final scheme = Theme.of(context).colorScheme;

    return Scaffold(
      appBar: AppBar(
        title: const Text('Lumi & Nyx'),
        actions: [
          PopupMenuButton<ThemeMode>(
            icon: const Icon(Icons.light_mode),
            initialValue: mode,
            onSelected: onChangeMode,
            itemBuilder: (context) => const [
              PopupMenuItem(value: ThemeMode.system, child: Text('System')),
              PopupMenuItem(value: ThemeMode.light, child: Text('Light')),
              PopupMenuItem(value: ThemeMode.dark, child: Text('Dark')),
            ],
          ),
        ],
      ),
      body: AnimatedTheme(
        duration: const Duration(milliseconds: 250),
        data: Theme.of(context),
        child: Center(
          child: Card(
            color: scheme.surface,
            child: Padding(
              padding: EdgeInsets.all(context.space.xl),
              child: Text(
                'This card adapts to the active theme.',
                style: Theme.of(context).textTheme.titleLarge,
              ),
            ),
          ),
        ),
      ),
      floatingActionButton: FloatingActionButton.extended(
        onPressed: () {
          final next = switch (mode) {
            ThemeMode.system => ThemeMode.light,
            ThemeMode.light => ThemeMode.dark,
            ThemeMode.dark => ThemeMode.system,
          };
          onChangeMode(next);
        },
        label: Text('Mode: ${mode.name}'),
        icon: const Icon(Icons.auto_mode),
      ),
    );
  }
}

The FAB cycles through modes quickly; the menu gives the user explicit control. AnimatedTheme handles the transition so the switch doesn't feel abrupt.

Custom Fonts and Typography

Add your font to pubspec.yaml:

flutter:
  uses-material-design: true
  fonts:
    - family: Inter
      fonts:
        - asset: assets/fonts/Inter-Regular.ttf
        - asset: assets/fonts/Inter-Medium.ttf
          weight: 500
        - asset: assets/fonts/Inter-SemiBold.ttf
          weight: 600

Then apply it in your AppTheme:

static TextTheme _textTheme(ColorScheme scheme) {
  final base = Typography.material2021().black;
  return base.apply(
    fontFamily: 'Inter',
    bodyColor: scheme.onBackground,
    displayColor: scheme.onBackground,
  );
}

If you want a different type scale in dark mode, you can create a separate builder for it.

Respecting the System Theme

Using ThemeMode.system is the right default — it automatically follows the OS-level setting on Android, iOS, macOS, and Windows. If you ever need to query it manually:

final isDark = MediaQuery.of(context).platformBrightness == Brightness.dark;

One practical note: if you're offering a manual override toggle, make sure you're also persisting the choice. Otherwise users will find their preference reset every time they launch the app.

Reading Theme Correctly Inside Widgets

The single most common theming mistake in Flutter codebases is hardcoding colors. It breaks dark mode and makes brand updates painful.

Do this:

final cs = Theme.of(context).colorScheme;

Container(
  decoration: BoxDecoration(
    color: cs.surface,
    borderRadius: BorderRadius.circular(16),
  ),
  child: Text('Hello', style: Theme.of(context).textTheme.bodyLarge),
);

Avoid this:

Container(color: Colors.white);
Text('Hello', style: TextStyle(color: Colors.black));

Hardcoded colors are invisible to the theme system. They'll look wrong in dark mode and require manual updates whenever your brand changes.

Status Bar and System Overlays

This detail is easy to overlook but visible to every user. Make sure your status bar icons stay readable against both themes:

AppBar(
  systemOverlayStyle: Theme.of(context).brightness == Brightness.dark
      ? SystemUiOverlayStyle.light
      : SystemUiOverlayStyle.dark,
);

For custom areas without an AppBar, wrap with AnnotatedRegion<SystemUiOverlayStyle>.

Theming Cupertino Widgets

If your app uses Cupertino-style components alongside Material ones, pass the current theme through:

CupertinoTheme(
  data: CupertinoThemeData(
    brightness: Theme.of(context).brightness,
    primaryColor: Theme.of(context).colorScheme.primary,
  ),
  child: const CupertinoButton(child: Text('iOS style'), onPressed: null),
);

Multiple Brand Themes

Some apps need more than light and dark — think "Blue plan" vs "Green plan", or white-labeled variants. You can handle this with the same approach:

enum Brand { indigo, green }

final brandThemes = <Brand, ThemeData>{
  Brand.indigo: AppTheme.light,
  Brand.green: AppTheme.light.copyWith(
    colorScheme: ColorScheme.fromSeed(seedColor: const Color(0xFF0EA5A5)),
  ),
};

Swap brandThemes[currentBrand]! the same way you'd swap ThemeMode, and persist the choice.

Common Pitfalls

A few things that come up repeatedly in code reviews:

• Hardcoded colors — the most frequent issue. Always pull from Theme.of(context).colorScheme.
• Missing darkTheme — if you only set theme, your app will show the light theme on dark-mode devices.
• No persistence — users expect their theme preference to survive an app restart.
• Text contrast issues — use onSurface, onBackground, and similar "on" colors from ColorScheme instead of guessing.
• No animation — AnimatedTheme is a small addition that makes theme switches feel intentional rather than jarring.
• Scattered global tokens — if you're defining spacing or border radii as constants spread across files, move them into a ThemeExtension.

A Quick Checklist Before Shipping

• Material 3 enabled with useMaterial3: true
• Both theme and darkTheme provided
• themeMode persisted across sessions
• Quick toggle available, with system mode as an option
• Custom fonts applied via TextTheme
• Brand-specific tokens in a ThemeExtension
• Animated transitions on theme change
• Status bar icon colors correct per theme
• No hardcoded colors anywhere in widgets

Key Takeaways

ThemeMode controls which theme is active. ColorScheme is your source of truth for colors — build it from a seed and let Flutter derive the rest. ThemeExtension is the right place for custom design tokens like spacing and radii. Persist the user's preference and animate transitions. And keep hardcoded colors out of your widgets entirely — your future self will thank you.

One of the most common in security-sensitive Flutter apps is this: the app is backgrounded, the user changes something significant — enables developer options, toggles mock location, grants a new permission — and then returns. The app resumes and carries on as if nothing happened. It trusts whatever state it had when it left. That trust is the problem.

didChangeAppLifecycleState is where you fix it.

What the Lifecycle States Actually Mean

Flutter surfaces four app-level states through AppLifecycleState:

• resumed — the app is in the foreground and the user can interact with it
• inactive — the app is visible but not interactive (incoming call, app switcher, system dialog)
• paused — the app is in the background and not visible
• detached — the Flutter engine is running but no UI is attached

For most security and freshness checks, resumed is the state you care about. It fires every time the app returns to the foreground — from the background, from a lock screen, from switching apps. That's the moment you want to re-examine assumptions.

Setting It Up

Add WidgetsBindingObserver to your state class, register in initState, and always remove in dispose:

class _HomeState extends State<HomeScreen> with WidgetsBindingObserver {

  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    if (state == AppLifecycleState.resumed) {
      _onAppResumed();
    } else if (state == AppLifecycleState.paused) {
      _onAppPaused();
    }
  }
}

The removeObserver call in dispose is not optional. Skipping it means the widget keeps receiving lifecycle callbacks after it's been removed from the tree, which can cause calls on disposed resources or setState on unmounted widgets.

Re-Validating Security on Resume

The most important use of resumed in security-sensitive apps is re-running the checks that determine whether the environment is still trustworthy. A user can:

• Enable developer options while your app is backgrounded
• Enable mock location in developer settings
• Connect a USB debugger
• Grant or revoke permissions
• Enable a VPN

None of these trigger any callback while your app is in the background. The only opportunity you have to detect them is when the app comes back to the foreground.

void _onAppResumed() {
  _validateEnvironment();
}

Future<void> _validateEnvironment() async {
  final isDeveloperModeEnabled = await _checkDeveloperOptions();
  final isMockLocationEnabled = await _checkMockLocation();
  final isRooted = await _checkRootAccess();

  if (isDeveloperModeEnabled || isMockLocationEnabled || isRooted) {
    _blockUsage();
  }
}

This is standard behavior in banking apps, delivery tracking apps, attendance systems, and anywhere location or session integrity matters. The app doesn't assume the environment is still safe — it checks every time it resumes.

Auto Logout After Inactivity

For apps that handle sensitive data, automatic logout after a period of inactivity is a compliance requirement in many contexts. didChangeAppLifecycleState gives you a clean way to implement it:

DateTime? _pausedAt;

void _onAppPaused() {
  _pausedAt = DateTime.now();
}

void _onAppResumed() {
  if (_pausedAt != null) {
    final elapsed = DateTime.now().difference(_pausedAt!);
    if (elapsed > const Duration(minutes: 10)) {
      _logoutUser();
      return;
    }
  }
  _pausedAt = null;
  // Continue normal resume flow
}

The timeout window depends on the app's sensitivity. Financial apps often use 5 minutes. The pattern is the same regardless.

Refreshing Stale Data

Rather than polling on a timer or force-refreshing every time a screen is pushed, resumed is a natural moment to check whether data needs updating:

void _onAppResumed() {
  final timeSinceLastSync = DateTime.now().difference(_lastSyncTime);
  if (timeSinceLastSync > const Duration(minutes: 5)) {
    _refreshData();
  }
}

This feels more intentional than a background timer — it only refreshes when the user actually returns to the app.

Pausing and Resuming Resources

The paused state is the right place to release resources that shouldn't run in the background:

void _onAppPaused() {
  _videoController.pause();
  _locationSubscription.cancel();
  _animationController.stop();
}

void _onAppResumed() {
  if (_shouldAutoPlay) _videoController.play();
  _startLocationUpdates();
}

Cancelling the location subscription when paused and restarting it on resume prevents unnecessary GPS usage while the app isn't visible. On battery-sensitive devices, this matters.

Handling Permission Changes

A common UX scenario: your app requests a permission, the user declines, then goes to Settings and manually grants it. When they return to your app, you should detect the new permission state without asking again:

void _onAppResumed() {
  _recheckPermissions();
}

Future<void> _recheckPermissions() async {
  final status = await Permission.camera.status;
  if (status.isGranted && !_cameraReady) {
    _initializeCamera();
  }
}

Silently re-checking on resume, rather than showing another permission dialog, is the right pattern here.

Using AppLifecycleListener (Newer API)

Flutter also offers AppLifecycleListener, added in Flutter 3.13, which provides named callbacks instead of a switch statement. For new code, it's cleaner:

late final AppLifecycleListener _listener;

@override
void initState() {
  super.initState();
  _listener = AppLifecycleListener(
    onResume: _onAppResumed,
    onPause: _onAppPaused,
    onInactive: _onInactive,
  );
}

@override
void dispose() {
  _listener.dispose();
  super.dispose();
}

The behavior is identical to WidgetsBindingObserver, but the intent of each callback is explicit from the name rather than requiring a switch on the state enum.

A Few Practical Notes

Keep resume logic fast. _onAppResumed fires before the UI is interactive again. If you kick off a slow API call here, the user will notice the lag. Run quick local checks synchronously; defer heavy network work.

Guard against async races. If _onAppResumed triggers an async operation, the widget might be disposed before it completes. Check mounted before calling setState in any callback that crosses an await boundary.

Centralize your checks. Rather than duplicating security or permission checks across multiple screens, keep them in a single service class. Your lifecycle handler calls into that service, and the service decides what action to take. This keeps the lifecycle handler thin and the logic testable.

The Underlying Point

An app that resumes and blindly trusts its previous state is an app that can be manipulated. The window between backgrounding and resuming is exactly when users — or bad actors — can change conditions your app depends on. didChangeAppLifecycleState is how you close that window. Use it to re-check anything your app's correctness or security depends on, and treat resumed not as a continuation of the previous session but as a fresh opportunity to verify that the environment is still what you expect.

At some point in every Dart project, you run into a situation where your classes are being used in ways you never intended. Someone creates an object directly when there should only ever be one. Someone calls an internal helper from outside the file. Someone instantiates a utility class that was never meant to be instantiated.

The language gives you tools to prevent all of this — private constructors, factory constructors, and private functions. They're not just syntax features; they're the building blocks of intentional API design.

Constructors: The Starting Point

A constructor is how you create an object from a class.

class ToyBox {
  ToyBox() {
    print('A new ToyBox is created!');
  }
}

void main() {
  var box = ToyBox(); // Creates a new instance
}

This is fine for most cases. But sometimes, you don't want every caller to freely spin up new instances. That's where private constructors come in.

Private Constructors: Controlling How Objects Are Created

A private constructor uses the ClassName._() syntax. It's accessible only within the same file — nothing outside can call it directly.

class ToyBox {
  ToyBox._(); // private constructor

  static final ToyBox _instance = ToyBox._();

  factory ToyBox() => _instance;
}

Now ToyBox._() can't be called from anywhere outside this file. Only the class itself uses it — which makes it the foundation of the Singleton pattern, utility-only classes, and any situation where you want precise control over instantiation.

Private Constructors for Static-Only Classes

One of the most practical uses of private constructors is preventing instantiation of classes that exist purely as namespaces for static methods or constants.

class MathUtils {
  MathUtils._(); // prevents instantiation

  static const double pi = 3.14159;

  static double areaOfCircle(double radius) => pi * radius * radius;
}

void main() {
  print(MathUtils.areaOfCircle(5)); // works fine
  // var m = MathUtils();           // compile error
}

The private constructor sends a clear signal: this class isn't meant to be used as an object. You use its static members. Creating an instance makes no sense.

You'll see this pattern throughout Flutter's own codebase — Colors, Icons, and similar classes follow the same approach.

Factory Constructors: Smart Object Creation

A factory constructor looks like a regular constructor from the outside, but internally it has full control over what gets returned. It doesn't have to create a new instance every time.

class ToyBox {
  static final ToyBox _instance = ToyBox._();

  ToyBox._();

  factory ToyBox() {
    return _instance; // same instance every time
  }
}

void main() {
  var box1 = ToyBox();
  var box2 = ToyBox();
  print(box1 == box2); // true
}

Factory constructors are useful when you need to return a cached instance, choose between subclasses at runtime, or perform validation before construction. They hide that complexity from the caller.

Factory Constructors That Return Subclasses

A factory constructor can act as a dispatch mechanism — the caller asks for a Shape, and the factory decides which concrete type to return.

abstract class Shape {
  factory Shape(String type) {
    if (type == 'circle') return Circle();
    if (type == 'square') return Square();
    throw ArgumentError('Unknown shape type: $type');
  }
}

class Circle implements Shape {}
class Square implements Shape {}

void main() {
  var s = Shape('circle');
  print(s.runtimeType); // Circle
}

This is encapsulation in practice. The caller doesn't need to know which class they're getting — they just ask for a shape and work with the result.

Private Functions: Keeping Internals Internal

Private functions — any method prefixed with _ — are inaccessible outside the library. They let you keep your class's public surface area small and clean while moving implementation details out of sight.

class PasswordValidator {
  bool isValid(String password) {
    return _hasMinLength(password) && _hasUppercase(password);
  }

  bool _hasMinLength(String password) => password.length >= 8;
  bool _hasUppercase(String password) => password.contains(RegExp(r'[A-Z]'));
}

The public API is just isValid(). The two private helpers do the actual work but are invisible to anyone using this class. This is what good encapsulation looks like — you expose what's necessary and hide everything else.

Real-World Use Cases

Singleton for shared services

When you want a single shared instance across the entire app:

class DatabaseManager {
  static final DatabaseManager _instance = DatabaseManager._();

  DatabaseManager._();

  factory DatabaseManager() => _instance;

  void connect() => print('Connected to DB!');
}

Every call to DatabaseManager() returns the same object. No matter how many places in the app call it, they're all working with the same instance.

Factory for JSON deserialization

This is the most common real-world use of factory constructors in Flutter:

class User {
  final String name;
  final int age;

  User._(this.name, this.age);

  factory User.fromJson(Map<String, dynamic> json) {
    return User._(json['name'], json['age']);
  }
}

The factory hides parsing logic from the caller. If you later need to add validation or caching, you do it inside the factory — none of the calling code changes.

Static-only utility class

class DateUtils {
  DateUtils._();

  static String today() => DateTime.now().toIso8601String();
}

Nothing stops callers from misusing DateUtils as an object — except this private constructor.

Private helpers for internal logic

class EmailValidator {
  bool isValid(String email) => _containsAtSymbol(email) && _isProperLength(email);

  bool _containsAtSymbol(String email) => email.contains('@');
  bool _isProperLength(String email) => email.length >= 6;
}

One clean public method. Two private helpers doing the work behind the scenes.

When to Use Each

The Core Idea

Private constructors and factory methods aren't clever tricks — they're the tools Dart gives you for writing APIs that are hard to misuse. The more explicitly you define how your classes should be created and accessed, the less time you spend debugging code that used them in ways you didn't anticipate.

Good code hides what should be hidden and exposes only what's meant to be used. These three features — private constructors, factory constructors, and private functions — are how you enforce that in Dart.

When that happens, you need to go below the widget layer. Here's how.

The Limit of Widget Composition

Composing existing widgets is fast and reliable, but it has a ceiling. Situations where widget composition genuinely breaks down include:

• Drawing smooth curves or custom shapes that aren't expressible with existing widgets
• Building custom charts, waveforms, or progress arcs
• Laying out children in non-standard arrangements — radial menus, fisheye lists, anything that doesn't follow linear flow
• Building game-like UIs where you need pixel-perfect control over what's drawn and when

For these, Flutter gives you three layers of increasing power — and complexity.

Level 1: CustomPaint and CustomPainter

CustomPaint is Flutter's first escape hatch from the widget system. It hands you a Canvas and a Paint object and gets out of the way. You describe what to draw; Flutter draws it.

Here's a wave background as a practical example:

class WavePainter extends CustomPainter {
  @override
  void paint(Canvas canvas, Size size) {
    final paint = Paint()
      ..color = Colors.blueAccent
      ..style = PaintingStyle.fill;

    final path = Path()
      ..moveTo(0, size.height * 0.8)
      ..quadraticBezierTo(
        size.width * 0.5,
        size.height,
        size.width,
        size.height * 0.8,
      )
      ..lineTo(size.width, 0)
      ..lineTo(0, 0)
      ..close();

    canvas.drawPath(path, paint);
  }

  @override
  bool shouldRepaint(CustomPainter oldDelegate) => false;
}

Using it in your widget tree:

class WaveHeader extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return CustomPaint(
      painter: WavePainter(),
      child: Container(height: 200),
    );
  }
}

shouldRepaint controls when Flutter redraws your painter — returning false here means it only draws once, which is fine for static shapes. For animated or interactive painters, you'd return true or compare old and new delegate values.

This approach handles any shape you can describe with a Path — curves, polygons, gradients, arbitrary fills. It's the right tool for anything visual that doesn't fit standard widget constraints.

Level 2: RenderBox

When you need control over not just painting but also layout and hit testing, RenderBox is the next step. This is Flutter's rendering layer — the same level at which built-in widgets like Container and Text are actually implemented.

It sounds intimidating, but the structure is straightforward:

class MyRenderBox extends RenderBox {
  @override
  void performLayout() {
    size = constraints.constrain(Size(200, 100));
  }

  @override
  void paint(PaintingContext context, Offset offset) {
    final canvas = context.canvas;
    final paint = Paint()..color = Colors.green;
    canvas.drawRect(offset & size, paint);
  }
}

Wrapping it as a widget:

class GreenBox extends LeafRenderObjectWidget {
  @override
  RenderObject createRenderObject(BuildContext context) {
    return MyRenderBox();
  }
}

Drop GreenBox() anywhere in your widget tree. It handles its own size and painting without delegating to any other widget.

You can also handle gestures at this layer:

@override
bool hitTestSelf(Offset position) => true;

@override
void handleEvent(PointerEvent event, HitTestEntry entry) {
  if (event is PointerDownEvent) {
    print("Touched at ${event.position}");
  }
}

This level is appropriate when CustomPainter isn't enough — when your component needs to participate in layout, own its size, or handle input in ways that don't map cleanly to the gesture widgets above.

Level 3: SceneBuilder

SceneBuilder sits at the very bottom of Flutter's rendering stack, below widgets and below RenderBox. It's how Flutter assembles the final frame before handing it to the GPU.

In practice, you'll rarely need this in a standard app. The cases where it makes sense are narrow:

• Building a plugin that integrates Flutter into another rendering engine
• Working on ultra-high-performance rendering where you want to eliminate all widget overhead
• Advanced graphics work involving custom shaders or hybrid compositions

It's worth knowing it exists, but for most production apps — even complex ones — CustomPainter or RenderBox will take you as far as you need to go.

Useful Tools

A few things worth having in your toolkit when working at this level:

• Flutter DevTools — inspect layout, painting, and performance. The "Highlight Repaints" toggle is particularly useful for spotting unnecessary redraws in CustomPainter work.
• ShaderMask and FragmentProgram — bring GPU shaders into your Flutter widgets. Useful for effects that are expensive to approximate with the Canvas API.
• AnimationController with CustomPaint — the standard pattern for animating custom drawings. Drive your painter's parameters from an animation value and call setState (or use a Listenable) to trigger repaints.
• Flame — a lightweight game engine built on Flutter. Worth considering for UIs that are fundamentally game-like in nature rather than document-like.

When to Reach for Each Layer

Real-World Scenarios

• Fitness app progress rings — arcs drawn with CustomPainter, driven by animation values
• Voice recorder waveform — real-time canvas drawing updated from an audio stream
• Interactive mind map — RenderBox with custom hit testing for each node
• Design tool UI — combination of RenderBox for layout and CustomPainter for content

The Underlying Point

Flutter is, at its core, a canvas. The widget system is a convenient abstraction built on top of that canvas, and it's the right starting point for almost everything. But when your design genuinely requires it, stepping below widgets is not as scary as it looks — and the control you gain is well worth the extra complexity.

Build that wavy onboarding screen. Draw that custom chart. Flutter has the tools for it.

Platform Channels are that help. They're Flutter's built-in bridge for passing messages between Dart and native code. There are three of them, each suited to a different communication pattern.

What Is a Platform Channel?

Think of Flutter and native code as two teams working in separate rooms. They can't walk into each other's spaces directly, but they can pass notes through a slot in the wall. Platform Channels are that slot.

Every channel has a name — a string identifier shared by both sides so they can find each other. Beyond that, the three channel types differ in how the conversation flows.

MethodChannel: Ask Once, Get an Answer

MethodChannel is the most common type. Flutter sends a named method call, native code handles it and replies, and that's the end of the exchange.

It's the right tool any time you want to ask native code to do something and get a result back — check the battery, read a device ID, trigger a native dialog.

Flutter (Dart):

const platform = MethodChannel('samples.flutter.dev/battery');

Future<void> getBatteryLevel() async {
  try {
    final int result = await platform.invokeMethod('getBatteryLevel');
    print('Battery is $result%.');
  } catch (e) {
    print('Error: $e');
  }
}

Android (Kotlin):

MethodChannel(flutterEngine.dartExecutor.binaryMessenger, "samples.flutter.dev/battery")
  .setMethodCallHandler { call, result ->
    if (call.method == "getBatteryLevel") {
      val batteryLevel = getBatteryLevel()
      result.success(batteryLevel)
    } else {
      result.notImplemented()
    }
  }

Both sides reference the same channel name. Flutter calls invokeMethod, native handles it, and calls result.success() with the response. One request, one response, done.

BasicMessageChannel: Two-Way Messaging Without a Command Structure

BasicMessageChannel is less formal. Either side can send a message at any point, and the other side can reply — or not. There's no method name, no command-response pairing. It's just a communication channel between two parties.

This suits situations where you want ongoing, loosely structured communication without the overhead of named method calls.

Flutter (Dart):

const channel = BasicMessageChannel<String>(
  'samples.flutter.dev/message',
  StringCodec(),
);

void sendMessage() {
  channel.send('Hello from Flutter!');
}

void receiveMessages() {
  channel.setMessageHandler((message) async {
    print('From Native: $message');
    return 'Received.';
  });
}

Android (Kotlin):

channel = BasicMessageChannel(
  flutterEngine.dartExecutor.binaryMessenger,
  "samples.flutter.dev/message",
  StringCodec.INSTANCE
)

channel.setMessageHandler { message, reply ->
  println("Flutter says: $message")
  reply.reply("Got it.")
}

Both sides set a message handler and can send messages independently. The codec (StringCodec here) defines how messages are serialized — you can also use StandardMessageCodec for more complex data types.

EventChannel: Continuous Data from Native to Flutter

EventChannel is built for streaming. Native code produces a continuous flow of data — sensor readings, location updates, audio levels — and Flutter subscribes to that stream. The data flows until either side cancels.

Flutter (Dart):

const eventChannel = EventChannel('samples.flutter.dev/sensor');

void listenToSensor() {
  eventChannel.receiveBroadcastStream().listen(
    (event) {
      print('Sensor update: $event');
    },
    onError: (error) {
      print('Error: $error');
    },
  );
}

Android (Kotlin):

EventChannel(flutterEngine.dartExecutor.binaryMessenger, "samples.flutter.dev/sensor")
  .setStreamHandler(object : EventChannel.StreamHandler {
    override fun onListen(arguments: Any?, events: EventChannel.EventSink) {
      startSendingSensorData(events)
    }

    override fun onCancel(arguments: Any?) {
      stopSensorUpdates()
    }
  })

When Flutter subscribes, onListen fires on the native side — that's when you start pushing data to the EventSink. When Flutter unsubscribes or the stream is cancelled, onCancel fires and you can clean up.

This is the right choice for any native data source that produces updates over time: accelerometer, GPS, microphone input, network connectivity changes.

Choosing the Right Channel

A Few Practical Notes

Channel names are just strings, but treat them seriously. Use a reverse-domain format like com.yourapp.feature/channel to avoid collisions, especially if you're using third-party plugins that also register channels.

Error handling matters on both sides. On the Dart side, invokeMethod throws a PlatformException if native code calls result.error(). Catch it explicitly rather than letting it bubble up silently.

Threading on Android. The MethodCallHandler runs on the main thread by default. If your native operation is blocking or IO-heavy, dispatch it to a background thread and call result.success() from there when you're done.

iOS works the same way. The channel names and Dart code are identical; only the native implementation differs (Swift or Objective-C instead of Kotlin/Java). Structurally, the pattern is the same on both platforms.

In Summary

Platform Channels are how Flutter reaches into the native platform when it needs to. MethodChannel handles one-off requests. BasicMessageChannel handles free-form conversation. EventChannel handles data streams.

Most Flutter apps only need MethodChannel for occasional platform calls and EventChannel for anything that streams. If you've been avoiding native integration because it seemed complex, the actual API surface is smaller than it looks — it's just message passing with a name attached.

That's where CustomPaint and GestureDetector come in. Together, they let you draw anything and respond to any touch input.

What CustomPaint Actually Does

CustomPaint is Flutter's drawing surface. It gives your code direct access to a Canvas object — the same drawing API that Flutter itself uses internally. With it, you can draw lines, arcs, bezier curves, rectangles, circles, gradients, and arbitrary paths.

The key class is CustomPainter. You subclass it, implement two methods, and pass an instance to CustomPaint:

class CirclePainter extends CustomPainter {
  @override
  void paint(Canvas canvas, Size size) {
    final paint = Paint()
      ..color = Colors.deepPurple
      ..style = PaintingStyle.fill;

    final center = Offset(size.width / 2, size.height / 2);
    final radius = size.width * 0.4;

    canvas.drawCircle(center, radius, paint);
  }

  @override
  bool shouldRepaint(CirclePainter oldDelegate) => false;
}

Using it:

CustomPaint(
  painter: CirclePainter(),
  size: const Size(300, 300),
)

shouldRepaint determines whether Flutter redraws when the widget rebuilds. Return false for static visuals; return true (or compare old and new delegate properties) for anything that changes over time.

Drawing More Complex Shapes with Path

The Path class is the most powerful drawing tool in the Canvas API. It lets you describe any shape as a sequence of moves, lines, and curves.

class WavePainter extends CustomPainter {
  @override
  void paint(Canvas canvas, Size size) {
    final paint = Paint()
      ..color = Colors.teal
      ..style = PaintingStyle.fill;

    final path = Path()
      ..moveTo(0, size.height * 0.6)
      ..quadraticBezierTo(
        size.width * 0.25, size.height * 0.45,
        size.width * 0.5, size.height * 0.6,
      )
      ..quadraticBezierTo(
        size.width * 0.75, size.height * 0.75,
        size.width, size.height * 0.6,
      )
      ..lineTo(size.width, size.height)
      ..lineTo(0, size.height)
      ..close();

    canvas.drawPath(path, paint);
  }

  @override
  bool shouldRepaint(WavePainter oldDelegate) => false;
}

quadraticBezierTo takes a control point and an end point, producing a smooth curve. Chain multiple curves together to get a wave, a mountain outline, a custom app bar shape — anything your design requires.

Making It Interactive with GestureDetector

A static drawing is useful, but the real power comes from combining CustomPaint with GestureDetector. You can let users draw, tap elements, or interact with anything on the canvas.

Here's a simple free-draw canvas — users drag their finger and it draws a stroke:

class DrawingCanvas extends StatefulWidget {
  const DrawingCanvas({super.key});

  @override
  State<DrawingCanvas> createState() => _DrawingCanvasState();
}

class _DrawingCanvasState extends State<DrawingCanvas> {
  final List<Offset?> _points = [];

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onPanUpdate: (details) {
        setState(() {
          final box = context.findRenderObject() as RenderBox;
          _points.add(box.globalToLocal(details.globalPosition));
        });
      },
      onPanEnd: (_) {
        setState(() => _points.add(null)); // null signals a break between strokes
      },
      child: CustomPaint(
        painter: StrokePainter(_points),
        size: Size.infinite,
      ),
    );
  }
}

class StrokePainter extends CustomPainter {
  final List<Offset?> points;

  StrokePainter(this.points);

  @override
  void paint(Canvas canvas, Size size) {
    final paint = Paint()
      ..color = Colors.black
      ..strokeWidth = 3.0
      ..strokeCap = StrokeCap.round;

    for (int i = 0; i < points.length - 1; i++) {
      if (points[i] != null && points[i + 1] != null) {
        canvas.drawLine(points[i]!, points[i + 1]!, paint);
      }
    }
  }

  @override
  bool shouldRepaint(StrokePainter oldDelegate) => oldDelegate.points != points;
}

A few things to note here: onPanUpdate fires continuously as the finger moves, providing position updates. globalToLocal converts screen coordinates to canvas-local coordinates, which is necessary when the canvas isn't at the top-left of the screen. The null sentinel between strokes means lifting and putting down the finger starts a new stroke.

Hit Testing: Knowing What Was Tapped

Sometimes you don't want to respond to taps on the whole canvas — you want to detect when the user taps a specific thing you drew. For that, CustomPainter has a hitTest method.

class TappableCirclePainter extends CustomPainter {
  final Offset center;
  final double radius;

  TappableCirclePainter({required this.center, required this.radius});

  @override
  void paint(Canvas canvas, Size size) {
    final paint = Paint()..color = Colors.orange;
    canvas.drawCircle(center, radius, paint);
  }

  @override
  bool hitTest(Offset position) {
    return (position - center).distance <= radius;
  }

  @override
  bool shouldRepaint(TappableCirclePainter oldDelegate) =>
      oldDelegate.center != center || oldDelegate.radius != radius;
}

When hitTest returns true, the GestureDetector wrapping this CustomPaint will fire its tap callbacks. When it returns false, the tap passes through as if nothing was there. This gives you precise, geometry-aware hit detection on anything you've drawn.

Animating Your Drawings

Static drawings are useful; animated ones are memorable. The standard approach is to drive a CustomPainter from an AnimationController:

class PulsingCircle extends StatefulWidget {
  const PulsingCircle({super.key});

  @override
  State<PulsingCircle> createState() => _PulsingCircleState();
}

class _PulsingCircleState extends State<PulsingCircle>
    with SingleTickerProviderStateMixin {
  late AnimationController _controller;
  late Animation<double> _radiusAnim;

  @override
  void initState() {
    super.initState();
    _controller = AnimationController(
      vsync: this,
      duration: const Duration(seconds: 1),
    )..repeat(reverse: true);

    _radiusAnim = Tween<double>(begin: 40, end: 80).animate(
      CurvedAnimation(parent: _controller, curve: Curves.easeInOut),
    );
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return AnimatedBuilder(
      animation: _radiusAnim,
      builder: (context, _) {
        return CustomPaint(
          painter: CircleRadiusPainter(radius: _radiusAnim.value),
          size: const Size(200, 200),
        );
      },
    );
  }
}

class CircleRadiusPainter extends CustomPainter {
  final double radius;
  CircleRadiusPainter({required this.radius});

  @override
  void paint(Canvas canvas, Size size) {
    final center = Offset(size.width / 2, size.height / 2);
    canvas.drawCircle(center, radius, Paint()..color = Colors.indigo);
  }

  @override
  bool shouldRepaint(CircleRadiusPainter old) => old.radius != radius;
}

AnimatedBuilder rebuilds only the subtree it wraps when the animation ticks — efficient and clean. Pass the animated value as a parameter to your painter, and return true from shouldRepaint whenever it changes.

Performance Considerations

A few things to keep in mind as your custom painters get more complex:

shouldRepaint is critical. Every time Flutter rebuilds the parent widget, it calls shouldRepaint. If you return true unconditionally, your painter redraws on every build — which is expensive. Compare the old and new delegate properties and return false when nothing meaningful has changed.

Use repaintBoundary for complex painters. Wrapping a CustomPaint in a RepaintBoundary widget tells Flutter to cache its layer separately, so it doesn't get redrawn when unrelated parts of the tree rebuild.

Avoid allocating Paint and Path objects inside paint(). These objects get created on every frame if they're constructed inside the method. Create them as fields on the painter (or use const where possible) and reuse them.

What You Can Build With This

• Custom progress indicators — arcs, segmented rings, waveform-style bars
• Interactive drawing and annotation tools
• Chart and data visualization components
• Custom onboarding illustrations that animate into view
• Game-like UI elements with touch interaction

The Canvas API is lower-level than widgets, but it's not complicated once you get the mental model: you describe what to draw in paint(), control when it redraws with shouldRepaint(), and wire up interaction through GestureDetector or hitTest. That's really the whole thing.

It was a Tuesday. I opened a project I hadn't touched in four months. My goal was to fix a simple bug — something I expected to take twenty minutes.

Instead I found a method named doMagic().

I stared at it. Why is it async? Why does it mutate context and a global variable called spookyGhost? I checked for comments. There were none. Not even a half-hearted TODO.

Past me had written this code. Present me had no idea what it did.

That's the thing about code documentation — you don't feel the need for it until you desperately need it and it isn't there.

Clean Code Isn't the Same as Understandable Code

Most developers, when pushed on this topic, will say: "I write clean code. It's self-documenting."

Here's a quick test of that:

final thing = getThing(userId, true);

What's thing? What does true mean in this context? What does getThing actually retrieve?

If you can't answer those questions from the call site alone, the code isn't self-documenting — it just looks clean. Clean code tells you how something works. Documentation tells you why it exists and when to use it. You need both.

Dart Doc Basics

Dart uses /// for documentation comments. These aren't just for humans — DartDoc and IDEs parse them, and the output shows up in hover tooltips, generated API docs, and code completion.

/// Loads the user's preferred widget based on stored preferences.
///
/// Typically called from the dashboard on first render. If no preferences
/// are found, defaults to the most popular widget for that region.
Widget getThing(String userId, bool fallbackToDefault) { ... }

That getThing call makes sense now. The method name hasn't changed, but the context around it has.

One feature worth using: wrapping identifiers in square brackets creates cross-references in generated docs.

/// Uses [userId] to look up preferences.
/// Falls back if [fallbackToDefault] is true.
///
/// See also: [UserPreferencesService]

When rendered, [userId] becomes a link to its definition. It's a small touch that pays off when navigating a larger codebase.

What to Document and What to Skip

The most common mistake developers make with documentation is writing it for the wrong things. Documenting obvious one-liners creates noise. Not documenting complex logic creates confusion.

Document when:

• The function or class is public and used across multiple files
• You used a workaround that isn't immediately obvious from reading the code
• The function has non-obvious behavior: side effects, ordering requirements, threading constraints
• A parameter name isn't self-explanatory — especially boolean flags

Skip documentation when:

• The code is a simple one-liner with a descriptive name
• The function is private and used in only one place
• The code is temporary or about to be deleted

A Documentation Structure That Works

The most useful docs follow a consistent structure: what it does, when to use it, and an example. Three layers, and you can read as much or as little as you need.

/// Shows a profile card with an optional action button.
///
/// Used on the user dashboard to highlight key account information.
/// If [onActionPressed] is null, the button is hidden automatically.
///
/// Example:
/// ```dart
/// ProfileCard(
///   user: currentUser,
///   onActionPressed: () => navigateToSettings(),
/// )
///

class ProfileCard extends StatelessWidget { final User user; final VoidCallback? onActionPressed;

// ... } ```

The first line answers "what does this do?" The middle lines answer "when and why would I use this?" The example shows actual usage. Someone new to the codebase can read just the first line and move on, or dig into the details if they need them.

Useful Things Most Developers Don't Know About Dart Docs

Markdown works inside ///. You can use *italic*, **bold**, bullet lists, and fenced code blocks. Docs don't have to be plain text.

You can reference parameters inline. [paramName] in brackets links to the parameter definition in IDEs that support it.

See also: sections are useful. If your method is closely related to another method or class, noting that explicitly saves readers from having to search.

/// {@macro myMacro} lets you reuse documentation across similar widgets or functions without copying and pasting. Useful for widget families that share common behavior.

The return value deserves a line. If a function returns something non-obvious — a nullable type, an empty list on failure, a transformed version of the input — say so explicitly.

The Practical Test

Ask a teammate to explain a method you wrote three months ago, without looking at anything other than the call site. If they can't do it in thirty seconds, you needed documentation.

This isn't about being thorough for the sake of it. It's about the fact that the person who will most benefit from your documentation is often you, six months later, at 11pm, debugging something that should have been obvious.

A Simple Daily Habit

You don't need to document your entire codebase in one sitting. That's overwhelming and it won't happen.

A more realistic approach: pick one undocumented function each day. Write three lines about what it does, when to use it, and any edge cases worth knowing. After a month, you'll have documented thirty functions, and the habit will feel automatic.

Summary

Use /// for Dart doc comments. Wrap identifiers in square brackets to create cross-references. Structure your docs in three layers: what it does, when to use it, and an example. Return value behavior and non-obvious side effects deserve explicit mention. And write docs like you're writing a note to yourself on a bad day — because at some point, that's exactly what they'll be.

The real magic was never in doMagic(). It was knowing what doMagic() was supposed to do.

I tapped. Nothing. The camera stayed focused wherever it felt like. I tapped again. Same blur, same indifference.

That's when I went digging into the camera package to figure out why, and how to actually wire this up properly.

What Needs to Happen

Tap-to-focus requires three things in sequence:

1. Capture where the user tapped on screen
2. Convert that screen position into normalized coordinates the camera understands
3. Tell the camera controller to focus at that point

Each step is straightforward on its own. The tricky part is understanding why each one is necessary.

The Full Implementation

GestureDetector(
  onTapDown: (TapDownDetails details) {
    final RenderBox box = context.findRenderObject() as RenderBox;
    final Offset localPosition = box.globalToLocal(details.globalPosition);

    final double dx = localPosition.dx / box.size.width;
    final double dy = localPosition.dy / box.size.height;

    _controller.setFocusPoint(Offset(dx, dy));
    _controller.setFocusMode(FocusMode.auto);
  },
  child: AspectRatio(
    aspectRatio: 3 / 4,
    child: CameraPreview(_controller),
  ),
),

Let's walk through what each part is doing.

Why onTapDown Instead of onTap

onTap fires after the finger lifts, and it doesn't include position data in a form that's easy to work with for this use case. onTapDown fires the moment the finger touches the screen and gives you a TapDownDetails object containing globalPosition — the exact screen coordinates of the touch. For camera focus, you want the position immediately, so onTapDown is the right handler.

Getting the Widget's Position with RenderBox

final RenderBox box = context.findRenderObject() as RenderBox;

The touch position from onTapDown is in global screen coordinates — relative to the top-left corner of the entire screen. But the camera preview widget probably doesn't start at (0, 0) on screen. There's an app bar, padding, or other widgets above it.

RenderBox knows exactly where the widget sits on screen and how large it is. You need it to convert the global position into a position that's local to the camera preview widget.

Converting Global to Local Coordinates

final Offset localPosition = box.globalToLocal(details.globalPosition);

globalToLocal translates the tap position from screen space into the widget's own coordinate space. After this, localPosition tells you where the user tapped relative to the top-left corner of the camera preview — not the screen.

Normalizing the Coordinates

final double dx = localPosition.dx / box.size.width;
final double dy = localPosition.dy / box.size.height;

The camera's setFocusPoint method expects normalized coordinates — values between 0.0 and 1.0 — where (0, 0) is the top-left and (1, 1) is the bottom-right of the preview. Dividing by the widget's width and height converts pixel positions into that normalized format.

This is the step developers most often skip or get wrong. If you pass raw pixel coordinates to setFocusPoint, the camera either ignores them or focuses in the wrong place entirely.

Telling the Camera to Focus

_controller.setFocusPoint(Offset(dx, dy));
_controller.setFocusMode(FocusMode.auto);

setFocusPoint sets where the camera should focus. setFocusMode(FocusMode.auto) tells the camera to actually trigger autofocus at that point. You need both — the point alone doesn't trigger a focus action, and setting the mode without a point falls back to whatever default behavior the camera had before.

Adding a Visual Focus Indicator

Functional tap-to-focus is good. Tap-to-focus with a visible focus ring is noticeably better — it tells the user their tap was registered and shows exactly where the camera is focusing.

Here's a simple implementation using an overlay:

class CameraWithFocus extends StatefulWidget {
  final CameraController controller;
  const CameraWithFocus({super.key, required this.controller});

  @override
  State<CameraWithFocus> createState() => _CameraWithFocusState();
}

class _CameraWithFocusState extends State<CameraWithFocus> {
  Offset? _focusPoint;
  bool _showFocusRing = false;

  Future<void> _onTapDown(TapDownDetails details) async {
    final box = context.findRenderObject() as RenderBox;
    final local = box.globalToLocal(details.globalPosition);
    final dx = local.dx / box.size.width;
    final dy = local.dy / box.size.height;

    await widget.controller.setFocusPoint(Offset(dx, dy));
    await widget.controller.setFocusMode(FocusMode.auto);

    setState(() {
      _focusPoint = local;
      _showFocusRing = true;
    });

    Future.delayed(const Duration(seconds: 1), () {
      if (mounted) setState(() => _showFocusRing = false);
    });
  }

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTapDown: _onTapDown,
      child: Stack(
        children: [
          AspectRatio(
            aspectRatio: 3 / 4,
            child: CameraPreview(widget.controller),
          ),
          if (_showFocusRing && _focusPoint != null)
            Positioned(
              left: _focusPoint!.dx - 30,
              top: _focusPoint!.dy - 30,
              child: Container(
                width: 60,
                height: 60,
                decoration: BoxDecoration(
                  border: Border.all(color: Colors.yellowAccent, width: 2),
                  borderRadius: BorderRadius.circular(4),
                ),
              ),
            ),
        ],
      ),
    );
  }
}

The ring appears at the tap location and disappears after a second. The yellow border on a slightly rounded rectangle is a common camera UI pattern — familiar to users from the default phone camera app.

One Thing Worth Knowing About Platform Behavior

setFocusPoint and setFocusMode are async operations that communicate with the native camera layer. On Android, focus response is generally fast. On iOS, there can occasionally be a small delay. Wrapping both calls in await is the correct approach — don't fire-and-forget them, especially if you're also updating UI state based on the result.

Also, not all camera hardware supports manual focus point selection. On devices where it isn't supported, the camera package may throw a CameraException. Wrapping the focus calls in a try-catch is worth doing in production code.

Summary

The implementation is compact, but each line has a specific reason for being there. onTapDown gets the position immediately. RenderBox translates it from screen space to widget space. Dividing by width and height normalizes it for the camera API. setFocusPoint and setFocusMode apply it. Add a visual indicator on top and the feature feels complete — not just functional.

Android's Activity Lifecycle

Android apps are built around the Activity class, and the OS communicates state changes through a set of well-defined callbacks:

These fire in sequence as the user navigates into and out of the activity. The most commonly used pair is onResume and onPause — when the app comes to the foreground and when it's about to leave it.

Flutter's Widget Lifecycle

Flutter replaces the activity-centric model with a widget-centric one. A StatefulWidget goes through its own lifecycle:

initState() — called once when the widget is inserted into the tree. This is the equivalent of onCreate. Initialize controllers, set up listeners, and fetch initial data here.

@override
void initState() {
  super.initState();
  _controller = AnimationController(vsync: this);
  _loadData();
}

didChangeDependencies() — called immediately after initState and again whenever the widget's inherited dependencies change. Use this when setup depends on InheritedWidget values like Theme or MediaQuery.

build() — called whenever Flutter needs to render the widget. This can be called many times, so keep it free of side effects.

didUpdateWidget() — called when the parent rebuilds and passes new configuration to this widget. Useful for reacting to external prop changes.

dispose() — called when the widget is permanently removed from the tree. This is where you release resources — cancel timers, close streams, dispose controllers. The equivalent of onDestroy.

@override
void dispose() {
  _controller.dispose();
  _subscription.cancel();
  super.dispose();
}

Observing App-Level Lifecycle in Flutter

Widget lifecycle handles what happens to a specific screen. But for app-level events — the user pressing home, switching apps, receiving a phone call — Flutter uses WidgetsBindingObserver.

Add the mixin to your StatefulWidget's state class, register it in initState, and override didChangeAppLifecycleState:

class _HomeState extends State<HomeScreen> with WidgetsBindingObserver {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    switch (state) {
      case AppLifecycleState.resumed:
        // App is in foreground and interactive
        break;
      case AppLifecycleState.inactive:
        // App is losing focus (e.g., phone call, app switcher)
        break;
      case AppLifecycleState.paused:
        // App is in background and not visible
        break;
      case AppLifecycleState.detached:
        // Engine is running but no views attached
        break;
      case AppLifecycleState.hidden:
        // All views are hidden (added in newer Flutter versions)
        break;
    }
  }
}

Always call removeObserver in dispose. Failing to do so causes memory leaks — the observer will continue receiving callbacks even after the widget is gone.

Mapping Android to Flutter

One important nuance: Flutter's state names don't map one-to-one to Android's names. When Android calls Activity.onPause, Flutter enters inactive — not paused. When Android calls Activity.onStop, Flutter enters paused. This mismatch trips up developers coming from native Android, so it's worth keeping this table close.

Practical Use Cases

Pause video playback when the app goes to the background:

@override
void didChangeAppLifecycleState(AppLifecycleState state) {
  if (state == AppLifecycleState.paused) {
    _videoController.pause();
  } else if (state == AppLifecycleState.resumed) {
    _videoController.play();
  }
}

Release the camera when the app is not visible:

@override
void didChangeAppLifecycleState(AppLifecycleState state) {
  if (state == AppLifecycleState.inactive) {
    _cameraController.dispose();
  } else if (state == AppLifecycleState.resumed) {
    _initCamera();
  }
}

Refresh stale data when returning to the foreground:

@override
void didChangeAppLifecycleState(AppLifecycleState state) {
  if (state == AppLifecycleState.resumed) {
    _refreshUserSession();
  }
}

Using the Newer AppLifecycleListener

Flutter also provides AppLifecycleListener, a newer class that offers named callbacks for each transition rather than a single switch statement. For new code, this tends to be cleaner:

late final AppLifecycleListener _listener;

@override
void initState() {
  super.initState();
  _listener = AppLifecycleListener(
    onResume: () => _onResumed(),
    onPause: () => _onPaused(),
    onInactive: () => _onInactive(),
    onDetach: () => _onDetached(),
  );
}

@override
void dispose() {
  _listener.dispose();
  super.dispose();
}

The behavior is the same as WidgetsBindingObserver, but the API is more explicit and easier to read at a glance.

Common Mistakes

Forgetting to remove the observer. If you add an observer in initState but don't remove it in dispose, the widget keeps receiving callbacks after it's been removed from the tree. This can cause exceptions or unexpected behavior.

Doing heavy work in build. Unlike onCreate, build can be called many times. Database queries, network calls, and expensive computations don't belong there — they belong in initState or triggered by state changes.

Treating inactive like paused. inactive fires for brief interruptions — phone calls, the notification shade, the app switcher — where the app is still partially visible. paused is when the app has genuinely moved to the background. The right action (pause media vs. release camera) depends on which state you're actually in.

Summary

Flutter's lifecycle is widget-first rather than activity-first, but all the same events exist — they're just expressed differently. initState and dispose bookend a widget's life. WidgetsBindingObserver and AppLifecycleListener handle app-level foreground/background transitions. Keep the Android-to-Flutter mapping in mind, always clean up in dispose, and use the named callbacks in AppLifecycleListener for clarity in new code.

They tried again. Same result. No explanation, no error code — just a flat refusal from the OS.

This is one of Android's more frustrating error messages because it's generic. It doesn't tell you what went wrong. But the actual causes are predictable, and once you know them, the fix is usually quick.

The Most Common Cause: Signing Conflict

If any version of your app is already installed on the device — even a debug build — and the APK you're trying to install is signed with a different certificate, Android will refuse the installation entirely.

Android uses signing certificates to verify that updates to an app come from the same source as the original install. A mismatched certificate looks like a completely different app trying to take over the same package name. Android blocks it.

To fix it, uninstall the existing version first:

adb uninstall com.yourpackage.name

If you have multiple devices connected, specify which one:

adb -s <device_id> uninstall com.yourpackage.name

Then reinstall:

adb install path/to/your-app.apk

This situation comes up often when switching between debug and release builds, when moving between machines (since Android Studio generates a debug keystore per machine), or when a team member builds the APK using a different signing config.

Going forward, the cleanest habit is to uninstall before installing when you know the signing config has changed.

Checking Which Devices Are Connected

If you're not sure what device IDs are available:

adb devices

This lists all connected devices and emulators. Use the ID from the output in the -s flag.

Version Code Downgrade

Android won't install an APK whose versionCode is lower than the currently installed version. This is a deliberate restriction — the OS prevents rolling back to older versions without an explicit uninstall.

If you're testing an older build or an earlier branch:

adb install -d path/to/your-app.apk

The -d flag allows downgrades. Without it, the install will fail silently if the version code is lower.

APK Corruption or Incomplete Transfer

If the APK file was partially downloaded, copied over an unstable connection, or corrupted during transfer, the package installer will reject it.

Check the file size — compare it against the original build output. If they differ, rebuild or re-download and try again.

You can also verify the APK's signature is intact before installing:

apksigner verify path/to/your-app.apk

If the APK is unsigned or the signature is broken, this will tell you.

Insufficient Storage

The device needs enough free space to unpack and install the APK. This is rarer than the other causes, but it still happens, especially on older or lower-end devices. Check available storage in Settings and clear space if needed.

"Unknown Sources" Not Enabled

When installing APKs outside of the Play Store, Android requires explicit permission to install from unknown sources. On Android 8 and above, this permission is per-app (granted to the specific app doing the installing, like a file manager or browser). On older versions, it's a global toggle.

If the install fails and the device prompts about unknown sources, grant the permission to the relevant app and try again.

Getting More Detail with ADB

The on-device error message gives you nothing useful. The ADB output gives you a specific error code:

adb install -r path/to/your-app.apk

The -r flag reinstalls while keeping app data. The output will include codes like INSTALL_FAILED_UPDATE_INCOMPATIBLE (signing mismatch), INSTALL_FAILED_VERSION_DOWNGRADE (version code too low), or INSTALL_FAILED_INSUFFICIENT_STORAGE (no space). These codes are specific enough to point directly to the fix.

Checking If the App Is Already Installed

Sometimes the app is installed under a secondary user profile or work profile and isn't visible in the main settings, but still causes a conflict. You can check:

adb shell pm list packages | grep com.yourpackage.name

If it shows up, it's installed somewhere on the device. Uninstall for all users:

adb shell pm uninstall --user 0 com.yourpackage.name

Replace 0 with the appropriate user ID if needed.

A Useful Workflow for Development

When testing during development, using adb install -r keeps the app's data intact while replacing the binary. For situations where signing has changed, always uninstall first. And when you can't figure out why an install is failing, run it via ADB and read the error code — it's almost always more useful than anything the device UI shows you.

Quick Reference

But the same mechanism can be misused. In apps that depend on real-world location data — delivery platforms, attendance systems, ride-sharing, banking — a user can install a GPS spoofing app, set a fake location, and your app will receive that fake data as if it were real. The device has no way to automatically tell the difference unless you check for it explicitly.

This article covers how to detect mock location at the app level in Android, using both modern and legacy approaches.

How Mock Location Works

On Android 6.0 and above, mock location isn't a global setting — it's granted to a specific app. The user goes to Developer Options, selects "Select mock location app," and chooses a spoofing app from the list. Once set, that app can feed arbitrary coordinates to LocationManager and FusedLocationProviderClient.

On older Android versions (5.1 and below), it was a simpler global toggle in Developer Options.

Detecting Mock Location

The most reliable approach is to check the Location object's mock flag before using the coordinates.

For Android 12 and above (API level 31+):

val locationManager = getSystemService(Context.LOCATION_SERVICE) as LocationManager
val locationListener = object : LocationListener {
    override fun onLocationChanged(location: Location) {
        if (location.isMock) {
            // Location is from a mock provider — reject or flag it
            handleMockLocation()
        } else {
            processRealLocation(location)
        }
    }
}

locationManager.requestLocationUpdates(
    LocationManager.GPS_PROVIDER,
    1000L,
    0f,
    locationListener
)

location.isMock is the modern, direct way to check this. It returns true if the location was provided by a mock provider.

For Android below API 31:

@Suppress("DEPRECATION")
fun isMockLocation(location: Location): Boolean {
    return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        location.isMock
    } else {
        location.isFromMockProvider
    }
}

isFromMockProvider is deprecated as of API 31 but still works on older devices. Using the version check ensures correct behavior across the full Android version range.

Using Fused Location Provider

If you're using FusedLocationProviderClient (which is the recommended approach for most apps), the same check applies to the Location objects you receive in your callback:

val fusedLocationClient = LocationServices.getFusedLocationProviderClient(this)

val locationRequest = LocationRequest.Builder(
    Priority.PRIORITY_HIGH_ACCURACY,
    1000L
).build()

val locationCallback = object : LocationCallback() {
    override fun onLocationResult(result: LocationResult) {
        for (location in result.locations) {
            if (isMockLocation(location)) {
                // Handle mock location
            } else {
                // Use real location
            }
        }
    }
}

fusedLocationClient.requestLocationUpdates(
    locationRequest,
    locationCallback,
    Looper.getMainLooper()
)

Checking If Mock Location Is Enabled at All

For stricter applications, you may want to reject any session where the device even has mock locations enabled — regardless of whether the current location reading is mocked. You can check this at startup:

fun isMockLocationEnabled(context: Context): Boolean {
    return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
        val locationManager = context.getSystemService(Context.LOCATION_SERVICE) as LocationManager
        locationManager.isProviderEnabled(LocationManager.GPS_PROVIDER) &&
            Settings.Secure.getInt(
                context.contentResolver,
                Settings.Secure.ALLOW_MOCK_LOCATION, 0
            ) != 0
    } else {
        Settings.Secure.getInt(
            context.contentResolver,
            Settings.Secure.ALLOW_MOCK_LOCATION, 0
        ) != 0
    }
}

Note: On API 23 and above, ALLOW_MOCK_LOCATION in Settings.Secure is always 0 because mock location is no longer a global toggle — it's per-app. For API 23+, the per-location isMock check is more relevant.

Detecting Whether a Mock Provider App Is Active

On API 23 and above, you can check whether any app is currently registered as the mock location provider:

fun hasMockLocationApp(context: Context): Boolean {
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.M) return false
    val locationManager = context.getSystemService(Context.LOCATION_SERVICE) as LocationManager
    return try {
        locationManager.addTestProvider(
            LocationManager.GPS_PROVIDER,
            false, false, false, false, false, false, false,
            Criteria.POWER_LOW, Criteria.ACCURACY_FINE
        )
        locationManager.removeTestProvider(LocationManager.GPS_PROVIDER)
        false // No mock provider was active; we were able to add one
    } catch (e: SecurityException) {
        true // A mock provider is already registered — another app owns it
    }
}

This works by trying to add a test provider. If another app has already claimed the mock provider slot, Android throws a SecurityException. That exception tells you a mock location app is active.

What to Do When Mock Location Is Detected

The right response depends on your app's use case.

For a delivery or attendance app where fake location directly enables fraud, you might block the action entirely and show an error:

if (isMockLocation(location)) {
    showError("Your location appears to be mocked. Please disable any GPS spoofing apps and try again.")
    return
}

For lower-stakes applications, you might log the detection server-side for review without blocking the user in the moment:

if (isMockLocation(location)) {
    reportSuspiciousActivity(userId, location)
}
processLocation(location)

Avoid silently doing nothing. If you're checking for mock location, you should have a plan for what happens when you find it.

Limitations

App-level detection has limits. Rooted devices can use tools like Xposed or Magisk modules to hide mock location flags entirely, making isMock return false even for spoofed coordinates. For applications where location integrity is critical, combine app-level checks with server-side validation — look for impossible speed (jumping between distant locations in seconds), trajectory anomalies, or coordinates that don't match cell tower or Wi-Fi positioning data.

No single check is foolproof. Defense in depth — multiple signals checked at different layers — gives you the most reliable protection.

Summary

location.isMock (API 31+) and location.isFromMockProvider (pre-API 31) are the primary tools for detecting fake GPS at the app level. Check them on every location update before using the coordinates. For stricter security requirements, also check whether a mock provider app is active at startup. Pair app-level detection with server-side anomaly detection for the strongest coverage.

How Android Determines Location

Android can derive a device's position from several sources simultaneously:

GPS (Global Positioning System) — communicates with satellites. High accuracy (within a few meters in open conditions), but slow to acquire a fix, doesn't work well indoors, and draws significant battery power.

Wi-Fi positioning — estimates location based on the signal strengths of nearby Wi-Fi networks, matched against a database of known networks and their physical locations. Fast, works indoors, moderate accuracy (tens of meters in cities), lower power consumption than GPS.

Cell tower triangulation — uses signal strengths from nearby cell towers. Fast acquisition, works everywhere with coverage, but accuracy is coarse — anywhere from a few hundred meters to several kilometers depending on tower density.

Sensors — accelerometers, gyroscopes, and barometers can assist location tracking by filling in gaps between GPS fixes (dead reckoning). Not a standalone source, but used by the system to smooth out position updates.

In practice, Android uses all of these together and blends the results to produce the best estimate it can.

The Traditional Approach: LocationManager

LocationManager is the lower-level API that's been in Android since API 1. It gives you direct access to each location provider independently.

GPS provider — most accurate, indoors unreliable:

LocationManager locationManager = (LocationManager) getSystemService(Context.LOCATION_SERVICE);

if (ActivityCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION)
    == PackageManager.PERMISSION_GRANTED) {
    locationManager.requestLocationUpdates(
        LocationManager.GPS_PROVIDER,
        5000,   // minimum time between updates (ms)
        10,     // minimum distance between updates (meters)
        locationListener
    );
}

Network provider — Wi-Fi and cell towers:

locationManager.requestLocationUpdates(
    LocationManager.NETWORK_PROVIDER,
    5000,
    10,
    locationListener
);

Passive provider — piggybacks on other apps' location requests:

locationManager.requestLocationUpdates(
    LocationManager.PASSIVE_PROVIDER,
    0,
    0,
    locationListener
);

The passive provider doesn't trigger any location requests on its own. It receives updates when other apps or the system request them. This is useful for background scenarios where you want location updates without contributing to battery drain yourself.

Listening for updates:

LocationListener locationListener = new LocationListener() {
    @Override
    public void onLocationChanged(Location location) {
        double latitude = location.getLatitude();
        double longitude = location.getLongitude();
        float accuracy = location.getAccuracy(); // meters
    }

    @Override
    public void onProviderEnabled(String provider) {}

    @Override
    public void onProviderDisabled(String provider) {}
};

LocationManager gives you granular control, but managing multiple providers simultaneously, handling their different characteristics, and balancing accuracy against battery life is work you have to do yourself.

The Modern Approach: Fused Location Provider

FusedLocationProviderClient is Google's abstraction over the raw providers. It fuses GPS, Wi-Fi, and cellular data internally and gives you a single, battery-efficient stream of location updates. You describe what you need — accuracy level, update frequency — and the system figures out which providers to use and when.

Setup:

FusedLocationProviderClient fusedLocationClient =
    LocationServices.getFusedLocationProviderClient(this);

Getting the last known location:

if (ActivityCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION)
    == PackageManager.PERMISSION_GRANTED) {

    fusedLocationClient.getLastLocation()
        .addOnSuccessListener(this, location -> {
            if (location != null) {
                double lat = location.getLatitude();
                double lon = location.getLongitude();
            }
        });
}

getLastLocation() returns immediately with a cached value — it's fast but can be null if the device hasn't obtained a location recently. For most "show current location" use cases, this is the right starting point.

Requesting continuous updates:

LocationRequest locationRequest = new LocationRequest.Builder(
    Priority.PRIORITY_HIGH_ACCURACY,
    10000  // interval in milliseconds
)
.setMinUpdateIntervalMillis(5000)
.build();

LocationCallback locationCallback = new LocationCallback() {
    @Override
    public void onLocationResult(LocationResult locationResult) {
        if (locationResult == null) return;
        for (Location location : locationResult.getLocations()) {
            // Process each update
        }
    }
};

fusedLocationClient.requestLocationUpdates(
    locationRequest,
    locationCallback,
    Looper.getMainLooper()
);

Priority levels:

• PRIORITY_HIGH_ACCURACY — uses GPS when available, highest accuracy, highest power cost
• PRIORITY_BALANCED_POWER_ACCURACY — uses Wi-Fi and cell, roughly city-block accuracy, lower power
• PRIORITY_LOW_POWER — city-level accuracy, minimal power
• PRIORITY_PASSIVE — no active requests, receives updates from other apps

Always stop updates when you don't need them:

@Override
protected void onStop() {
    super.onStop();
    fusedLocationClient.removeLocationUpdates(locationCallback);
}

Failing to remove updates is one of the most common causes of unexpected battery drain in location-aware apps.

Permissions

Location requires explicit runtime permissions. There are two relevant permission levels:

• ACCESS_COARSE_LOCATION — city-level accuracy, uses Wi-Fi and cell
• ACCESS_FINE_LOCATION — precise accuracy, uses GPS

Declare them in AndroidManifest.xml:

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

And request them at runtime before making any location calls. Using the Activity Result API (recommended):

val locationPermissionRequest = registerForActivityResult(
    ActivityResultContracts.RequestMultiplePermissions()
) { permissions ->
    when {
        permissions[Manifest.permission.ACCESS_FINE_LOCATION] == true -> {
            // Fine location granted
        }
        permissions[Manifest.permission.ACCESS_COARSE_LOCATION] == true -> {
            // Coarse location only
        }
        else -> {
            // No location permission
        }
    }
}

locationPermissionRequest.launch(
    arrayOf(
        Manifest.permission.ACCESS_FINE_LOCATION,
        Manifest.permission.ACCESS_COARSE_LOCATION
    )
)

For background location (tracking while the app is not in the foreground), you also need ACCESS_BACKGROUND_LOCATION, which requires additional justification in the Play Store review process.

Choosing Between LocationManager and FusedLocationProviderClient

For most apps, FusedLocationProviderClient is the right choice. It handles provider selection automatically, optimizes battery usage, and produces more consistent results than managing raw providers yourself.

LocationManager makes sense when:

• Your app runs on devices without Google Play Services (some older or specialized Android devices)
• You need direct, unfiltered GPS output for precision-critical applications
• You're building a tool that needs to reason about individual providers separately

Reading the Location Object

Regardless of which API you use, location updates arrive as Location objects. The most commonly used properties:

location.getLatitude()      // degrees, -90 to +90
location.getLongitude()     // degrees, -180 to +180
location.getAccuracy()      // estimated horizontal accuracy in meters
location.getAltitude()      // meters above WGS 84 ellipsoid (if available)
location.getSpeed()         // meters per second (if available)
location.getBearing()       // direction of travel in degrees (if available)
location.getTime()          // UTC timestamp in milliseconds
location.getProvider()      // which provider produced this update

getAccuracy() is particularly useful — it tells you the radius of the circle (in meters) within which the device's actual location falls with 68% confidence. A location with 5-meter accuracy is a confident GPS fix. A location with 1500-meter accuracy is a rough cell-tower estimate. Use the accuracy value to decide whether a given update is precise enough for your use case.

Summary

Android location works by blending multiple data sources — GPS, Wi-Fi, cell towers, and sensors. LocationManager gives you direct access to individual providers. FusedLocationProviderClient abstracts all of that into a single battery-efficient API where you describe the accuracy level you need. For most applications, start with FusedLocationProviderClient using PRIORITY_BALANCED_POWER_ACCURACY, switch to PRIORITY_HIGH_ACCURACY only when precision matters, and always remove update callbacks when the app is not actively displaying or using location data.

Step 1: Enable Flutter Web Support

First, verify that your Flutter installation has web support enabled:

flutter doctor

If web isn't listed as a supported platform, enable it:

flutter config --enable-web

You only need to do this once per Flutter installation.

Step 2: Build the Production Release

Navigate to your Flutter project directory and run:

flutter build web

This compiles your app into a set of static web assets — HTML, JavaScript, CSS, and assets — optimized for production. The output lands in the build/web/ directory.

For a build that uses CanvasKit (better rendering fidelity, slightly larger download):

flutter build web --web-renderer canvaskit

For a smaller initial download that uses the browser's built-in HTML renderer:

flutter build web --web-renderer html

If you're not sure which to use, start with the default (which is canvaskit for release builds) and test on your target devices.

Step 3: Serve the App Locally Before Deploying

Flutter doesn't include a built-in web server, but you have several options for local testing.

Quick test in Chrome (debug mode):

flutter run -d chrome

For a build closer to production performance:

flutter run -d chrome --profile

Serving the production build with Python:

cd build/web
python3 -m http.server 8000

Open http://localhost:8000 in your browser.

Serving with Node.js:

npm install -g http-server
cd build/web
http-server -p 8000

Serving with Dart's dhttpd:

dart pub global activate dhttpd
dhttpd --path build/web --port 8000

Any of these will serve the build/web folder as a static site. The Python option requires no additional installs if Python 3 is already on your system, which makes it the quickest option for a one-off check.

Step 4: Deploy to a Hosting Platform

The build/web/ directory contains everything needed to host your app — it's a standard set of static files. Any static hosting platform will work.

Firebase Hosting (recommended if you're already using Firebase):

firebase init hosting
# Point the public directory to build/web
firebase deploy

Vercel:

npm install -g vercel
cd build/web
vercel

Netlify: Drag and drop the build/web folder into the Netlify dashboard, or use the CLI:

npm install -g netlify-cli
netlify deploy --dir=build/web --prod

GitHub Pages: Copy the contents of build/web into your gh-pages branch, or use a GitHub Action to automate it on each push.

AWS S3 + CloudFront: Upload build/web to an S3 bucket configured for static website hosting, then point CloudFront at it for CDN distribution.

A Few Things Worth Knowing

The base href matters. If you're deploying to a subdirectory rather than the root of a domain, you'll need to set the base href at build time:

flutter build web --base-href /my-app/

Without this, routing and asset loading will break when the app isn't served from the root path.

Routing on the server. Flutter web uses client-side routing by default. If a user navigates directly to a deep link (e.g., yoursite.com/profile/123), the server needs to serve index.html for that path rather than returning a 404. Most hosting platforms have a configuration option for this — in Firebase it's a rewrite rule, in Netlify it's a _redirects file.

Service worker caching. Flutter web builds include a service worker for offline support. If you deploy an update and users aren't seeing it, they may have a cached version. The service worker handles cache invalidation automatically, but it can take a page refresh or two to propagate.

Summary

Enable web support, run flutter build web, verify locally with a simple HTTP server, and deploy the build/web folder to any static hosting provider. The whole process takes a few minutes once it's set up, and subsequent deployments are even faster.

This guide walks through setting up an emulator if you don't have one, starting it, and sending SMS messages via ADB.

Setting Up an Emulator

If you already have an emulator configured, skip ahead to the next section.

Install Android Studio from developer.android.com. During setup, make sure the Android Virtual Device (AVD) Manager component is selected.

Create a virtual device:

1. Open Android Studio and go to Tools > Device Manager
2. Click Create Device
3. Choose a hardware profile — Pixel 5 or Pixel 6 work well for most testing
4. Select a system image (Android 13 or 14 recommended) and download it if it's not already available
5. Adjust RAM and storage if needed, then click Finish

Starting the Emulator

From Android Studio:

Open Device Manager and click the play button next to your emulator. Wait for it to fully boot before proceeding.

From the command line:

List your available emulators:

<Android SDK path>/emulator/emulator -list-avds

Start one by name:

<Android SDK path>/emulator/emulator -avd Pixel_5_API_33

Replace Pixel_5_API_33 with the name from your AVD list.

Verify the emulator is running:

adb devices

You should see output like:

List of devices attached
emulator-5554   device

If the status shows offline instead of device, wait a few more seconds for the emulator to finish booting.

Sending a Mock SMS

Once the emulator is running, sending a test SMS is a single command:

adb emu sms send <phone_number> "<message>"

For example:

adb emu sms send 5551234567 "Your OTP is 849201"

The phone number can be any string — it doesn't need to be a real or valid number. The message can be anything, including structured formats your app might parse.

Verify it arrived:

Open the Messages app on the emulator. The SMS should appear immediately from the number you specified.

If You Have Multiple Devices Connected

If adb devices shows more than one device or emulator, target a specific one with the -s flag:

adb -s emulator-5554 emu sms send 5551234567 "Your OTP is 849201"

Use the exact device ID from the adb devices output.

Useful ADB Commands for Emulator Testing

List connected devices:

adb devices

Open a shell on the emulator:

adb shell

Install an APK:

adb install path/to/your-app.apk

Uninstall an app:

adb uninstall com.your.package.name

Clear app data (reset app state):

adb shell pm clear com.your.package.name

Restart ADB if devices aren't showing:

adb kill-server
adb start-server

Troubleshooting

"emulator: command not found"

The emulator binary isn't in your PATH. Either add <Android SDK>/emulator/ to your PATH, or use the full path to the binary each time.

Emulator not appearing in adb devices

Make sure the emulator has fully booted — the home screen should be visible. If it still doesn't appear, restart the ADB server with adb kill-server followed by adb start-server.

SMS not appearing in the Messages app

Some system images handle SMS simulation better than others. If you're on an older image, try updating to a more recent Android version. Also check that the Messages app is set as the default SMS app on the emulator.

Summary

Start the emulator, confirm it's listed with adb devices, then run adb emu sms send <number> "<message>". The SMS appears in the emulator's Messages app immediately. This works for any SMS content — OTPs, structured messages, conversation threads — and makes SMS-related feature testing significantly faster than relying on real messages.

So I built it using Android's native foreground service directly. This is a writeup of how I got there and why the approach works where most alternatives fail.

Why Most Packages Fail When the App Is Killed

The root cause is threading. Most Flutter location packages run their location logic on the Flutter engine's main UI thread. When Android kills the app — whether because the user swiped it away, the OS reclaimed memory, or the device restarted — that thread stops. The location tracking stops with it.

A foreground service is different. It runs on its own thread, independent of the app's lifecycle. Android treats foreground services with higher priority than background processes, which means the OS is far less likely to terminate them under memory pressure. They also persist across app restarts because they're registered with Android as running services, not just background tasks attached to an activity.

The other key insight: any work you do from the service thread — API calls, Firebase writes, database updates — needs to happen within that thread. If you try to hand off data back to Flutter and then push it to Firebase from the Dart side, you reintroduce the dependency on the Flutter engine being alive. The service has to own the full chain: collect location, push to backend, done.

The Approach

The architecture I landed on has three parts:

An Android foreground service that runs independently, requests location updates from FusedLocationProviderClient, and pushes coordinates to Firebase Realtime Database directly from the native layer. It displays a persistent notification showing the current coordinates — both to meet Android's foreground service requirements (a visible notification is mandatory) and as a useful debugging tool during development.

A Flutter-to-native bridge using a MethodChannel to start and stop the service. From the Flutter side, you call startService or stopService. The native side registers or kills the foreground service accordingly.

The Flutter UI layer which shows the current state (tracking active/inactive) and lets the user control it. The UI doesn't receive location updates directly — it reads from Firebase if it needs to display current position, keeping the UI and the tracking service decoupled.

Why a Foreground Service Specifically

Android has several service types. A regular background service gets killed aggressively on newer Android versions — sometimes within minutes. A JobScheduler or WorkManager task runs on a schedule but isn't appropriate for continuous real-time tracking. A foreground service with a visible notification is the only option Android explicitly supports for long-running, user-aware background work.

The notification requirement isn't optional. Android will throw an exception if you try to run a foreground service without starting it with a notification. The notification tells the user "this app is actively doing something in the background" — which is the right contract to have with the user for location tracking anyway.

Integrating with Flutter

The MethodChannel wiring is the same pattern as any other Flutter-to-native communication. On the Dart side:

const _channel = MethodChannel('com.yourapp/location_service');

Future<void> startTracking() async {
  await _channel.invokeMethod('startLocationService');
}

Future<void> stopTracking() async {
  await _channel.invokeMethod('stopLocationService');
}

On the Android (Kotlin) side, handle these calls in MainActivity and start or stop the foreground service in response. The service itself is a standard Android Service subclass that calls startForeground() in onStartCommand.

Firebase Writes From the Service Thread

This is where most implementations fall apart. The temptation is to collect location in the native service, pass it back to Flutter via a method channel, and then write to Firebase from Dart. Don't do this.

When the app is killed, the Flutter engine is gone. The method channel is gone. Any pending location updates sitting in a queue waiting to be passed to Dart disappear.

Instead, initialize the Firebase Android SDK directly in the service class and write to Realtime Database or Firestore from there. The Firebase Android SDK works perfectly from a foreground service. Your location data reaches Firebase whether or not the Flutter UI is running.

Permissions

Background location tracking requires explicit permissions. In AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />

ACCESS_BACKGROUND_LOCATION was added in Android 10 and must be requested separately from fine location — the user has to explicitly grant "Allow all the time" rather than just "Allow while using the app." Google Play also requires justification for this permission during app review.

On Android 14 and above, FOREGROUND_SERVICE_LOCATION is additionally required.

What This Approach Doesn't Cover

iOS is a different story entirely. iOS doesn't have foreground services in the Android sense. Continuous background location on iOS requires a different entitlement (Location updates background mode) and has stricter restrictions on what the app can do while backgrounded. This approach is Android-specific.

For cross-platform background location with iOS support, you'll need either a paid package or a separate native iOS implementation.

The Result

The foreground service approach works reliably across the Android versions I tested — from Android 9 through Android 14. The app can be killed by the user, the phone can restart, and as long as the service was running when those events happened, it continues running afterward (Android restarts foreground services automatically after a device reboot if START_STICKY is returned from onStartCommand).

The notification is a small UX cost, but for apps doing delivery tracking, attendance, or any use case where the user knows the app is tracking them, it's the right expectation to set. It's also honest — the user can see exactly when tracking is active.

If you're building something that genuinely needs persistent background location on Android and the package licensing fees aren't feasible, the native foreground service approach is worth the setup cost. It's more code, but it's reliable in a way that Flutter-layer solutions typically aren't.