Permissions & Setup

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

iOS

Info.plist Keys

Expo projects: the config plugin injects these automatically from app.json. Bare RN apps need to add them manually.

<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>

Expo Config Plugin

The React Native package ships with an Expo config plugin that injects permissions, background modes, and the license key during prebuild.

{
  "expo": {
    "plugins": [
      [
        "@bglocation/react-native",
        {
          "licenseKey": "BGL1-eyJ...",
          "locationWhenInUsePermission": "We use your location to track your route.",
          "locationAlwaysPermission": "Background location for continuous tracking."
        }
      ]
    ]
  }
}

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

Expo prebuild and the Android manifest merger add the required permissions from the React Native package.

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 {
  addListener,
  checkPermissions,
  requestPermissions,
} from '@bglocation/react-native';

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

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

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

// Step 4: Handle rationale (Android 11+)
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.

import {
  addListener,
  checkBatteryOptimization,
  requestBatteryOptimization,
} from '@bglocation/react-native';

// Check battery optimization state
const batteryState = await checkBatteryOptimization();
console.log('Ignoring optimizations:', batteryState.isIgnoringOptimizations);

// Open system battery settings
await requestBatteryOptimization();

// Listen for automatic warnings on start()
addListener('onBatteryWarning', (event) => {
  console.warn(event.message);
});