Permissions & Setup

Detailed platform setup for iOS and Android — permissions, background modes, Expo config plugin, and store review tips.

iOS

Info.plist Keys

Add these keys to your Xcode project's Info.plist. Capacitor apps managed with Xcode should add them directly.

<key>NSLocationWhenInUseUsageDescription</key>
<string>We need your location to track your route.</string>

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Background location is needed for continuous tracking.</string>

Background Modes

Enable Location updates in Xcode > Signing & Capabilities > Background Modes, or add to Info.plist:

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

iOS Specifics

Minimum target: iOS 15.0+
SLC fallback: Significant Location Change monitoring is registered automatically. If iOS kills the app, SLC relaunches it and standard GPS tracking resumes.
Approximate location (iOS 14+): If the user grants only approximate location, the plugin emits onAccuracyWarning on start.

Android

Manifest Permissions

The Capacitor plugin contributes its manifest entries automatically during sync and manifest merge.

ACCESS_FINE_LOCATION                 <!-- GPS -->
ACCESS_COARSE_LOCATION               <!-- Wi-Fi / Cell -->
ACCESS_BACKGROUND_LOCATION           <!-- Android 10+ -->
FOREGROUND_SERVICE                   <!-- Required for foreground service -->
FOREGROUND_SERVICE_LOCATION          <!-- Android 14+ -->
POST_NOTIFICATIONS                   <!-- Android 13+ notification -->

Foreground Service

Tracking runs as a foreground service with a persistent notification. This prevents Android from killing the process. Customize the notification text via notification.title and notification.text in the config.

Minimum SDK

minSdk 26 (Android 8.0), compileSdk 36.

Runtime Permission Flow

On Android 10+, background location must be requested as a separate step after foreground permission is granted. The plugin provides a two-step flow:

import { BackgroundLocation } from '@bglocation/capacitor';

// Step 1: Check current state
const status = await BackgroundLocation.checkPermissions();
console.log('Foreground:', status.location);        // 'granted' | 'denied' | 'prompt'
console.log('Background:', status.backgroundLocation);

// Step 2: Request foreground first
if (status.location !== 'granted') {
  await BackgroundLocation.requestPermissions({ permissions: ['location'] });
}

// Step 3: Request background (Android: must be separate step)
if (status.backgroundLocation !== 'granted') {
  await BackgroundLocation.requestPermissions({ permissions: ['backgroundLocation'] });
}

// Step 4: Handle rationale (Android 11+)
BackgroundLocation.addListener('onPermissionRationale', (event) => {
  // Show custom UI explaining why "Allow all the time" is needed
  console.log(event.message);
  console.log('Should show rationale:', event.shouldShowRationale);
});

Battery Optimization (Android)

Android OEM battery killers (Xiaomi, Huawei, Samsung, etc.) can stop background tracking. The plugin detects this automatically and emits onBatteryWarning with an OEM-specific help URL from dontkillmyapp.com.

// Check battery optimization state
const batteryState = await BackgroundLocation.checkBatteryOptimization();
console.log('Ignoring optimizations:', batteryState.isIgnoringOptimizations);
console.log('Manufacturer:', batteryState.manufacturer);
console.log('Help URL:', batteryState.helpUrl);

// Open system battery settings
await BackgroundLocation.requestBatteryOptimization();

// Listen for automatic warnings on start()
BackgroundLocation.addListener('onBatteryWarning', (event) => {
  console.warn(event.message);
  // Open dontkillmyapp.com with OEM-specific instructions
  window.open(event.helpUrl);
});