Android setup

Android needs the least manual work. The package's manifest merges all required permissions and components into your app automatically. Your job is to handle runtime permission prompts and the Play Store declarations.

Build requirements

android/build.gradle

buildscript {
    ext {
        minSdkVersion = 24
        compileSdkVersion = 36
        targetSdkVersion = 36
    }
}

android/gradle.properties

newArchEnabled=true

Java 17 is required, which is the React Native default.

Permissions (merged automatically)

You do not need to add these to your AndroidManifest.xml. They are listed so you know what ends up in your app and can declare it in the Play Console.

<!-- Merged from react-native-background-location-pro-eval -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<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" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
<uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
<!-- Only requested at runtime if you call setMotionPermissionOptIn(true) -->
<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />

Permission	Why it is needed
Fine and coarse location	Capture location.
Background location	Keep capturing after the app leaves the screen.
Foreground service (location)	Android requires a visible notification for continuous background location.
Post notifications	Show that notification on Android 13 and newer.
Receive boot completed	Resume tracking after a reboot while tracking is desired.
Schedule exact alarm	Reliable recovery watchdog.
Ignore battery optimizations	Lets you ask users to exempt the app on aggressive ROMs.
Internet and network state	Upload points and detect connectivity.
Activity recognition	Optional extra signal for the adaptive_low_power motion gate.

Removing a permission you do not want

If you never call setMotionPermissionOptIn(true) and want to drop Activity Recognition, remove it with the manifest merger:

android/app/src/main/AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:tools="http://schemas.android.com/tools">
  <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" tools:node="remove" />
</manifest>

Do not remove the location, foreground service or notification permissions. Background tracking does not work without them.

Runtime permissions

Android grants location in steps, and each step is a separate user decision:

Android version	Flow
9 and older	One prompt grants location in foreground and background.
10	Foreground prompt, then a separate prompt with an Allow all the time option.
11 and newer	Foreground prompt. Allow all the time is only available on the app's Settings page.
13 and newer	Additionally, a notification permission prompt.

requestLocationPermission(true) handles the location steps. It asks for foreground location first, then for background location, opening Settings when the OS no longer shows a prompt. Request notifications yourself on Android 13 and newer:

permissions.ts

import {PermissionsAndroid, Platform} from 'react-native';
import LocationTracker from 'react-native-background-location-pro-eval';

export async function prepareAndroid() {
  if (Platform.OS !== 'android') return;

  if (Platform.Version >= 33) {
    await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS);
  }

  // Foreground first, then escalate to "Allow all the time"
  LocationTracker.requestLocationPermission(true);
}

Show your own explanation first

Google Play policy and good UX both expect a prominent disclosure screen before the background location request. It should say what you collect, why, and that it happens while the app is closed. Show it, then call requestLocationPermission(true).

Improving survival on aggressive devices

Stock Android keeps a foreground service alive reliably. Some vendor ROMs are stricter. Check and fix these from your settings screen:

const s = LocationTracker.getStatus();

if (!s.batteryUnrestricted) {
  LocationTracker.requestIgnoreBatteryOptimizations();
}
if (!s.exactAlarmsAllowed) {
  // Android 12+: "Alarms & reminders". Often off by default on Android 14+.
  LocationTracker.openExactAlarmSettings();
}

For vendor-specific settings, such as autostart on Xiaomi and app launch on Huawei, link users to dontkillmyapp.com.

Optional: motion permission

For the best battery life with adaptive_low_power, opt in to Activity Recognition:

LocationTracker.setMotionPermissionOptIn(true);
LocationTracker.setTrackingProfile('adaptive_low_power');

Without it, the profile still works using the other available motion signals, and it falls back to balanced rather than pausing silently.

Cleartext HTTP for local testing

Android blocks plain http:// by default. For a local test server, allow cleartext in debug builds only:

android/app/src/debug/AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:tools="http://schemas.android.com/tools">
  <application android:usesCleartextTraffic="true" tools:targetApi="28" />
</manifest>

Use HTTPS in production.

Google Play submission checklist

Apps that use background location go through an extra Play Console review:

1. App content > Location permissions: declare the background location use case, and upload a short video showing the disclosure, the prompt and the feature.
2. App content > Foreground service permissions: declare the location foreground service type with a description.
3. Data safety: declare precise location collection, its purpose, and whether it is shared.
4. Your in-app prominent disclosure must appear before the permission request.

The licensed editions include a store approval blueprint with ready-made disclosure text and reviewer notes. See Evaluation vs licensed edition.