Flutter Native - GPS Positioning

This guide covers how to use GPS positioning with the Wemap SDK, including required permissions and configuration.

---

Overview

GPS is the default location source. It uses the device's built-in GPS (and assisted positioning) to determine the user's location. It works best outdoors and in buildings with good satellite visibility.

Use GPS when:

• Your app is used outdoors (navigation, outdoor maps)
• Indoor precision is not critical
• You want minimal permissions (no camera)

---

Permissions

GPS requires location permission only.

Android

Add to android/app/src/main/AndroidManifest.xml:

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

iOS

Add to ios/Runner/Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>We need access to your location to show your position on the map and provide navigation.</string>

If you use the permission_handler package, add to your Podfile's post_install block:

config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
  '$(inherited)',
  'PERMISSION_LOCATION=1',
]

---

Enabling GPS

GPS is the default. You can set it explicitly:

MapOptions(
  mapID: yourMapId,
  token: yourToken,
  environment: Environment.PROD,
  locationSource: LocationSource.GPS,  // Default; can be omitted
)

---

Locating the user with GPS

After granting location permission and once the map is ready, call mapManager.locateMe() to request the user's GPS position.

With LocationSource.GPS, locateMe() fetches user location and draws the blue dot without automatically centering the camera.

If you want the camera to follow the blue dot, call a camera/tracking method explicitly (for example mapManager.enableTrackingMode() or mapManager.enableTrackingWithHeadingMode()).

late MapManager _mapManager;

void _onMapReady(MapData mapData, MapManager mapManager) {
  _mapManager = mapManager;
  // Ensure location permission is granted, then locate the user
  _locateUser();
}

Future<void> _locateUser() async {
  // Request permission if needed (e.g. using permission_handler)
  _mapManager.locateMe();
  // Optional: move camera to user explicitly
  _mapManager.enableTrackingMode();
}

---

User location button

With userLocationButtonEnabled: true, users can tap a button to trigger location behavior. Depending on the current camera mode/state, this may switch tracking modes. The SDK will request location permission when needed.

WemapMap(
  options: mapOptions,
  userLocationButtonEnabled: true,
)

---

Retrieving user location

After the map is ready, you can access user position and attitude via MapManager, which is provided in the onMapReady callback.

Important: with GPS, call mapManager.locateMe() first to ensure user location is initialized before calling mapManager.getUserLocation().

Method	Description
mapManager.getUserLocation()	Get current user position once. Returns Coordinate? with latitude, longitude, level. Returns null if location is not yet available.
mapManager.getUserLocationStream()	Stream<Coordinate> — continuous position updates
mapManager.getUserAttitudeStream()	Stream<Attitude> — device heading (headingDegrees 0–360) for the blue dot arrow

Future<void> _loadUserLocation() async {
  final hasPermission = await _ensureLocationPermission();
  if (!hasPermission) return;

  mapManager.locateMe();
  final coordinate = await mapManager.getUserLocation();
  if (coordinate != null) {
    print('User at: ${coordinate.latitude}, ${coordinate.longitude}');
  }
}

// Or listen to continuous updates
mapManager.getUserLocationStream().listen((coordinate) {
  // Handle each position update
});