Find Your Location

One of the main reasons to use a mapping application is to find out where you are.

The LocationEngine provided by the HERE SDK implements a comprehensive location solution that works with several location sources such as GPS or other Global Navigation Satellite System (GNSS) receivers, mobile network signals and Wi-Fi network signals to determine accurate locations.

Add the Required Permissions

Flutter itself provides no permission handling. Therefore, you need to adapt a few generated files for your Android and iOS native projects.

Let's start with Android.

Before you can start using the LocationEngine in your app on Android devices, you will need to add the required permissions to the app's AndroidManifest.xml file (located in your_project_dir/android/app/src/main/):

...
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" android:maxSdkVersion="22" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

Next, we can move on to iOS.

Add to the app's Info.plist file (located in your_project_dir/ios/Runner/):

<key>UIRequiredDeviceCapabilities</key>
<array>
   <string>location-services</string>
   <string>gps</string>
</array>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
   <string>This app needs to access your current location to display it on the map.</string>
<key>NSLocationWhenInUseUsageDescription</key>
   <string>This app needs to access your current location to display it on the map.</string>
<key>NSMotionUsageDescription</key>
   <string>Motion detection is needed to determine more accurate locations, when no GPS signal is found or used.</string>

The permission_handler plugin can be used to request specific permissions from the user. Please refer to the plugin's official site for more information. Alternatively, you can find platform specific code for requesting permissions in the "Find your Location" section of the Developer's Guide for the HERE SDK for Android and Developer's Guide for the HERE SDK for iOS.

An app using native location services such as GPS will ask for the user's permission. Not all devices provide the same capabilities and may have certain hardware restrictions that can lead to varying results.

Prior to using the LocationEngine, it may be a good idea to check if the native location services are enabled. On most Android devices a user can decide to turn the location services on, and even increase the accuracy, by opening the device's Settings and navigating to the Security & location section. On most iOS devices, a user can navigate to Settings > Privacy > Location Services to make sure that the location services are on.

Handle the User's Consent Whether to Gather Information

The LocationEngine contains functionality that can gather certain information about the surroundings of the mobile device in order to improve the HERE services used by the HERE SDK. An example of such information is the strength of the nearby Wi-Fi and mobile network signals.

The HERE SDK provides a ConsentEngine that handles the flow to acquire the user’s consent to collect such data. In addition, it allows to retrieve the current status and to revoke a previous decision whether to collect data or not. The application must ensure that this is accessible for the user at all times.

Setting localization

Consent engine supports upto 31 different languages. Language used when the dialog is shown is automatically selected based on current device language setting. In case the device language is not in supported languages, English will be used instead. The code snippet below shows how to configure your application to support localized consent dialog.

// File: main.dart

import 'package:flutter/material.dart';
import 'package:here_sdk/consent.dart';

import 'PositioningExample.dart';

// ...

void main() {
    runApp(
        MaterialApp(
            // Add consent localization delegates.
            localizationsDelegates: HereSdkConsentLocalizations.localizationsDelegates,
            // Add supported locales.
            supportedLocales: HereSdkConsentLocalizations.supportedLocales,
            home: MyApp(),
        ),
    );
}

// ...

class MyApp extends StatefulWidget {
    @override
    PositioningExample createState() => PositioningExample();
}

Requesting user consent

Before starting the LocationEngine, you need to ensure that the user's consent to collect the before mentioned information has been handled. It does not matter what the answer was (if the user accepted the collection of data or not), only that they were shown the consent dialog and that an answer was given. The LocationEngine will return LocationEngineStatus.USER_CONSENT_NOT_HANDLED status when attempting to start it without having handled the user's consent.

The code snippet below creates an instance of the ConsentEngine, checks if the user’s consent has already been requested and if not, invokes a UI dialog (pictured also below) which explains the details of information gathering to the user, and provides them with the possibility to either grant or deny permission.

ConsentEngine _consentEngine = ConsentEngine();

// ...

Future<void> _ensureUserConsentRequested() async {
  // Check if user consent has been handled.
  if (_consentEngine.userConsentState == ConsentUserReply.notHandled) {
    // Show dialog.
    await _consentEngine.requestUserConsent(context);
  }

  _updateConsentInfo();
  _startLocating();
}

It is recommended to not call requestUserConsent() while loading a map scene.

Note that the code for _updateConsentInfo() is left out here. It basically shows the current consent decision of the user.

The dialog contains a link to a web page describing the privacy practices of HERE and supports 37 languages. When shown, the dialog will be displayed according to the device's language preferences, or in English, if they are not supported.

The user's response persists between the usage sessions of the application and can be retrieved with the userConsentState property, which returns a Consent.UserReply value:

switch (_consentEngine.userConsentState) {
  case ConsentUserReply.granted:
    //The user has previously given permission.
    break;
  case ConsentUserReply.denied:
    // The user has previously denied permission.
    break;
  case ConsentUserReply.notHandled:
    //The user has not been asked for consent.
    break;
  case ConsentUserReply.requesting:
    //The dialog is currently being shown to the user.
    break;
  default:
    throw Exception("Unknown consent state.");
}

Keep in mind that the application must provide the possibility for the user to see what response they have given earlier, by accessing the userConsentState property. In addition, the application must also make it possible for the user to change their mind on the consent at any time, by calling the requestUserConsent() method and displaying the consent dialog again.

On Android, when requestUserConsent() is called the HERE SDK shows a new Activity containing the dialog. When the dialog is dismissed, the previous Activity is resumed. If a MapView is shown before the dialog is opened, the MapView will be paused until it is shown again.

// ...

// Platform class from dart:io library provides a way to check on what platform your app is running.
import 'dart:io' show Platform;

// ...

class ConsentPreferencesPage extends StatefulWidget {
  ConsentPreferencesPage({Key key, this.title}) : super(key: key);

  final String title;

  @override
  State<ConsentPreferencesPage> createState() {
    //Use different states according to the platform the app is running on.
    if (Platform.isAndroid) {
      return _ConsentPreferencesPageAndroid();
    }
    return _ConsentPreferencesPageOther();
  }

// ...

// This state shows what response the user has given to the consent, by accessing the consentEngine.userConsentState property. Additionally, it allows the user to change their mind on the consent by including a button "Manage Consent" that calls the requestUserConsent() method and displays the consent dialog again.
class _ConsentPreferencesPageAndroid extends State<ConsentPreferencesPage> with WidgetsBindingObserver {
  final ConsentEngine _consentEngine = ConsentEngine();

  String _getConsentAnswer() {
    switch (_consentEngine.userConsentState) {
      case ConsentUserReply.granted:
        //The user has previously given permission.
        return "You have granted consent to the data collection.";
      case ConsentUserReply.denied:
        // The user has previously denied permission.
      case ConsentUserReply.notHandled:
        //The user has not been asked for consent.
      case ConsentUserReply.requesting:
        //The dialog is currently being shown to the user.
        return "You have denied consent to the data collection.";
      default:
        throw Exception("Unknown consent state.");
    }
  }

  // ...

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Container(
        margin: const EdgeInsets.only(left: 25, right: 25),
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Flexible(
                child: Text(
                    'The Location Engine contains functionality that can gather certain '
                        'information about the surroundings of the mobile device in order '
                        'to improve the HERE services used by the HERE SDK. An example '
                        'of such information is the strength of the nearby Wi-Fi and '
                        'mobile network signals.'
                ),
            ),
            SizedBox(height: 20),
            Flexible(
                child: Text(
                    _getConsentAnswer(),
                ),
            ),
            SizedBox(height: 20),
            PlatformButton(
                child: const Text("Manage Consent"),
                onPressed: () {
                  setState(() {
                    _consentEngine.requestUserConsent(context);
                  });
                }
            ),
          ],
        ),
      ),
    );
  }

// ...

// This state informs the user that there is currently no data collection.
class _ConsentPreferencesPageOther extends State<ConsentPreferencesPage> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Container(
        margin: const EdgeInsets.only(left: 25, right: 25),
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Flexible(
              child: Text('This app does not collect any data on this platform.'),
            ),
          ]
        )
      )
    );
  }
}

Customize the Consent Dialog

It is possible to customize the look and the content of the dialog. For this, ask HERE to certify the application’s own customized user consent dialog. Once the certification is received the application can use the methods grantUserConsent() and denyUserConsent() to communicate the user’s response to the HERE SDK - calling requestUserConsent() is no longer necessary when HERE approves that a custom dialog can be initiated by an application. The communicated user’s response is persisted by the HERE SDK, and the method getUserConsentState() can be used to retrieve the previously given response.

Learn more about this option or initiate the certification process by contacting HERE via your HERE Sales representative or via our help page.

Create a LocationEngine

Creating a new LocationEngine is simple:

LocationEngine _locationEngine = LocationEngine();

Get the Last Known Location

Once the engine is initialized, the last known location can be obtained, as long as the engine has been started at least once before and received at least one position, otherwise null will be returned. This information will remain, so the last known location will also be available between application sessions.

Location? myLastLocation = _locationEngine.lastKnownLocation;

if (myLastLocation != null) {
    // Log the last known location coordinates.
    print("Last known location: " + myLastLocation.coordinates.latitude.toString() + ", " + myLastLocation.coordinates.longitude.toString());
}

Get Notified on Location Events

Next before starting the LocationEngine, it's a good idea to register a LocationStatusListener so that you will be notified of changes in the engine's status. To do so, implement the LocationStatusListener abstract class and register it with the location engine's addLocationStatusListener() method. Check the API Reference for more information on the different statuses.

class PositioningExample extends State<MyApp> implements LocationStatusListener {

  @override
  onFeaturesNotAvailable(List<LocationFeature> features) {
    for (var feature in features) {
      print("Feature not available: " + feature.toString());
    }
  }

  @override
  onStatusChanged(LocationEngineStatus locationEngineStatus) {
    print("LocationEngineStatus: " + locationEngineStatus.toString());
  }

// ...

// Add the listener.
_locationEngine.addLocationStatusListener(this);

Additionally, through the listener's onFeaturesNotAvailable() callback you will be notified of any LocationFeature that is not available. If a feature that you need is not available, contact your HERE representative.

The last thing to consider before starting the engine is registering a LocationListener, which provides the onLocationUpdated() callback that sends a notification once a new Location is detected. You can do so in a similar way as with the previously mentioned LocationStatusListener:

class PositioningExample extends State<MyApp> implements LocationListener {
    @override
    onLocationUpdated(Location location) {
        print("Received location: " + location.coordinates.latitude.toString() + ", " + location.coordinates.longitude.toString());
    }

// ...

// Add the listener.
_locationEngine.addLocationListener(this);

Except for the current geographic coordinates and the timestamp, all other Location fields are optional. For example, the received Location object may contain the information about the bearing angle, as well as the current speed, but this is not guaranteed to be available. Unavailable values will be returned as null. What kind of sources are used for positioning (as defined by the LocationAccuracy used to start the engine, see the Start and Stop Receiving Locations section below), and the device's capabilities affect what fields will be available.

You can add as many LocationStatusListener and LocationListener as you need by calling the respective addLocationStatusListener() and addLocationListener() methods.

Start and Stop Receiving Locations

You are now ready to call the LocationEngine's startWithLocationAccuracy() method:

class PositioningExample extends State<MyApp> implements LocationListener, LocationStatusListener {

    LocationEngine _locationEngine = LocationEngine();
    ConsentEngine _consentEngine = ConsentEngine();

// ...

    if (_consentEngine.userConsentState == ConsentUserReply.notHandled) {
        await _consentEngine.requestUserConsent(context);
    }

    _updateConsentInfo();
    _startLocating();

// ...

void startLocating() {
    _locationEngine.addLocationListener(this);
    _locationEngine.addLocationStatusListener(this);
    _locationEngine.startWithLocationAccuracy(LocationAccuracy.bestAvailable);
}

The most straightforward way to start the engine is by passing it one of the pre-defined LocationAccuracy modes, as in the code snippet above. See the table below or check the API Reference for more information about all the available modes.

After the LocationEngine has been started, you will receive LocationEngineStatus.alreadyStarted if you try to start it again without calling stop() first. You can use the method isStarted() to check if the engine is started or not. Similarly, if you have started a LocationEngine and try to start another one without stopping the first, you will get LocationEngineStatus.alreadyStarted error. Only one engine can be started at a time.

If you don't want to receive more location updates, you can stop the engine by calling the stop() method. Remember to remove the listeners when they are no longer needed:

void stopLocating() {
    _locationEngine.removeLocationStatusListener(this);
    _locationEngine.removeLocationListener(this);
    _locationEngine.stop();
}

In general, it is recommended to listen to the AppLifecycleState and to stop the LocationEngine when an app gets disposed, see the positioning_app for an example on GitHub.

Pause Updates while Stationary on iOS Devices

On iOS devices the LocationEngine will, by default, pause the location updates when location data is not expected to change. This can be used, for example, to improve battery life when the device is stationary. This feature can be controlled by the method LocationEngine.setPauseLocationUpdatesAutomatically().

Enable Background Updates

In case you want to continue receiving location updates while the application is running in the background, you first need to enable such capability by adding the needed permissions. On Android, this is only necessary if you target Android 10 (API level 29) or higher. Add the following permission to the app's AndroidManifest.xml file:

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

On iOS add the following key to the app's Info.plist file:

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

Remember that the user needs to be requested for autorization. Check the Add the Required Permissions section for suggestions on how to request permissions from the user.

Once the autorization is cleared, you are all set. On iOS devices, you can enable or disable location updates in the background with the LocationEngine.setBackgroundLocationAllowed() method. They are enabled by default. Also on iOS devices, you can set the visibility of the application's background location indicator with the method LocationEngine.setBackgroundLocationIndicatorVisible(). It is visible by default.

The final check for iOS devices would be to ensure that the location updates won't pause when the device is stationary by passing false to the LocationEngine.setPauseLocationUpdatesAutomatically() method.

In addition, it is recommended to listen to the AppLifecycleState when you have background updates enabled.

Specify Location Options on Android Devices

If you are targeting Android devices and want more control over what options are taken into account when generating the locations, you can create a LocationOptions object, configure it to your liking, and start the engine by calling the startWithLocationOptions(locationOptions) method.

// ...

// Create a new LocationOptions object. By default all options are enabled.
LocationOptions locationOptions = LocationOptions();

// Use WiFi and satellite (GNSS) positioning only.
locationOptions.wifiPositioningOptions.enabled = true;
locationOptions.satellitePositioningOptions.enabled = true;
locationOptions.sensorOptions.enabled = false;
locationOptions.cellularPositioningOptions.enabled = false;

// Receive a location approximately every minute, but not more often than every 30 seconds.
locationOptions.notificationOptions.smallestIntervalMilliseconds = 30000;
locationOptions.notificationOptions.desiredIntervalMilliseconds = 60000;

_locationEngine.startWithLocationOptions(locationOptions);

// ...

The table below shows an overview of the available LocationAccuracy modes, and how they are internally translated to LocationOptions in Android and to CLLocationAccuracy modes in iOS:

Access Accuracy Information from a Location

In Android, the field horizontalAccuracyInMeters found in the Location object (also known as radius of uncertainty) tells us that the true geographic coordinates lie with a probability of 68% within that radius. This can be used to draw a halo indicator around the current location.

Similarly for the altitude, a verticalAccuracyInMeters value of 10 meters means that the real altitude lies with a probability of 68% in the range between altitude - 10m and altitude + 10m. Other accuracy values, like bearingAccuracyInDegrees and speedAccuracyInMetersPerSecond will follow the same rule: a smaller uncertainty results in a better accuracy.

Achieving probabilities other than 68% (CEP68)

What if the given probability of 68% (CEP68) is not enough - is it possible to achieve an accuracy of 99%? Yes, it is: Since the given circular error probability (CEP) follows a chi-squared distribution with two degrees-of-freedom, it is easy to calculate the desired probability based on the following formulas:

The table above can be used to visualize various probability levels for a halo indicator on the map. For example, if the horizontal accuracy is 20 meters, you can (roughly) double the radius to achieve a probability of 99%. The accuracy value is always given as CEP68, that means:

CEP99 = 2.01 x CEP68 = 2.01 x 20m = 40.2m

Now you can draw a radius of 40.2 meters around the found location - and with a probability of 99%, the real location will lie within that circle. On the other hand, the probability for a radius of 0 meters is 0%.

Legal Requirement

Using the HERE SDK location features requires you to show the HERE SDK consent dialog in your application as described above. Users must be able to see their current consent decision and to revoke any previous consent decision - otherwise, you are not allowed to use the HERE SDK location features and you must refer to the platform location APIs instead.

Tutorial: Show your Current Location on a Map

A LocationIndicator is used for representing device's current location on map. Before the indicator is updated with a current location value, a default Location is set, which can be the last known location - or just any place the user should see before the first location update arrives.

//Default start-up location.
static final GeoCoordinates _defaultGeoCoordinates = GeoCoordinates(52.530932, 13.384915);

// LocationIndicator object to represent device's current location.
LocationIndicator _locationIndicator;

// ...

void _addMyLocationToMap(Location myLocation) {
    if (_locationIndicator != null) {
        _hereMapController?.removeLifecycleListener(_locationIndicator!);
    }

    // Set-up location indicator.
    _locationIndicator = LocationIndicator();
    _locationIndicator?.locationIndicatorStyle = LocationIndicatorIndicatorStyle.pedestrian;
    _locationIndicator?.updateLocation(myLocation);
    _hereMapController?.addLifecycleListener(_locationIndicator!);

    // Point camera at given location.
    _hereMapController?.camera.lookAtPointWithDistance(
        myLocation.coordinates,
        _cameraDistanceInMeters,
    );

    // Update state's location.
    setState(() {
        _location = myLocation;
    });
}

// ...

    Location? location = _locationEngine.lastKnownLocation;

    if (location == null) {
        // No last known location, use default instead.
        location = Location.withCoordinates(_defaultGeoCoordinates);
        location.time = DateTime.now();
    }

    _addMyLocationToMap(location);

// ...

void _updateMyLocationOnMap(Location myLocation) {
    if (_locationIndicator == null) {
      return;
    }

    // Update location indicator's location.
    _locationIndicator?.updateLocation(myLocation);

    // Point camera at given location.
    _hereMapController?.camera.lookAtPoint(myLocation.coordinates);

    // Update state's location.
    setState(() {
        _location = myLocation;
    });
}

As shown in the implementation above, you can pass the Location object to the location indicator by calling updateLocation(). In this example, the goal is to track the user's current location - therefore, the map viewport's center location is updated as well.