Skip to content

Add native location-provider override (setExternalLocation) - #1145

Open
trueshail wants to merge 1 commit into
mapbox:mainfrom
amusetechnologies:pr/external-location-provider
Open

Add native location-provider override (setExternalLocation)#1145
trueshail wants to merge 1 commit into
mapbox:mainfrom
amusetechnologies:pr/external-location-provider

Conversation

@trueshail

@trueshail trueshail commented Sep 3, 2026

Copy link
Copy Markdown

Summary

Adds a way to drive the map puck from an externally-supplied location instead of Mapbox's own GPS-only location engine — a custom LocationProvider/HeadingProvider on both platforms, wired through a small setExternalLocation/clearExternalLocation API on LocationSettings.

Resolves #1085.

What's here

  • iOS: ExternalLocationProvider.swift implements LocationProvider + HeadingProvider, registered via mapView.location.override(provider:).
  • Android: ExternalLocationProvider.kt implements LocationProvider, registered via mapView.location.setLocationProvider(...).
  • Both: a hand-written FlutterMethodChannel/MethodChannel exposing setExternalLocation/clearExternalLocation, kept isolated in LocationController/LocationComponentController so it stays easy to rebase onto future releases. This is deliberately not Pigeon-generated — the Pigeon input specs for this plugin aren't published, only the generated output.
  • Dart: LocationSettings.setExternalLocation/.clearExternalLocation wrap the new channel.
  • Docs: a README section under "User location" (matching the existing "Location puck" subsection's style), a doc-comment example on setExternalLocation itself, and a CHANGELOG entry.

The override activates lazily on the first setExternalLocation call; clearExternalLocation restores the platform default provider (GPS). Until either is called, map behavior is unchanged from stock mapbox_maps_flutter — this is purely additive.

Usage

// Start driving the puck from an external source.
mapboxMap.location.setExternalLocation(
    latitude: 37.775,
    longitude: -122.418,
    heading: 90.0,
    accuracy: 5.0);

// Later, hand the puck back to the platform's default provider (e.g. GPS).
mapboxMap.location.clearExternalLocation();

Motivation

Useful for apps that need to drive the puck from a custom positioning source — e.g. an indoor-positioning SDK while inside a mapped venue, falling back to GPS outdoors — without Mapbox's own location engine ever being in the loop. Per #1085, this seems like a capability others have asked for too.

Testing

  • flutter analyze clean on the touched files.
  • Full test suite passing, including 3 new tests for the new channel (test/external_location_test.dart).
  • Verified on real iOS simulator and Android debug builds of the example app.

Rebased onto current main from our original branch point at v2.29.0 — no conflicts.

@trueshail
trueshail requested a review from a team as a code owner September 3, 2026 23:58
@trueshail
trueshail requested a review from evil159 September 3, 2026 23:58
@CLAassistant

CLAassistant commented Sep 3, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@trueshail
trueshail force-pushed the pr/external-location-provider branch 2 times, most recently from 7fd6db0 to 8735c9b Compare September 4, 2026 00:12
Adds a custom LocationProvider on both platforms so the map puck can
be driven by an externally-supplied location instead of Mapbox's own
GPS-only location engine:

- iOS: ExternalLocationProvider.swift implements LocationProvider +
  HeadingProvider, registered via mapView.location.override(provider:).
- Android: ExternalLocationProvider.kt implements LocationProvider,
  registered via mapView.location.setLocationProvider(...).
- Both: a hand-written FlutterMethodChannel/MethodChannel exposing
  setExternalLocation/clearExternalLocation, deliberately NOT
  Pigeon-generated (Mapbox doesn't publish the Pigeon input specs for
  this plugin, only the generated output), kept isolated in
  LocationController/LocationComponentController to stay easy to
  rebase onto future upstream releases.
- Dart: LocationSettings.setExternalLocation/.clearExternalLocation
  wrap the new channel.

The override activates lazily on first setExternalLocation call and
clearExternalLocation restores the platform default provider (GPS) -
until called, map behavior is unchanged from stock mapbox_maps_flutter.

Verified: flutter analyze clean, full test suite passing (29/29,
including 3 new tests for the new channel), and real iOS simulator +
Android debug builds of the example app both succeed.

Branched from v2.29.0.
@trueshail
trueshail force-pushed the pr/external-location-provider branch from 8735c9b to 89ff52b Compare September 4, 2026 13:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support Location Override

2 participants