#Background Location overview

Use the Background API when the product must record location while the app is not active, monitor geofences, recover events recorded while JavaScript was unavailable, or run native delivery behavior. For an active screen, use useWatchPosition() instead; it has a simpler permission and lifecycle model.

import {
  startBackgroundLocation,
  onBackgroundLocation,
  stopBackgroundLocation,
} from 'react-native-nitro-geolocation/background';

Keep the /background import explicit. It separates background permissions, storage, and native services from foreground code and is safe for shared web bundles to import, but background behavior itself is native-only.

#Understand the platform contract first

Background delivery is best effort, not an unbounded execution guarantee. Read the reliability contract before promising behavior for termination, reboot, suspension, or exact delivery timing.

#Complete the happy path

#1. Configure one platform

• Android background setup separates foreground, continuous tracking, notification, activity, and boot permissions.
• iOS background setup stages When In Use → Always and adds only the background/motion capabilities the feature needs.

Do not copy both platforms' complete permission lists into a foreground-only app.

#2. Request background access

Background permissions requests foreground and background access in the OS-required sequence and handles settings/app-resume round trips. Ask only after explaining the user-facing background outcome.

#3. Start and own the subscription

Start and stop tracking shows a complete continuous-tracking flow, one subscription owner, cleanup, and explicit stop behavior. A visible Android notification is part of the running product experience, not an implementation detail.

#4. Verify on a real device

Confirm foreground, background, screen lock, permission changes, process loss, stored-event recovery, and any reboot behavior your app claims. Use the long-run E2E guide and test the Android OEMs/iOS versions you ship.

The minimum success outcome is:

• permission status reports foreground and background granted;
• tracking status reports configured and started;
• a live location is received while the app is active and backgrounded;
• persisted events can be drained after JavaScript restarts when persistence is enabled;
• stopping tracking removes the listener and native tracking state.

#Add advanced behavior only when needed

• Storage Recovery for events recorded while JavaScript was not running. Consumers must process recovered IDs idempotently.
• Android Headless JS for Android JavaScript delivery when the app process can be started for a task.
• Native HTTP Sync for native delivery. Treat endpoints, credentials, retention, retries, and server deduplication as security/product contracts.
• Geofencing for enter/exit behavior with documented platform limits.
• Activity Recognition for standalone activity events or activity-aware tracking and its extra permission.
• iOS Location Lifecycle for automatic pause and app-triggered resume observation.
• 2.0 Unified Background Events when upgrading stored provider or lifecycle event consumers.

#Diagnose silent delivery

import {
  diagnoseBackgroundLocation,
} from 'react-native-nitro-geolocation/background';

const diagnosis = await diagnoseBackgroundLocation();

if (!diagnosis.healthy) {
  console.warn(diagnosis.issues.join('\n'));
}

The diagnosis returns { healthy, status, issues } and identifies recorded native errors, missing permissions, disabled device services, a configured but stopped tracker, notification/service problems, or a tracker still waiting for a fix. Continue to Background troubleshooting.

#Type imports

Background code can import its contracts from the same self-contained subpath:

import type {
  BackgroundLocation,
  BackgroundLocationOptions,
  BackgroundLocationStatus,
  GeolocationResponse,
  LocationError,
  PermissionStatus,
} from 'react-native-nitro-geolocation/background';

Before shipping persistence or native sync, complete the Privacy and Compliance and Release readiness reviews.