Mapbox Maps SDK for Flutter
External Api Integration by Mapbox Inc.
Description
Mapbox provides the interactive map tiles and Flutter SDK used for the peer mentor geographic map view, enabling coordinators and administrators to visualise mentor distribution and proximity for assignment matching. Required for Norges Blindeforbund's large-fylke matching workflow. Mapbox is preferred over Google Maps for its superior Flutter SDK, offline tile support, and competitive pricing for Nordic-region projects.
Detailed Analysis
Mapbox provides the interactive map view that enables coordinators and administrators to visualise peer mentor geographic distribution across Norway's large fylker, directly supporting Norges Blindeforbund's requirement for proximity-based assignment matching. Mapbox was selected over Google Maps for its superior Flutter SDK maturity, offline tile support for low-connectivity rural areas, and competitive pricing for Nordic-region projects. The pricing model is per map load above a 50,000-load free tier monthly threshold — cost scales with active map usage and must be monitored as the user base grows. Critically, mentor location coordinates are never transmitted to Mapbox; they are used only for local marker placement, meaning Mapbox receives no personal data.
The public access token used for tile loading is acceptable in the mobile binary as it is scoped to styles and tiles read only. The map view is architecturally supplementary — a full mentor list fallback is always available — so a Mapbox outage has no impact on the core assignment workflow. Offline tile regions can be pre-downloaded for coordinators operating in areas with poor connectivity.
Mapbox integration requires a Mapbox account, an access token, and platform-specific token configuration: the MBXAccessToken key in iOS Info.plist and the token in Android's res/values/developer-config.xml. The mapbox_maps_flutter package (>=2.0.0) must be added as a dependency. Seven components depend on Mapbox: the MapProviderIntegration, MapViewScreen, MapMarkerWidget, MentorInfoPopup, MapFilterPanel, ViewToggleButton, and MentorListFallback. Development effort includes marker clustering configuration, Norwegian locale for map labels, and optional offline tile region download setup.
Testing must cover map load success on both platforms, tile cache behaviour when offline, marker rendering performance with realistic mentor data volumes, and the MentorListFallback activation when map tiles fail to load. The monthly map load count must be monitored against the 50,000 free tier limit — a billing alert should be configured at 80% of the threshold to avoid unexpected charges. The MentorListFallback component means map unavailability is a graceful degradation rather than a blocking failure, reducing delivery risk. Ongoing maintenance is low once configured, with Mapbox SDK updates following Flutter package release cycles.
The Mapbox Maps SDK for Flutter (mapbox_maps_flutter ^2.0.0) is used for all map rendering. Authentication uses a public access token scoped to styles:read and tiles:read, configured via MAPBOX_ACCESS_TOKEN environment variable and injected into platform-specific config files (iOS Info.plist MBXAccessToken; Android res/values/developer-config.xml). The token is safe to include in the mobile binary as it is restricted to tile and style reads. Map style is configurable — Mapbox Streets or a custom Norwegian-locale style are the options.
Mentor markers are rendered client-side using local coordinate data from PostGIS queries; no mentor location data is sent to Mapbox servers. The MapMarkerWidget handles clustering via configurable cluster radius to manage marker density at regional zoom levels. Tile load failures are caught and trigger display of the MentorListFallback widget, which renders the full contact list without map dependency. Offline tile regions are downloadable for pre-caching via the SDK's offline API, supporting coordinators in low-connectivity areas.
Map load count is tracked against the 50,000/month free tier ceiling with a billing alert at threshold. Initial map render with mentor markers targets < 2s. The MapFilterPanel and ViewToggleButton provide UI controls for filtering and switching between map and list views, both implemented independently of the Mapbox SDK to ensure the list fallback is always fully functional.
Using Components (7)
Dependencies (3)
Authentication
| Type | Api Key |
| Requirements | Mapbox access token (public token for map tiles), Token configured per platform in app, iOS: token in Info.plist MBXAccessToken key, Android: token in res/values/developer-config.xml |
| Scopes | styles:readtiles:read |
Configuration
MAPBOX_ACCESS_TOKEN
Error Handling
Monitoring
Performance
| Latency | < 2s for initial map render with mentor markers |
| Availability | Graceful degradation to list view — map is supplementary feature |
Cost Implications
| Pricing Model | Per map load pricing above free tier threshold |