### Run Example Application

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/example/README.md

Commands to install dependencies and launch the example app on an Android device or emulator.

```bash
# Install dependencies
yarn

# Start Metro bundler
yarn example start

# Run on Android device/emulator
yarn example android
```

--------------------------------

### Install Pods and Run iOS Example

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/development/contributing.md

Installs iOS dependencies using CocoaPods and then runs the example application. This is necessary after modifying native iOS code.

```sh
cd example/ios && pod install && cd ../.. 
yarn example ios
```

--------------------------------

### Start Example App Metro Bundler

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/development/contributing.md

Starts the Metro bundler for the example application. This allows for live reloading of JavaScript changes.

```sh
yarn example start
```

--------------------------------

### Geofencing Quick Start

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/guides/geofencing.md

A minimal example demonstrating how to register a geofence and listen for transition events.

```APIDOC
## Geofencing Quick Start

### Description
This example shows how to initialize geofencing, add a geofence, and react to transition events.

### Method
N/A (Component Example)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```typescript
import React, { useState } from 'react';
import { View, Text, Button } from 'react-native';
import {
  useGeofencing,
  useGeofenceEvents,
  GeofenceTransitionType,
} from '@gabriel-sisjr/react-native-background-location';

function GeofenceDemo() {
  const [enterCount, setEnterCount] = useState(0);
  const { geofences, addGeofence, maxGeofences } = useGeofencing();

  useGeofenceEvents({
    onTransition: (event) => {
      if (event.transitionType === GeofenceTransitionType.ENTER) {
        setEnterCount((prev) => prev + 1);
      }
    },
  });

  const handleAddGeofence = async () => {
    await addGeofence({
      identifier: 'office',
      latitude: -23.5505,
      longitude: -46.6333,
      radius: 200,
    });
  };

  return (
    <View>
      <Text>Active: {geofences.length} / {maxGeofences}</Text>
      <Text>Enter events: {enterCount}</Text>
      <Button title="Add Office Geofence" onPress={handleAddGeofence} />
    </View>
  );
}
```

### Response
N/A
```

--------------------------------

### Install and Link Package

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/README.md

Install the package and its iOS dependencies. Autolinking handles most setup, but manual Info.plist configuration is required for iOS.

```bash
yarn add @gabriel-sisjr/react-native-background-location
cd ios && pod install
```

--------------------------------

### Complete Trip Management Example

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/guides/background-tracking.md

A comprehensive example showcasing the lifecycle of a trip, including starting, stopping, refreshing locations, and clearing data using the `useBackgroundLocation` hook.

```APIDOC
## Complete Trip Management Example

```typescript
import {
  useBackgroundLocation,
  LocationAccuracy,
  NotificationPriority,
} from '@gabriel-sisjr/react-native-background-location';
import type { TrackingOptions } from '@gabriel-sisjr/react-native-background-location';

function TripManager() {
  const {
    isTracking,
    tripId,
    locations,
    startTracking,
    stopTracking,
    refreshLocations,
    clearCurrentTrip,
  } = useBackgroundLocation();

  const handleStartTrip = async () => {
    const options: TrackingOptions = {
      accuracy: LocationAccuracy.HIGH_ACCURACY,
      updateInterval: 5000,
      distanceFilter: 25,
      notificationOptions: {
        title: 'Trip Tracking',
        text: 'Tracking your trip in background',
        priority: NotificationPriority.LOW,
      },
    };

    const id = await startTracking(undefined, options);
    if (id) {
      console.log('Trip started:', id);
      // Save trip ID to your backend
      await saveTrip({ id, startedAt: Date.now() });
    }
  };

  const handleEndTrip = async () => {
    if (tripId) {
      // Upload locations before stopping
      await uploadLocations(tripId, locations);
      await clearCurrentTrip();
      await stopTracking();
    }
  };

  return (
    <View>
      <Button title="Start Trip" onPress={handleStartTrip} />
      {isTracking && (
        <>
          <Button title="Refresh" onPress={refreshLocations} />
          <Button title="End Trip" onPress={handleEndTrip} />
        </>
      )}
    </View>
  );
}
```
```

--------------------------------

### Install the library

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/static/llms-full.txt

Install the package using yarn or npm.

```bash
yarn add @gabriel-sisjr/react-native-background-location
# or
npm install @gabriel-sisjr/react-native-background-location
```

--------------------------------

### Run Example App on Android

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/development/contributing.md

Builds and runs the example application on an Android device or emulator.

```sh
yarn example android
```

--------------------------------

### Implement Background Tracking with Notifications

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/guides/notification-customization.md

A complete example demonstrating how to start background tracking with custom notification options and handle notification actions.

```typescript
import React from 'react';
import { View, Text, Button } from 'react-native';
import {
  useBackgroundLocation,
  useLocationUpdates,
  LocationAccuracy,
  NotificationPriority,
  stopTracking,
} from '@gabriel-sisjr/react-native-background-location';

function NotificationDemo() {
  const { startTracking, isTracking } = useBackgroundLocation();

  useLocationUpdates({
    onNotificationAction: (event) => {
      if (event.actionId === 'stop') {
        stopTracking();
      }
    },
  });

  const handleStart = async () => {
    await startTracking(undefined, {
      accuracy: LocationAccuracy.HIGH_ACCURACY,
      updateInterval: 5000,
      notificationOptions: {
        title: 'Delivery Active',
        text: 'En route to destination',
        priority: NotificationPriority.LOW,
        channelName: 'Delivery Tracking',
        color: '#2196F3',
        showTimestamp: true,
        subtext: 'Background tracking',
        actions: [
          { id: 'stop', label: 'Stop Tracking' },
        ],
      },
    });
  };

  return (
    <View>
      <Text>Tracking: {isTracking ? 'Active' : 'Inactive'}</Text>
      <Button
        title={isTracking ? 'Stop' : 'Start with Custom Notification'}
        onPress={isTracking ? () => stopTracking() : handleStart}
      />
    </View>
  );
}
```

--------------------------------

### Run Example App on iOS

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/development/contributing.md

Builds and runs the example application on an iOS simulator or physical device.

```sh
yarn example ios
```

--------------------------------

### Test installation in a new project

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/development/publishing.md

Verify the package installation process in a clean React Native environment.

```bash
npx react-native init TestApp
cd TestApp
npm install @gabriel-sisjr/react-native-background-location
```

--------------------------------

### Example Application Execution Commands

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/CONTRIBUTING.md

Commands to manage the example application lifecycle, including starting the Metro packager and running the app on specific platforms.

```shell
yarn example start
yarn example android
yarn example ios
```

--------------------------------

### Project Directory Structure

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/example/README.md

Overview of the example application file structure.

```text
example/
  src/
    App.tsx           # Main app with tracking controls and live map
  android/            # Android-specific configuration
  ios/                # iOS configuration (stub)
```

--------------------------------

### Beta Version Format Examples

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/development/ci-cd.md

Shows the structure of automatically generated beta version strings, including timestamps and commit SHAs, as well as custom suffix examples.

```text
0.2.0-beta.20251026143022.a1b2c3d
       |--- timestamp ---|-- SHA --|

Or with custom suffix:
0.2.0-rc1
0.2.0-beta1
```

--------------------------------

### Install Beta Version of Package

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/development/publishing.md

Install the beta version of the package using npm or yarn to test pre-release features. The '@beta' tag specifies the pre-release channel.

```bash
npm install @gabriel-sisjr/react-native-background-location@beta
# or
yarn add @gabriel-sisjr/react-native-background-location@beta
```

--------------------------------

### Project Setup and Dependency Installation

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/CONTRIBUTING.md

Commands to initialize the development environment. This installs all dependencies for the monorepo using Yarn workspaces.

```shell
yarn
```

--------------------------------

### Install iOS Pods

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/getting-started/installation.md

After completing iOS-specific Info.plist and Xcode configurations, install the necessary pods using the command line. This step is crucial for linking native iOS dependencies.

```bash
cd ios && pod install && cd ..

```

--------------------------------

### Install CocoaPods Dependencies

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/getting-started/ios-setup.md

Commands to install or clean and reinstall project dependencies.

```bash
cd ios && pod install && cd ..
```

```bash
cd ios
rm -rf Pods Podfile.lock
pod install --repo-update
cd ..
```

--------------------------------

### Before: Notification Options (v0.10.x)

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/migration/v0-12-0.md

Example of how notification-related options were passed directly to `startTracking` in v0.10.x.

```typescript
startTracking({
  updateInterval: 5000,
  notificationTitle: 'Location Tracking',
  notificationText: 'Tracking in background',
  notificationChannelName: 'Background Location',
  notificationChannelId: 'location_channel',
  notificationPriority: NotificationPriority.LOW,
  notificationSmallIcon: 'ic_notification',
  notificationLargeIcon: 'ic_notification_large',
  notificationColor: '#4CAF50',
  notificationShowTimestamp: true,
  notificationSubtext: 'Example',
  notificationActions: [{ id: 'stop', label: 'Stop' }],
});
```

--------------------------------

### Complete App Example with Background Location Tracking

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/getting-started/quick-start.md

This example shows a full React Native application setup for background location tracking. It includes permission handling, tracking configuration, error management, and data upload functionality. Use this as a comprehensive template for your project.

```tsx
import React, { useEffect } from 'react';
import { View, Text, Button, Alert, StyleSheet } from 'react-native';
import {
  useLocationPermissions,
  useBackgroundLocation,
  useLocationUpdates,
  LocationAccuracy,
  NotificationPriority,
  type TrackingOptions,
} from '@gabriel-sisjr/react-native-background-location';

const TRACKING_OPTIONS: TrackingOptions = {
  accuracy: LocationAccuracy.HIGH_ACCURACY,
  updateInterval: 5000,
  fastestInterval: 3000,
  distanceFilter: 50,
  notificationOptions: {
    title: 'Trip Recording',
    text: 'Recording your route in the background',
    priority: NotificationPriority.LOW,
    channelName: 'Trip Tracking',
  },
};

export default function App() {
  const { permissionStatus, requestPermissions, isRequesting } = 
    useLocationPermissions();

  const {
    startTracking,
    stopTracking,
    isTracking,
    tripId,
    locations,
    error,
    clearError,
    refreshLocations,
    clearCurrentTrip,
  } = useBackgroundLocation({
    onTrackingStart: (id) => console.log('Tracking started:', id),
    onTrackingStop: () => console.log('Tracking stopped'),
    onError: (err) => Alert.alert('Tracking Error', err.message),
  });

  const { lastLocation } = useLocationUpdates({
    onLocationUpdate: (loc) => {
      console.log(`[${new Date(loc.timestamp).toISOString()}]`,
        loc.latitude, loc.longitude);
    },
    onLocationWarning: (warning) => {
      console.warn(`[${warning.type}] ${warning.message}`);
    },
  });

  // Show errors
  useEffect(() => {
    if (error) {
      Alert.alert('Error', error.message, [
        { text: 'Dismiss', onPress: clearError },
      ]);
    }
  }, [error, clearError]);

  const handleToggleTracking = async () => {
    if (isTracking) {
      await stopTracking();
    } else {
      await startTracking(undefined, TRACKING_OPTIONS);
    }
  };

  const handleUploadAndClear = async () => {
    if (!tripId || locations.length === 0) return;

    try {
      // Upload to your server
      await fetch('https://your-api.com/trips', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          tripId,
          locations: locations.map((loc) => ({
            latitude: parseFloat(loc.latitude),
            longitude: parseFloat(loc.longitude),
            timestamp: loc.timestamp,
          })),
        }),
      });

      await clearCurrentTrip();
      Alert.alert('Success', 'Trip data uploaded and cleared');
    } catch (err) {
      Alert.alert('Upload Failed', 'Please try again later');
    }
  };

  // Permission screen
  if (!permissionStatus.location.hasPermission) {
    return (
      <View style={styles.container}>
        <Text style={styles.title}>Location Permission Required</Text>
        <Button
          title={isRequesting ? 'Requesting...' : 'Grant Permissions'}
          onPress={requestPermissions}
          disabled={isRequesting}
        />
      </View>
    );
  }

  return (
    <View style={styles.container}>
      <Text style={styles.title}>
        {isTracking ? 'Tracking Active' : 'Ready'}
      </Text>

      {tripId && <Text style={styles.info}>Trip: {tripId}</Text>}
      <Text style={styles.info}>Points: {locations.length}</Text>

      {lastLocation && (
        <Text style={styles.info}>
          Last: {lastLocation.latitude}, {lastLocation.longitude}
        </Text>
      )}

      <View style={styles.buttonGroup}>
        <Button
          title={isTracking ? 'Stop' : 'Start'}
          onPress={handleToggleTracking}
        />

        {isTracking && (
          <Button title="Refresh" onPress={refreshLocations} />
        )}

        {!isTracking && locations.length > 0 && (
          <Button title="Upload & Clear" onPress={handleUploadAndClear} />
        )}
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: 'center', padding: 20 },
  title: { fontSize: 22, fontWeight: 'bold', textAlign: 'center', marginBottom: 16 },
  info: { fontSize: 14, textAlign: 'center', marginBottom: 8 },
  buttonGroup: { marginTop: 20, gap: 12 },
});

```

--------------------------------

### Install Project Dependencies

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/development/contributing.md

Installs all necessary dependencies for the monorepo using Yarn workspaces. This command should be run in the root directory.

```sh
yarn
```

--------------------------------

### startTracking

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/api-reference/functions.md

Starts location tracking in the background for a specific trip.

```APIDOC
## startTracking

### Description
Starts location tracking in the background for a specific trip. When the native module is not available, logs a warning and returns a fallback tripId.

### Parameters
#### Path Parameters
- **tripIdOrOptions** (string | TrackingOptions) - Optional - Either a trip identifier string or tracking configuration options.
- **options** (TrackingOptions) - Optional - Tracking configuration options.

### Response
#### Success Response (200)
- **tripId** (string) - The effective tripId (either the provided one or the auto-generated one).
```

--------------------------------

### Complete Trip Management with useBackgroundLocation Hook

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/guides/background-tracking.md

A comprehensive example demonstrating the full lifecycle of trip management using the `useBackgroundLocation` hook. It covers starting tracking with custom options, handling trip IDs, uploading locations, clearing data, and stopping tracking.

```javascript
import {
  useBackgroundLocation,
  LocationAccuracy,
  NotificationPriority,
} from '@gabriel-sisjr/react-native-background-location';
import type { TrackingOptions } from '@gabriel-sisjr/react-native-background-location';

function TripManager() {
  const {
    isTracking,
    tripId,
    locations,
    startTracking,
    stopTracking,
    refreshLocations,
    clearCurrentTrip,
  } = useBackgroundLocation();

  const handleStartTrip = async () => {
    const options: TrackingOptions = {
      accuracy: LocationAccuracy.HIGH_ACCURACY,
      updateInterval: 5000,
      distanceFilter: 25,
      notificationOptions: {
        title: 'Trip Tracking',
        text: 'Tracking your trip in background',
        priority: NotificationPriority.LOW,
      },
    };

    const id = await startTracking(undefined, options);
    if (id) {
      console.log('Trip started:', id);
      // Save trip ID to your backend
      await saveTrip({ id, startedAt: Date.now() });
    }
  };

  const handleEndTrip = async () => {
    if (tripId) {
      // Upload locations before stopping
      await uploadLocations(tripId, locations);
      await clearCurrentTrip();
      await stopTracking();
    }
  };

  return (
    <View>
      <Button title="Start Trip" onPress={handleStartTrip} />
      {isTracking && (
        <>
          <Button title="Refresh" onPress={refreshLocations} />
          <Button title="End Trip" onPress={handleEndTrip} />
        </>
      )}
    </View>
  );
}

```

--------------------------------

### Auto-Start Tracking

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/guides/background-tracking.md

Demonstrates how to configure the `useBackgroundLocation` hook to automatically start tracking location updates when the component mounts.

```APIDOC
## Auto-Start Tracking

The `useBackgroundLocation` hook supports auto-starting on mount.

```typescript
function AutoTrackingScreen() {
  const { isTracking, locations } = useBackgroundLocation({
    autoStart: true,
    options: {
      accuracy: LocationAccuracy.HIGH_ACCURACY,
      updateInterval: 5000,
      notificationOptions: {
        priority: NotificationPriority.LOW,
      },
    },
    onError: (error) => {
      Alert.alert('Error', error.message);
    },
  });

  return (
    <View>
      <Text>Auto-tracking: {isTracking ? 'Active' : 'Inactive'}</Text>
      <Text>Points collected: {locations.length}</Text>
    </View>
  );
}
```
```

--------------------------------

### Add Single Geofence

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/guides/geofencing.md

Example of how to add a single geofence to the monitoring system.

```APIDOC
## POST /api/geofences (Conceptual)

### Description
Adds a single geofence to be monitored by the background location service.

### Method
POST (Conceptual)

### Endpoint
`/api/geofences` (Conceptual)

### Parameters
#### Request Body
- **identifier** (string) - Required - Unique identifier for the geofence.
- **latitude** (number) - Required - The latitude of the geofence center.
- **longitude** (number) - Required - The longitude of the geofence center.
- **radius** (number) - Required - The radius of the geofence in meters.

### Request Example
```typescript
import { addGeofence } from '@gabriel-sisjr/react-native-background-location';

await addGeofence({
  identifier: 'office',
  latitude: -23.5505,
  longitude: -46.6333,
  radius: 200,
});
```

### Response
#### Success Response (200)
Indicates the geofence was successfully added.

#### Response Example
```json
{
  "success": true,
  "message": "Geofence added successfully"
}
```
```

--------------------------------

### Install Package with npm or yarn

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/getting-started/installation.md

Use npm or yarn to add the background location library to your project. Autolinking is used, so no manual linking is required.

```bash
# Using npm
npm install @gabriel-sisjr/react-native-background-location

# Using yarn
yarn add @gabriel-sisjr/react-native-background-location
```

--------------------------------

### Define Usage Description Strings

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/getting-started/ios-setup.md

Examples of compliant and non-compliant usage description strings for App Store review.

```xml
<key>NSLocationWhenInUseUsageDescription</key>
<string>We use your location to show your current position on the map
and record trip routes while you are using the app.</string>

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We use your location in the background to continuously record
your trip route, even when the app is not visible. This ensures
complete and accurate trip records for fleet management.</string>
```

```xml
<!-- Too vague -->
<string>This app uses your location.</string>

<!-- Too technical -->
<string>Required for CLLocationManager background updates via
CoreLocation framework.</string>
```

--------------------------------

### Start Tracking

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/getting-started/quick-start.md

Initiates background location tracking. You can start with default options, custom accuracy, update intervals, distance filters, or provide a custom trip ID.

```APIDOC
## Start Tracking

### Description
Initiates background location tracking. This function can be called with default options, custom accuracy, update intervals, distance filters, or a custom trip ID.

### Method
`startTracking(tripId?: string, options?: TrackingOptions)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### `tripId` (string, Optional)
- A custom identifier for the tracking session.

#### `options` (object, Optional)
- **accuracy** (LocationAccuracy) - The desired location accuracy (e.g., `LocationAccuracy.HIGH_ACCURACY`, `LocationAccuracy.BALANCED_POWER_ACCURACY`).
- **updateInterval** (number) - The interval in milliseconds to receive location updates.
- **distanceFilter** (number) - The minimum distance in meters to trigger a location update.

### Request Example
```javascript
// Start with default options
const id = await startTracking();

// Start with custom options
const id = await startTracking(undefined, {
  accuracy: LocationAccuracy.HIGH_ACCURACY,
  updateInterval: 5000,
  distanceFilter: 50,
});

// Start with a custom trip ID
const id = await startTracking('my-trip-123', {
  accuracy: LocationAccuracy.BALANCED_POWER_ACCURACY,
});
```

### Response
#### Success Response
- **id** (string) - The ID of the tracking session.

#### Response Example
```json
"some-trip-id-12345"
```
```

--------------------------------

### Configure NotificationOptions in v0.10.x

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/BREAKING_CHANGES.md

Example of the legacy flat notification configuration structure used prior to v0.12.0.

```typescript
startTracking({
  updateInterval: 5000,
  notificationTitle: 'Location Tracking',
  notificationText: 'Tracking in background',
  notificationChannelName: 'Background Location',
  notificationChannelId: 'location_channel',
  notificationPriority: NotificationPriority.LOW,
  notificationSmallIcon: 'ic_notification',
  notificationLargeIcon: 'ic_notification_large',
  notificationColor: '#4CAF50',
  notificationShowTimestamp: true,
  notificationSubtext: 'Example',
  notificationActions: [{ id: 'stop', label: 'Stop' }],
});
```

--------------------------------

### Implement Complete Permission Flow

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/guides/permission-handling.md

A comprehensive example demonstrating how to handle granted, blocked, and undetermined permission states within a React component.

```typescript
import React from 'react';
import { View, Text, Button, Linking, Alert } from 'react-native';
import { useLocationPermissions } from '@gabriel-sisjr/react-native-background-location';

function App() {
  const {
    permissionStatus,
    requestPermissions,
    isRequesting,
  } = useLocationPermissions();

  // Step 1: Check if permissions are granted
  if (permissionStatus.hasAllPermissions) {
    return <MainApp />;
  }

  // Step 2: Handle blocked state
  if (permissionStatus.location.status === 'blocked') {
    return (
      <View style={styles.container}>
        <Text style={styles.title}>Location Access Required</Text>
        <Text style={styles.body}>
          Location permissions have been permanently denied.
          Please enable them in Settings to use this app.
        </Text>
        <Button
          title="Open Settings"
          onPress={() => Linking.openSettings()}
        />
      </View>
    );
  }

  // Step 3: Handle denied / undetermined states
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Welcome</Text>
      <Text style={styles.body}>
        This app needs location access to track your trips in the background.
      </Text>

      {/* Show individual permission states */}
      <View style={styles.statusRow}>
        <Text>Location: {permissionStatus.location.status}</Text>
        <Text>Notification: {permissionStatus.notification.status}</Text>
      </View>

      <Button
        title="Grant Permissions"
        onPress={async () => {
          const granted = await requestPermissions();
          if (!granted) {
            Alert.alert(
              'Permissions Required',
              'Location access is required for tracking.'
            );
          }
        }}
        disabled={isRequesting}
      />

      {isRequesting && <Text>Requesting permissions...</Text>}
    </View>
  );
}
```

--------------------------------

### Quick Start: Start Background Tracking

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/README.md

Initiate background location tracking with a specified trip ID and distance filter. Ensure location permissions are handled prior to calling this function.

```tsx
import {
  startTracking,
  useLocationUpdates,
} from '@gabriel-sisjr/react-native-background-location';

function App() {
  const { locations } = useLocationUpdates();

  return (
    <Button
      title="Start"
      onPress={() => startTracking({ tripId: 'trip-1', distanceFilter: 10 })}
    />
  );
}
```

--------------------------------

### Start Background Tracking

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/getting-started/quick-start.md

Use the `startTracking` function from the `useBackgroundLocation` hook to initiate location tracking. You can start with default options or provide custom accuracy, update interval, distance filter, and a custom trip ID.

```tsx
import {
  useBackgroundLocation,
  LocationAccuracy,
} from '@gabriel-sisjr/react-native-background-location';

const { startTracking, stopTracking, isTracking, tripId, locations } = 
  useBackgroundLocation();

// Start with default options (auto-generated trip ID)
const id = await startTracking();

// Start with custom options
const id = await startTracking(undefined, {
  accuracy: LocationAccuracy.HIGH_ACCURACY,
  updateInterval: 5000,
  distanceFilter: 50,
});

// Start with a custom trip ID
const id = await startTracking('my-trip-123', {
  accuracy: LocationAccuracy.BALANCED_POWER_ACCURACY,
});
```

--------------------------------

### Geofence Notification Usage Example

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/api-reference/types.md

Demonstrates how to use the `GEOFENCE_TEMPLATE_VARS` to construct dynamic notification titles and text for geofence alerts. This example shows how to import the constant and incorporate its variables into the notification options.

```typescript
import { GEOFENCE_TEMPLATE_VARS } from '@gabriel-sisjr/react-native-background-location';

const options = {
  title: 'Geofence Alert',
  text: `You entered ${GEOFENCE_TEMPLATE_VARS.IDENTIFIER} at ${GEOFENCE_TEMPLATE_VARS.TIMESTAMP}`,
};
```

--------------------------------

### Run Local Checks

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/development/ci-cd.md

Execute local checks including installation, linting, type checking, testing, and preparation.

```bash
yarn install
yarn lint
yarn typecheck
yarn test
yarn prepare
```

--------------------------------

### Enable New Architecture on iOS

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/troubleshooting.md

Use this command to enable the New Architecture for iOS builds. Ensure you run a clean pod install afterwards.

```bash
RCT_NEW_ARCH_ENABLED=1 pod install
```

--------------------------------

### Geofencing Example

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/migration/v0-14-0.md

This code snippet demonstrates geofencing functionality, which remains unchanged and uses named exports.

```typescript
import {
  addGeofence,
  removeGeofence,
  getActiveGeofences,
  configureGeofenceNotifications,
  GeofenceError,
  GeofenceErrorCode,
} from '@gabriel-sisjr/react-native-background-location';

try {
  await addGeofence({
    identifier: 'warehouse-1',
    latitude: -23.5505,
    longitude: -46.6333,
    radius: 150,
    transitions: ['enter', 'exit'],
  });
} catch (err) {
  if (
    err instanceof GeofenceError &&
    err.code === GeofenceErrorCode.DUPLICATE_IDENTIFIER
  ) {
    // handle duplicate
  }
}
```

--------------------------------

### Configure Tracking Notification Defaults

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/guides/notification-customization.md

Set initial notification options when starting the background tracking service.

```typescript
import {
  startTracking,
  LocationAccuracy,
  NotificationPriority,
} from '@gabriel-sisjr/react-native-background-location';

await startTracking({
  accuracy: LocationAccuracy.HIGH_ACCURACY,
  updateInterval: 5000,
  notificationOptions: {
    title: 'Trip in Progress',
    text: 'Tracking your location in the background',
    priority: NotificationPriority.LOW,
    channelName: 'Location Tracking',
    color: '#4CAF50',
    showTimestamp: true,
    smallIcon: 'ic_tracking',     // Must exist in res/drawable
    largeIcon: 'ic_app_logo',     // Must exist in res/drawable
    subtext: 'Background tracking active',
  },
});
```

--------------------------------

### Enable New Architecture on iOS (Expo)

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/troubleshooting.md

Configure the Podfile.properties.json to enable the New Architecture for Expo projects on iOS. A clean pod install is recommended.

```properties
newArchEnabled=true
```

--------------------------------

### Execute project development and quality assurance scripts

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/CONTRIBUTING.md

A collection of package.json scripts used for project setup, static analysis, testing, and running the example application on mobile platforms. These commands require a configured Node.js environment with Yarn installed.

```shell
# Setup project dependencies
yarn

# Run TypeScript type checking
yarn typecheck

# Run ESLint for code quality
yarn lint

# Run Jest unit tests
yarn test

# Start Metro bundler for example app
yarn example start

# Run example app on Android
yarn example android

# Run example app on iOS
yarn example ios
```

--------------------------------

### Start Tracking with Low Priority Notification

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/api-reference/enums.md

Example of starting background location tracking with a low-priority foreground service notification. Ensure the NotificationPriority enum is imported.

```typescript
import { startTracking, NotificationPriority } from '@gabriel-sisjr/react-native-background-location';

await startTracking({
  notificationOptions: {
    title: 'Tracking',
    text: 'Location is being recorded',
    priority: NotificationPriority.LOW,
  },
});
```

--------------------------------

### Build Library for Manual Publishing

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/development/publishing.md

Execute these commands to install dependencies and prepare the library for manual publishing. This includes compiling TypeScript and generating necessary files.

```bash
yarn install
yarn prepare
```

--------------------------------

### Cross-Platform Location Tracking

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/production/platform-comparison.md

This example demonstrates how to use the react-native-background-location library to start and stop location tracking, handle location updates, and manage permissions. It shows how the same code can be used on both Android and iOS, with notes on platform-specific options.

```typescript
import {
  LocationAccuracy,
  useLocationPermissions,
  useBackgroundLocation,
  useLocationUpdates,
} from '@gabriel-sisjr/react-native-background-location';

function TrackingScreen() {
  const { permissionStatus, requestPermissions } = useLocationPermissions();
  const { isTracking, tripId, startTracking, stopTracking } = useBackgroundLocation();

  useLocationUpdates({
    onLocationUpdate: (location) => {
      // Same data format on both platforms
      console.log(location.latitude, location.longitude);
    },
    onLocationWarning: (warning) => {
      // Handle platform-specific warnings gracefully
      console.log(warning.type, warning.message);
    },
  });

  const handleStart = async () => {
    if (!permissionStatus.hasAllPermissions) {
      await requestPermissions();
    }

    // Same options work on both platforms
    // notificationOptions are silently ignored on iOS
    await startTracking({
      accuracy: LocationAccuracy.HIGH_ACCURACY,
      distanceFilter: 50,
      notificationOptions: {
        title: 'Tracking Active',   // Android only, ignored on iOS
        text: 'Recording your route', // Android only, ignored on iOS
      },
    });
  };

  return (
    <View>
      <Button title="Start" onPress={handleStart} />
      <Button title="Stop" onPress={stopTracking} />
    </View>
  );
}
```

--------------------------------

### Minimal React Native Background Location Tracking

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/getting-started/quick-start.md

This example demonstrates a minimal setup for background location tracking using three core hooks: useLocationPermissions, useBackgroundLocation, and useLocationUpdates. It handles permission requests and displays tracking status and location data.

```tsx
import React from 'react';
import { View, Text, Button, StyleSheet } from 'react-native';
import {
  useLocationPermissions,
  useBackgroundLocation,
  useLocationUpdates,
  LocationAccuracy,
} from '@gabriel-sisjr/react-native-background-location';

function TrackingScreen() {
  const { permissionStatus, requestPermissions, isRequesting } = 
    useLocationPermissions();

  const { startTracking, stopTracking, isTracking, tripId } = 
    useBackgroundLocation();

  const { locations, lastLocation } = useLocationUpdates({
    onLocationUpdate: (location) => {
      console.log('New location:', location.latitude, location.longitude);
    },
  });

  // Step 1: Request permissions if not granted
  if (!permissionStatus.location.hasPermission) {
    return (
      <View style={styles.container}>
        <Text style={styles.title}>Location Permission Required</Text>
        <Text style={styles.subtitle}>
          Background location access is needed to track your trips.
        </Text>
        <Button
          title={isRequesting ? 'Requesting...' : 'Grant Permissions'}
          onPress={requestPermissions}
          disabled={isRequesting}
        />
      </View>
    );
  }

  // Step 2: Show tracking controls
  return (
    <View style={styles.container}>
      <Text style={styles.title}>
        {isTracking ? 'Tracking Active' : 'Ready to Track'}
      </Text>

      {tripId && <Text style={styles.info}>Trip: {tripId}</Text>}
      <Text style={styles.info}>Locations: {locations.length}</Text>

      {lastLocation && (
        <Text style={styles.info}>
          Last: {lastLocation.latitude}, {lastLocation.longitude}
        </Text>
      )}

      <Button
        title={isTracking ? 'Stop Tracking' : 'Start Tracking'}
        onPress={() =>
          isTracking
            ? stopTracking()
            : startTracking(undefined, {
                accuracy: LocationAccuracy.HIGH_ACCURACY,
                distanceFilter: 50,
              })
        }
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: 'center', padding: 20 },
  title: { fontSize: 22, fontWeight: 'bold', textAlign: 'center', marginBottom: 12 },
  subtitle: { fontSize: 14, textAlign: 'center', marginBottom: 20, color: '#666' },
  info: { fontSize: 14, textAlign: 'center', marginBottom: 8 },
});

export default TrackingScreen;

```

--------------------------------

### Basic Geofence Management Example

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/api-reference/hooks/useGeofencing.md

Demonstrates adding and removing a geofence using the useGeofencing hook. Includes basic state display for active geofences, loading status, and error messages. Ensure to handle potential errors during geofence operations.

```tsx
import { useGeofencing } from '@gabriel-sisjr/react-native-background-location';

function GeofenceScreen() {
  const {
    geofences,
    isLoading,
    error,
    addGeofence,
    removeGeofence,
    maxGeofences,
  } = useGeofencing();

  const handleAdd = async () => {
    try {
      await addGeofence({
        identifier: 'office',
        latitude: -23.5505,
        longitude: -46.6333,
        radius: 200,
      });
      console.log('Geofence added');
    } catch (err) {
      console.error('Failed to add geofence:', err);
    }
  };

  return (
    <View>
      <Text>
        Active: {geofences.length} / {maxGeofences ?? '...'}
      </Text>

      <Button title="Add Office" onPress={handleAdd} disabled={isLoading} />

      {geofences.map((g) => (
        <View key={g.identifier}>
          <Text>{g.identifier}</Text>
          <Button
            title="Remove"
            onPress={() => removeGeofence(g.identifier)}
          />
        </View>
      ))}

      {error && <Text style={{ color: 'red' }}>{error.message}</Text>}
    </View>
  );
}
```

--------------------------------

### Granular Permission Handling

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/api-reference/hooks/useLocationPermissions.md

This example demonstrates how to handle different location permission statuses (BLOCKED, WHEN_IN_USE) and notification permissions. It uses `useEffect` to check permissions on mount and provides specific UI feedback and actions based on the status. It also includes a fallback to open device settings if permissions are permanently denied or require an upgrade.

```tsx
import {
  useLocationPermissions,
  LocationPermissionStatus,
} from '@gabriel-sisjr/react-native-background-location';

function PermissionScreen() {
  const { permissionStatus, requestPermissions, checkPermissions } = 
    useLocationPermissions();
  const { location, notification } = permissionStatus;

  useEffect(() => {
    // Check on mount without prompting
    checkPermissions();
  }, [checkPermissions]);

  if (location.status === LocationPermissionStatus.BLOCKED) {
    return (
      <View>
        <Text>Location permission is permanently denied.</Text>
        <Text>Please enable it in your device Settings.</Text>
        <Button title="Open Settings" onPress={() => Linking.openSettings()} />
      </View>
    );
  }

  if (location.status === LocationPermissionStatus.WHEN_IN_USE) {
    return (
      <View>
        <Text>Background location is required for trip recording.</Text>
        <Text>Please upgrade to "Always Allow" in Settings.</Text>
        <Button title="Open Settings" onPress={() => Linking.openSettings()} />
      </View>
    );
  }

  if (!location.hasPermission) {
    return (
      <View>
        <Button
          title="Grant Location Permission"
          onPress={requestPermissions}
        />
      </View>
    );
  }

  if (!notification.hasPermission) {
    return (
      <View>
        <Text>
          Notifications are disabled. Geofence alerts will not be visible.
        </Text>
        <Button title="Continue Anyway" onPress={() => navigate('Tracking')} />
      </View>
    );
  }

  return <TrackingScreen />;
}
```

--------------------------------

### Verify Library Build

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/development/publishing.md

Run these commands to ensure the library's code quality and functionality before publishing. This includes type checking, linting, and running tests.

```bash
yarn typecheck
yarn lint
yarn test
```

--------------------------------

### Develop and Commit

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/development/ci-cd.md

Stage all changes and commit them using the conventional commit format.

```bash
git add .
git commit -m "feat: add awesome feature"
```

--------------------------------

### Configure Info.plist Permissions

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/getting-started/ios-setup.md

Required location usage descriptions and background mode declarations for Info.plist.

```xml
<!-- Required: WhenInUse permission description -->
<key>NSLocationWhenInUseUsageDescription</key>
<string>We need your location to track your trips and routes.</string>

<!-- Required: Always permission description (for background tracking) -->
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We need continuous location access to track trips even when
the app is in the background.</string>

<!-- Required: Legacy Always permission (backwards compatibility) -->
<key>NSLocationAlwaysUsageDescription</key>
<string>We need continuous location access to track trips even when
the app is in the background.</string>

<!-- Background Modes declaration -->
<key>UIBackgroundModes</key>
<array>
    <string>location</string>
</array>
```

--------------------------------

### Start Location Tracking

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/api-reference/hooks/useBackgroundLocation.md

Manually start location tracking. This method can accept an optional custom trip ID and tracking options, which will override the hook's default options.

```typescript
const tripId = await startTracking('my-trip-id', {
  interval: 10000,
});
```

--------------------------------

### Create NPM Automation Token via CLI

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/development/ci-cd.md

Steps to log in to npm and create an automation token using the npm command-line interface.

```bash
npm login
npm token create --type automation
```

--------------------------------

### Check Tracking Status on Startup

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/guides/crash-recovery.md

On app startup, check the current tracking status using `isTracking()` to sync your UI state with the active session. This prevents unnecessary state resets.

```typescript
import { isTracking } from '@gabriel-sisjr/react-native-background-location';

useEffect(() => {
  isTracking().then((status) => {
    if (status.active) {
      // Sync your UI state with the active session
    }
  });
}, []);
```

--------------------------------

### Resume Existing Trip or Start New

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/guides/crash-recovery.md

Avoid generating new trip IDs unnecessarily. Check `isTracking()` first and resume an existing trip if available, or start a new one.

```typescript
// Good: resume existing or start new
const status = await isTracking();
const tripId = status.tripId
  ? await startTracking(status.tripId)
  : await startTracking();
```

--------------------------------

### Initialize Geofencing with Hooks

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/guides/notification-customization.md

Configure global notification templates for geofence transitions using the useGeofencing hook.

```typescript
import { useGeofencing } from '@gabriel-sisjr/react-native-background-location';

const { addGeofence } = useGeofencing({
  notificationOptions: {
    title: '{{transitionType}} -- {{identifier}}',
    text: 'Transition at {{latitude}}, {{longitude}}',
  },
});
```

--------------------------------

### Start Foreground-Only Tracking

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/production/app-store-compliance.md

Implementation for tracking location only while the application is in the foreground.

```typescript
import { startTracking } from '@gabriel-sisjr/react-native-background-location';

const tripId = await startTracking({
  foregroundOnly: true,
});
```

--------------------------------

### Verify Installation with isTracking

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/getting-started/installation.md

Import and use the `isTracking` function to verify that the native module is correctly linked and the library is loaded. This function checks the current tracking status.

```typescript
import { isTracking } from '@gabriel-sisjr/react-native-background-location';

// This should resolve without errors
const status = await isTracking();
console.log('Library loaded, tracking active:', status.active);
```

--------------------------------

### Get Active Geofences

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/api-reference/geofencing-functions.md

Retrieves an array of currently active geofence regions.

```APIDOC
## GET /api/geofences/active

### Description
Retrieves an array of currently active geofence regions.

### Method
GET

### Endpoint
/api/geofences/active

### Parameters
None.

### Response
#### Success Response (200)
- **GeofenceRegion[]** (array) - Array of currently active geofence regions.

### Response Example
```json
[
  {
    "identifier": "home",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "radius": 100
  }
]
```
```

--------------------------------

### Get Active Geofences

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/api-reference/geofencing-functions.md

Retrieves an array of currently active geofence regions.

```ts
function getActiveGeofences(): Promise<GeofenceRegion[]>
```

```ts
const active = await getActiveGeofences();
console.log(`${active.length} geofences active`);

active.forEach((g) => {
  console.log(`${g.identifier}: ${g.latitude}, ${g.longitude} (r=${g.radius}m)`);
});
```

--------------------------------

### Start Tracking with Options

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/guides/background-tracking.md

Initiates background tracking, allowing configuration of options like distanceFilter and notification details. Can be used with or without a custom trip ID.

```typescript
// Option 1: Pass options only (trip ID auto-generated)
const tripId = await startTracking({
  distanceFilter: 100,
  notificationOptions: {
    title: 'Delivery Active',
  },
});

// Option 2: Pass trip ID and options
const tripId = await startTracking('my-trip', {
  distanceFilter: 100,
});
```

--------------------------------

### Add a Single Geofence

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/guides/geofencing.md

A basic example of adding a geofence using the addGeofence function.

```typescript
import { addGeofence } from '@gabriel-sisjr/react-native-background-location';

await addGeofence({
  identifier: 'office',
  latitude: -23.5505,
  longitude: -46.6333,
  radius: 200,
});
```

--------------------------------

### Get Geofence Notification Configuration

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/api-reference/geofencing-functions.md

Retrieves the current global geofence notification configuration.

```APIDOC
## GET /api/notifications/geofence

### Description
Retrieves the current global geofence notification configuration. Returns an empty object if no configuration has been set.

### Method
GET

### Endpoint
/api/notifications/geofence

### Parameters
None.

### Response
#### Success Response (200)
- **NotificationOptions** (object) - The current notification configuration.

### Response Example
```json
{
  "title": "Geofence Alert",
  "text": "Transition at {{identifier}}",
  "priority": "HIGH",
  "transitionOverrides": {
    "ENTER": {
      "title": "Welcome!",
      "text": "You entered {{identifier}}"
    },
    "EXIT": {
      "title": "Goodbye!",
      "text": "You left {{identifier}}"
    }
  }
}
```
```

--------------------------------

### Storage Write Path Flowchart

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/architecture/data-flow.md

Illustrates the process of buffering and batching location writes to storage.

```mermaid
flowchart LR
    LOC["New location"] --> BUF["In-memory buffer<br/>(ConcurrentLinkedQueue / Array)"]
    BUF --> CHECK{"Buffer size >= 10<br/>OR 5s elapsed?"}
    CHECK -->|Yes| FLUSH["Batch INSERT<br/>(Room / Core Data)"]
    CHECK -->|No| WAIT["Wait for next<br/>location or timer"]
    FLUSH -->|Failure| RETRY["Re-add to buffer"]
```

--------------------------------

### Get Geofence Transitions

Source: https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/website/docs/api-reference/geofencing-functions.md

Retrieves stored geofence transition events from the local database.

```APIDOC
## GET /api/geofences/transitions

### Description
Retrieves stored geofence transition events from the local database.

### Method
GET

### Endpoint
/api/geofences/transitions

### Parameters
#### Query Parameters
- **identifier** (string) - Optional - Geofence identifier to filter by. If omitted, returns all transitions.

### Response
#### Success Response (200)
- **GeofenceTransitionEvent[]** (array) - Array of geofence transition events.

### Response Example
```json
[
  {
    "identifier": "office",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "radius": 100,
    "transitionType": "ENTER",
    "timestamp": 1678886400000
  }
]
```
```