Location and maps

Location is the most sensitive capability of the project: it proves visits (cahier §6.3, §6.4, §12 GPS), feeds the back-office live map, and must stay proportionate and transparent (cahier §8, §10; FLD-15, SEC-07). This page covers MOB-10, MDA-03, MDA-12 and the reseller app's WhatsApp region (MRA-08). Architectural choice: ADR-016.

Open decisions and the default the app is built with:

Because every threshold comes from settings, a decision taken late changes values, not code.

Permissions and consentCopy Anchor Link

The consent screen DA-04 appears after the first sign-in and until Me.consents.locationTrackingAcceptedAt is set; it reappears if a required permission is revoked.

• Consent text (validated by HOCO with counsel, D-07): positions are recorded only at tour start, at each arrival and while a tour is En cours; never during a suspension, after closing or outside tours; kept field.locationRetentionDays days (90 by default); visible to managers with the field-operations permission; the trail is used for the live map and the kilometres of the closing summary (cahier §6.9). The accepted version is written with me.update (consents.locationTrackingVersion), so the back-office can prove who accepted what.
• Order of requests: notifications first (the tour notification must be visible — that is the transparency), then foreground location. Each system dialog is preceded by one sentence in the app's own words.
• Precise location is required for check-in: Android 12+ lets users grant only approximate location (accuracy of kilometres), which can never pass the 100 m accuracy rule.
• Background location is not requested. The foreground service started by « Démarrer la tournée » keeps receiving positions with the screen off using the while-in-use permission (D-24 option 1). If HOCO ever chooses option 2, the app adds a second, separate request after foreground access, with a prominent in-app disclosure, and the Play Console declaration and video of build and release become mandatory.
• Settings transparency (DA-26): when location is used, the current tour state, the last ping sent and a link to the consent text.

apps/delegate/android/app/src/main/AndroidManifest.xml — permissions and package visibility (no ACCESS_BACKGROUND_LOCATION):

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
  <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
  <uses-permission android:name="android.permission.CAMERA" />

  <queries>
    <intent>
      <action android:name="android.intent.action.VIEW" />
      <data android:scheme="google.navigation" />
    </intent>
    <intent>
      <action android:name="android.intent.action.VIEW" />
      <data android:scheme="geo" />
    </intent>
    <intent>
      <action android:name="android.intent.action.VIEW" />
      <data android:scheme="https" />
    </intent>
  </queries>

  <application android:label="@string/app_name" android:allowBackup="false">
    <meta-data android:name="com.google.android.geo.API_KEY" android:value="${mapsApiKey}" />
  </application>
</manifest>

Photos never need a media-read permission: visit proof uses the camera only, and documents use the system photo picker.

Location serviceCopy Anchor Link

hoco_maps exposes an interface so tests and the dev flavor can replace the GPS:

abstract interface class LocationService {
  Future<LocationAccess> ensureAccess();                      // service on, permission, precision
  Future<Fix> bestFix({Duration window = const Duration(seconds: 20), double goodEnough = 30});
  Stream<Fix> tourStream(LocationPolicy policy);              // foreground service while listened
}

final class Fix {
  const Fix({required this.lat, required this.lng, required this.accuracy, required this.capturedAt, required this.isMock});
  final double lat;
  final double lng;
  final double accuracy;     // metres
  final DateTime capturedAt; // UTC
  final bool isMock;         // Position.isMocked on Android
}

GeolocatorLocationService (package geolocator) implements it:

• One-shot fixes (tour start, arrival, prospect position): listen with LocationAccuracy.best for up to 20 s, keep the most precise fix, stop early when accuracy is 30 m or better; show the live accuracy while acquiring (« Précision ± 45 m »). A fix older than 30 s is never reused for a check-in.
• Tour stream: AndroidSettings with LocationAccuracy.medium (balanced power: Wi-Fi and cell assisted, about 100 m), intervalDuration: 60 s, distanceFilter: 0, and foregroundNotificationConfig so the plugin runs a foreground service while the stream is listened to. The sampling decision is made in Dart (below).
• Coordinates are WGS84 degrees, accuracy in metres, capturedAt UTC — the GeoPoint of the API (GEO-03).

Sampling during toursCopy Anchor Link

Positions are recorded only while the tour is En cours — never while Suspendue, after closing, or outside tours (MDA-12).

final settings = AndroidSettings(
  accuracy: LocationAccuracy.medium,
  distanceFilter: 0,
  intervalDuration: const Duration(seconds: 60),
  foregroundNotificationConfig: ForegroundNotificationConfig(
    notificationTitle: l10n.tourTrackingTitle,   // « Tournée en cours »
    notificationText: l10n.tourTrackingBody,     // « Votre position est partagée jusqu'à la clôture ou la pause. »
    notificationChannelName: l10n.tourTrackingChannel,
    setOngoing: true,
    enableWakeLock: false,
  ),
);

/// "Every 5 minutes or 200 m": a sample is kept when either threshold is crossed.
/// Movement must exceed twice the fix accuracy so that GPS jitter is not taken for travel.
bool shouldRecord(Fix fix, Fix? last, LocationPolicy p) {
  if (last == null) return true;
  if (fix.capturedAt.difference(last.capturedAt) >= p.interval) return true;
  final moved = Geolocator.distanceBetween(last.lat, last.lng, fix.lat, fix.lng);
  return moved >= p.distanceMeters && moved > 2 * fix.accuracy;
}

Samples go to location_pings and are sent in batches to sync.locationPings every 15 minutes or 20 samples (offline sync › pings).

Battery. Balanced accuracy instead of GPS-best for the trail; high accuracy only for one-shot fixes; network batched every 15 minutes rather than per sample (radio wake-ups cost more than fixes); no wake lock. Many phones sold in Algeria (Xiaomi, Oppo, Realme, Samsung) kill background work aggressively: DA-26 includes a short « Optimisation de la batterie » help per brand that opens the battery-optimisation settings page — the app does not request the restricted ignore-optimisations permission. Battery drain over a full tour is measured in the field test (MOB-13); Assumption — target at most 10 % of battery over an 8-hour tour attributable to the app, to confirm there.

Escape hatch. If the field test shows sampling dying too often with the app swiped away, move the stream into a dedicated service isolate (flutter_foreground_task) — the LocationService interface stays the same.

GPS tolerance check at arrivalCopy Anchor Link

« Arrivé » (DA-08, DA-10) calls delegate.visits.arrive. It is offline-capable: the app evaluates the tolerance locally with the same algorithm and the settings snapshot, records the check-in, queues it, and the server's verdict at replay is final.

enum ArrivalVerdict { withinTolerance, accuracyTooLow, outOfTolerance, noReferenceLocation, mockLocation }

ArrivalVerdict checkArrival({required Fix fix, required GeoPoint? store, required FieldSettings s}) {
  if (fix.isMock) return ArrivalVerdict.mockLocation;
  if (fix.accuracy > s.gpsMaxAccuracyMeters) return ArrivalVerdict.accuracyTooLow;
  if (store == null) return ArrivalVerdict.noReferenceLocation;
  final d = Geolocator.distanceBetween(fix.lat, fix.lng, store.lat, store.lng);
  return d <= s.gpsToleranceMeters ? ArrivalVerdict.withinTolerance : ArrivalVerdict.outOfTolerance;
}

At replay the server may disagree (store pin corrected meanwhile, settings changed): the item comes back REJECTED or CONFLICT with the server message and the visit returns to À visiter locally, explained in the sync centre. Only one visit may be checked in at a time (409 VISIT_IN_PROGRESS); the app enforces it locally too.

MapsCopy Anchor Link

Recommendation: google_maps_flutter (Google Maps Platform), pending D-14: best coverage of Algerian streets and points of interest, native map loads on Android are not billed, and navigation hands off to the Google Maps app most delegates already use. Mapbox (mapbox_maps_flutter) would bring offline map packs but weaker geocoding of Algerian addresses. The map widgets live behind hoco_maps (TourMap, ProspectsMap), so a provider change stays inside one package.

Setup: Maps SDK for Android enabled in HOCO's Google Cloud project, one API key per flavor restricted to Android apps with the package name and the SHA-1 fingerprints (debug, upload and Play app-signing keys), injected through manifestPlaceholders (repository › flavors). Map style JSON from Akram (muted points of interest) passed to GoogleMap(style: …).

Offline, the map shows only tiles the SDK has cached; the list remains the reliable view and carries the same order, distances and statuses. Distances in lists are computed locally from the last fix (« 1,2 km », « 850 m »).

External navigationCopy Anchor Link

« Démarrer GPS » hands navigation to an installed app (FLD-07):

Future<bool> openNavigation(GeoPoint to, {String? label}) async {
  final dest = '${to.lat},${to.lng}';
  final candidates = [
    Uri.parse('google.navigation:q=$dest&mode=d'),                                   // Google Maps, turn by turn
    Uri.parse('geo:$dest?q=$dest(${Uri.encodeComponent(label ?? '')})'),              // any maps app
    Uri.https('www.google.com', '/maps/dir/', {'api': '1', 'destination': dest, 'travelmode': 'driving'}),
  ];
  for (final uri in candidates) {
    try {
      if (await launchUrl(uri, mode: LaunchMode.externalApplication)) return true;
    } on PlatformException {
      continue;
    }
  }
  return false; // show « Aucune application de navigation »
}

The <queries> entries of the manifest make these intents resolvable on Android 11+. On iOS (after the pilot, if decided) the order becomes comgooglemaps://, then Apple Maps https://maps.apple.com/?daddr=….

WhatsApp support region (reseller app)Copy Anchor Link

A fixed WhatsApp button floats over every reseller-app screen, guests included (SUP-05, RA-32). It opens the number of the user's support region (D-36 holds the regions and numbers):

The reseller app's only other location use is the optional « Utiliser ma position » on the delivery-address form (RA-19), also coarse-or-precise on the user's choice. Both are declared as optional approximate location in the data-safety form (build and release).

Testing with mock locationsCopy Anchor Link