Enable background updates

In case you want to continue receiving location updates while the application UI is not visible on Android, you need to implement a foreground service. This approach informs the user that your app is actively using HERE Positioning in the background.

Permissions: Ensure you have requested and been granted ACCESS_FINE_LOCATION. The ACCESS_BACKGROUND_LOCATION permission is not required when using a foreground service for location updates.
Android 14+ Requirement: For apps targeting Android 14 (API level 34) or higher, you must also declare and request the FOREGROUND_SERVICE_LOCATION permission at runtime:

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

Foreground Service Declaration: You must declare your service in AndroidManifest.xml and specify the foregroundServiceType for apps targeting Android 12 (API level 31) or higher:

<service
    android:name=".ForegroundService"
    android:foregroundServiceType="location" >
    ...
</service>

To keep the application receiving location updates when the UI is not visible, you need to start a foreground service. Remember that using a foreground service for HERE Positioning and is different from requesting a background location permission. Check the Android documentation and Foreground Services documentation for more details. Note that the positioning example app does not fully demonstrates the use of a foreground service for all supported Android versions.

Note

If your application targets Android API level 28 or lower, as long as your app already requests the permissions mentioned in the Add permissions section, you don't need to make any changes to support background updates.

If your application needs to access the device's location even when it is not running in the foreground and is not actively using a foreground service (for example, for features like geofencing that trigger actions based on location changes when the app is closed), you must request the ACCESS_BACKGROUND_LOCATION permission. This permission grants access beyond foreground use.

When it's Needed: This permission is only required if your app needs location access after the user navigates away from it and you are not using a foreground service to signal ongoing location use. Typical use cases include geofencing or collecting location data passively without continuous user interaction.
Manifest Declaration: Add the following permission to the app's AndroidManifest.xml file. This is required for apps targeting Android 10 (API level 29) or higher:

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

Runtime Request: Requesting background location is a multi-step process:
1. First, request foreground location permissions (ACCESS_FINE_LOCATION).
2. Only after foreground permission is granted, you can then separately request ACCESS_BACKGROUND_LOCATION. This often requires presenting additional UI explaining why your app needs this level of access.
Restrictions and Policy:
- Granting ACCESS_BACKGROUND_LOCATION requires explicit user approval via a separate permission dialog. Users can choose to grant foreground-only access even if background access is requested.
- Apps requesting this permission undergo stricter review on the Google Play Store. You must provide a clear and strong justification for needing background location access that aligns with permitted use cases. Failure to justify may lead to app rejection or removal.

Note

Requesting background location permissions is significantly different from using a foreground service for location updates. Most use cases requiring location while the app UI isn't visible should use a foreground service instead. Check the Android documentation on background location access for detailed implementation guidance and policy requirements.

Note

If your application targets SDK version 28 or lower, as long as your app already requests for the permissions mentioned in the earlier Add permissions section, you don't need to make any changes to support background updates.

If your application targets SDK version 33 or higher, and uses foreground service then your app needs to request for POST_NOTIFICATIONS permission.

A full working flow showing background location updates can be seen in the "PositioningWithBackgroundUpdates" example app you can find on GitHub.

Below we explain how to create this app and how to use a foreground service to fetch location updates when running in background. The foreground service uses Android's notification mechanism to notify the user on background activities. It also allows a user to interact with the service.

Step 1: Create a subclass of Service

Extend the Service class and override the necessary methods. In this tutorial we called the class ForegroundService - a full implementation of this class can be found on GitHub.

public class ForegroundService extends Service {
    private static final String CHANNEL_ID = "ForegroundServiceChannel";

    @Override
    public void onCreate() {
        super.onCreate();
    }

    @Override
    public int onStartCommand(Intent intent, int flags, int startId) {
        String input = intent.getStringExtra("inputExtra");
        createNotificationChannel();
        Intent notificationIntent = new Intent(this, MainActivity.class);
        PendingIntent pendingIntent = PendingIntent.getActivity(this,
                0, notificationIntent, 0);

        Notification notification = new NotificationCompat.Builder(this, CHANNEL_ID)
                .setContentTitle("Foreground Service")
                .setContentText(input)
                .setSmallIcon(R.drawable.ic_stat_name)
                .setContentIntent(pendingIntent)
                .build();

        startForeground(1, notification);

        // Here is a good place to confirm HERE legitimate interest privacy notice inclusion.
        // You can already start the LocationEngine here.

        return START_NOT_STICKY;
    }

    @Override
    public void onDestroy() {
        // Here is a good place to stop the LocationEngine.
        super.onDestroy();
    }

    @Nullable
    @Override
    public IBinder onBind(Intent intent) {
        // Here we do not use a binder to interact with the foreground service.
        return null;
    }
}

Step 2: Create a notification channel

For creating a notification channel, add the below code to our ForegroundService class:

private void createNotificationChannel() {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
        NotificationChannel serviceChannel = new NotificationChannel(
                CHANNEL_ID,
                "Foreground Service Channel",
                NotificationManager.IMPORTANCE_DEFAULT
        );

        NotificationManager manager = getSystemService(NotificationManager.class);
        manager.createNotificationChannel(serviceChannel);
    }
}

Step 3: Insert location handling

In order to confirm HERE Privacy Notice inclusion, confirmHEREPrivacyNoticeInclusion() method needs to be injected as shown on GitHub or in the Find Your Location section. This part is always required - even if you do not want to enable background updates.

Also, you definitely want to implement methods such as startLocating() to receive location updates and stopLocating() when an app gets disposed. These methods are always required - even if you do not want to enable background updates. The code can be found on GitHub or in the Find Your Location section.

Similarly, you need to implement a LocationListener to handle location updates. For this you can use the same code as for non-background updates.

Step 4: Start the foreground service from your Activity

In order to enable getting background updates, call startService(). The service can be stopped by calling stopService(), for example via dedicated buttons. The following two methods can be added to your Activity:

public void startService() {
    Intent serviceIntent = new Intent(this, ForegroundService.class);
    serviceIntent.putExtra("inputExtra", "Foreground Service Example in Android");
    ContextCompat.startForegroundService(this, serviceIntent);
}

public void stopService() {
    Intent serviceIntent = new Intent(this, ForegroundService.class);
    stopService(serviceIntent);
}

Step 5: Declare the service and add permissions

In the AndroidManifest you need to add the name of your Service class and type of foreground service.

Note we also need to explicitly ask the user to allow background updates by adding the ACCESS_BACKGROUND_LOCATION permission. In addition, we need the FOREGROUND_SERVICE and the POST_NOTIFICATIONS permissions.

Targeting Android 14 or later

Beginning with Android 14 (API level 34), you must declare an appropriate service type for each foreground service. That means you must declare the location service type for the ForegroundService in your app manifest, and also request the FOREGROUND_SERVICE_LOCATION permission. For more information regarding foreground service types, see Android developer documentation.

Below you can find an example, together with all other permissions that are required by HERE Positioning:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.foregroundservice">

    <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.CHANGE_NETWORK_STATE" />
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
    <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"/>

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">

        <service
            android:name=".ForegroundService"
            android:enabled="true"
            android:exported="true"
            android:foregroundServiceType="location" />

        <activity
            android:name=".MainActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

That's it - now your app will be fully operable in background and can receive location events - even if the device is locked. Note that handling of location updates in background can be a sensitive topic, so make sure to inform your users why you need this feature - and be aware that the Android OS will notify the user on the lock screen that your app is running and active. Consider to use less frequent location updates to avoid draining the battery when not necessary, for example, by setting a less-frequent LocationAccuracy, like for example, HUNDREDS_OF_METERS.