#Android background setup

Start with the foreground setup, then add only the declarations required by the background features your product enables. Android permission prompts must be requested in stages; declarations alone do not grant access.

#Feature-to-permission map

The library manifest contributes its service/receiver infrastructure and the foreground-service, activity, boot, and wake-lock declarations. Your merged app manifest must still contain the foreground/background location and Android 13+ notification declarations used by your configuration.

If the app does not use optional background features, inspect the merged manifest and remove inherited optional declarations with manifest-merger tools:node="remove" rules as described in Privacy and Compliance.

#Minimum continuous-tracking declarations

Use this set only when the app actually starts continuous background tracking:

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

The library's merged manifest supplies:

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

Do not add ACTIVITY_RECOGNITION behavior unless you use standalone activity events or trackingMode: 'activityAware'. Do not enable startOnBoot merely because the library declares the boot receiver.

#Request in a user-understandable sequence

1. Explain and request foreground location while the user is using the feature.
2. Show the feature working in the foreground.
3. Explain why the specific product outcome needs access when the app is not active, then request background access.
4. On Android 13+, request notification permission before starting continuous tracking and explain the persistent tracking notification.
5. Request Activity Recognition only when enabling activity-aware behavior.

Continue to Background permissions for the API flow. Never loop a denied prompt or open settings without a user action and explanation.

#Verify the setup

After native generation and manifest merging:

yarn nitro-geolocation doctor

Inspect android/app/build/intermediates/merged_manifests (the exact Gradle path can vary) to confirm that enabled capabilities are present and unused optional capabilities are removed. Then test foreground grant, background grant, denied, notification-denied, swipe-away, and reboot behavior on the Android versions and OEMs you ship. The reliability contract defines what the library can and cannot guarantee.

#Custom notification actions (2.0)

Add serializable { id, title } buttons through foregroundService.actions. Android supports at most three buttons in total, including stopActionTitle. IDs must be unique and both fields must be non-empty.

import {
  configureBackgroundLocation,
  onBackgroundEvent,
  registerBackgroundTask,
  type BackgroundEvent
} from 'react-native-nitro-geolocation/background';

function handleEvent(event: BackgroundEvent) {
  if (event.type === 'notificationAction') {
    console.log('Notification action:', event.notificationAction.actionId);
    // Apply your app's pause/resume, checkpoint, or other action here.
  }
}

// Register these before starting tracking.
const subscription = onBackgroundEvent(handleEvent);
registerBackgroundTask(handleEvent);

await configureBackgroundLocation({
  android: {
    foregroundService: {
      notificationTitle: 'Tracking your trip',
      notificationText: 'Location recording is active',
      stopActionTitle: 'Stop',
      actions: [
        { id: 'pause', title: 'Pause' },
        { id: 'checkpoint', title: 'Mark checkpoint' }
      ]
    }
  }
});

// Remove the live listener when its owner unmounts.
subscription.remove();

Custom buttons emit notificationAction events; your handler decides what they do. The existing stopActionTitle button stops tracking natively, even without JavaScript. Custom buttons do not implicitly stop or restart tracking.

Action configuration survives service restoration. Taps from an older tracking run or for an ID absent from the current configuration are ignored. When persistence is enabled, action events are also available through getStoredBackgroundEvents({ types: ['notificationAction'] }); acknowledge recovered events as usual. If no live listener handles the event, Android uses the registered Headless JS task. Register the task at your app entry point.

This is Android-only. iOS does not expose a customizable foreground-service notification, and Web does not support the background API.