{"id":46488089,"url":"https://github.com/gabriel-sisjr/react-native-background-location","last_synced_at":"2026-04-01T18:51:24.409Z","repository":{"id":320937057,"uuid":"1083810536","full_name":"gabriel-sisjr/react-native-background-location","owner":"gabriel-sisjr","description":"A React Native library for tracking location in the background using TurboModules (New Architecture). Track user location even when the app is minimized or in the background.","archived":false,"fork":false,"pushed_at":"2025-12-20T19:26:41.000Z","size":10716,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2025-12-22T11:27:33.148Z","etag":null,"topics":["gps-tracking","location-services","location-tracker","new-architecture","react-native","turbo-module"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gabriel-sisjr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"gabriel-sisjr"}},"created_at":"2025-10-26T18:55:41.000Z","updated_at":"2025-12-20T19:26:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"b6dcd75e-43e4-4a08-b234-2104c6509e4c","html_url":"https://github.com/gabriel-sisjr/react-native-background-location","commit_stats":null,"previous_names":["gabriel-sisjr/react-native-background-location"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/gabriel-sisjr/react-native-background-location","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabriel-sisjr%2Freact-native-background-location","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabriel-sisjr%2Freact-native-background-location/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabriel-sisjr%2Freact-native-background-location/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabriel-sisjr%2Freact-native-background-location/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gabriel-sisjr","download_url":"https://codeload.github.com/gabriel-sisjr/react-native-background-location/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabriel-sisjr%2Freact-native-background-location/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30171656,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T07:56:45.623Z","status":"ssl_error","status_checked_at":"2026-03-06T07:55:55.621Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gps-tracking","location-services","location-tracker","new-architecture","react-native","turbo-module"],"created_at":"2026-03-06T10:02:57.617Z","updated_at":"2026-04-01T18:51:24.403Z","avatar_url":"https://github.com/gabriel-sisjr.png","language":"TypeScript","funding_links":["https://github.com/sponsors/gabriel-sisjr"],"categories":[],"sub_categories":[],"readme":"# @gabriel-sisjr/react-native-background-location\n\n[![NPM Version](https://img.shields.io/npm/v/%40gabriel-sisjr%2Freact-native-background-location)](https://www.npmjs.com/package/@gabriel-sisjr/react-native-background-location)\n[![NPM Beta](https://img.shields.io/npm/v/%40gabriel-sisjr%2Freact-native-background-location/beta)](https://www.npmjs.com/package/@gabriel-sisjr/react-native-background-location/v/beta)\n[![NPM Downloads](https://img.shields.io/npm/dm/%40gabriel-sisjr%2Freact-native-background-location)](https://www.npmjs.com/package/@gabriel-sisjr/react-native-background-location)\n[![NPM Total Downloads](https://img.shields.io/npm/dt/%40gabriel-sisjr%2Freact-native-background-location)](https://www.npmjs.com/package/@gabriel-sisjr/react-native-background-location)\n[![CI Tests](https://github.com/gabriel-sisjr/react-native-background-location/actions/workflows/ci.yml/badge.svg)](https://github.com/gabriel-sisjr/react-native-background-location/actions/workflows/ci.yml)\n[![Code Coverage](https://codecov.io/gh/gabriel-sisjr/react-native-background-location/branch/develop/graph/badge.svg)](https://codecov.io/gh/gabriel-sisjr/react-native-background-location)\n[![Pre-release CI](https://github.com/gabriel-sisjr/react-native-background-location/actions/workflows/prerelease.yml/badge.svg?branch=develop\u0026label=Pre-release)](https://github.com/gabriel-sisjr/react-native-background-location/actions/workflows/prerelease.yml)\n[![Release CI](https://github.com/gabriel-sisjr/react-native-background-location/actions/workflows/publish.yml/badge.svg?branch=main\u0026label=Release)](https://github.com/gabriel-sisjr/react-native-background-location/actions/workflows/publish.yml)\n[![GitHub Stars](https://img.shields.io/github/stars/gabriel-sisjr/react-native-background-location)](https://github.com/gabriel-sisjr/react-native-background-location/stargazers)\n[![License](https://img.shields.io/github/license/gabriel-sisjr/react-native-background-location)](https://github.com/gabriel-sisjr/react-native-background-location/blob/develop/LICENSE)\n[![Bundlephobia](https://img.shields.io/bundlephobia/minzip/%40gabriel-sisjr%2Freact-native-background-location?label=size)](https://bundlephobia.com/package/@gabriel-sisjr/react-native-background-location)\n![Platform Android](https://img.shields.io/badge/platform-Android-green)\n![Platform iOS](https://img.shields.io/badge/platform-iOS-blue)\n![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)\n\nA cross-platform React Native library for background location tracking built on TurboModules (New Architecture). Tracks user location reliably on both Android and iOS even when the app is minimized, with persistent storage, crash recovery, and platform-native behavior.\n\n![Tracking demo](docs/assets/tracking.gif)\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Hooks](#hooks)\n- [API Reference](#api-reference)\n- [Types](#types)\n- [Enums](#enums)\n- [Notification Customization](#notification-customization)\n- [Documentation](#documentation)\n- [Platform Support](#platform-support)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Features\n\n- Cross-platform background location tracking (Android and iOS)\n- Real-time event-driven location updates on both platforms\n- Crash recovery with automatic session restoration (WorkManager on Android, significant location monitoring on iOS)\n- Configurable accuracy levels and update intervals for battery efficiency\n- Distance filtering and callback throttling\n- Session-based tracking organized by trip IDs\n- Persistent storage: Room Database (Android) / Core Data (iOS)\n- Full notification customization on Android: icons, colors, action buttons, dynamic updates\n- Static notification defaults via AndroidManifest or convention drawables (Android)\n- Android 14/15 compliance (foreground service type, timeout handling)\n- Provider abstraction with Google Play Services primary and fallback provider (Android)\n- CLLocationManager with WhenInUse and Always authorization levels (iOS)\n- Foreground-only mode (no background permission required)\n- Fully typed TypeScript API with unified cross-platform hooks\n\n## Installation\n\n```sh\nnpm install @gabriel-sisjr/react-native-background-location\n# or\nyarn add @gabriel-sisjr/react-native-background-location\n```\n\n### Android Setup\n\nAdd the required permissions to `android/app/src/main/AndroidManifest.xml`:\n\n```xml\n\u003cmanifest xmlns:android=\"http://schemas.android.com/apk/res/android\"\u003e\n  \u003cuses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\" /\u003e\n  \u003cuses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\" /\u003e\n  \u003cuses-permission android:name=\"android.permission.ACCESS_BACKGROUND_LOCATION\" /\u003e\n  \u003cuses-permission android:name=\"android.permission.FOREGROUND_SERVICE\" /\u003e\n  \u003cuses-permission android:name=\"android.permission.FOREGROUND_SERVICE_LOCATION\" /\u003e\n\u003c/manifest\u003e\n```\n\n\u003e On Android 11+, background location must be requested **separately** from foreground permissions. See the [Quick Start Guide](docs/getting-started/QUICKSTART.md) for the full permission flow and the [Integration Guide](docs/getting-started/INTEGRATION_GUIDE.md) for detailed setup in existing apps.\n\n### iOS Setup\n\n1. Add the following keys to your `Info.plist`:\n\n```xml\n\u003ckey\u003eNSLocationWhenInUseUsageDescription\u003c/key\u003e\n\u003cstring\u003eWe need your location to track your trips.\u003c/string\u003e\n\u003ckey\u003eNSLocationAlwaysAndWhenInUseUsageDescription\u003c/key\u003e\n\u003cstring\u003eWe need your location in the background to continue tracking your trips.\u003c/string\u003e\n```\n\n2. Enable the **Location updates** Background Mode in your Xcode project under Signing \u0026 Capabilities.\n\n3. Run `pod install` in your `ios/` directory.\n\n\u003e **iOS:** Unlike Android, iOS does not use a foreground notification for background tracking. Instead, the system shows a blue status bar indicator when the app is using location in the background. See the [iOS Setup Guide](docs/getting-started/IOS_SETUP.md) for full details and App Store compliance requirements.\n\n## Quick Start\n\n```typescript\nimport {\n  useLocationPermissions,\n  useBackgroundLocation,\n  useLocationUpdates,\n  LocationAccuracy,\n} from '@gabriel-sisjr/react-native-background-location';\n\nfunction TrackingScreen() {\n  const { permissionStatus, requestPermissions } = useLocationPermissions();\n  const { startTracking, stopTracking, isTracking } = useBackgroundLocation();\n  const { locations, lastLocation } = useLocationUpdates({\n    onLocationUpdate: (loc) =\u003e console.log('New:', loc.latitude, loc.longitude),\n  });\n\n  if (!permissionStatus.hasAllPermissions) {\n    return \u003cButton title=\"Grant Permissions\" onPress={requestPermissions} /\u003e;\n  }\n\n  return (\n    \u003cView\u003e\n      \u003cText\u003eStatus: {isTracking ? 'Tracking' : 'Stopped'}\u003c/Text\u003e\n      \u003cText\u003ePoints: {locations.length}\u003c/Text\u003e\n      {lastLocation \u0026\u0026 \u003cText\u003eLast: {lastLocation.latitude}, {lastLocation.longitude}\u003c/Text\u003e}\n      \u003cButton\n        title={isTracking ? 'Stop' : 'Start'}\n        onPress={() =\u003e isTracking\n          ? stopTracking()\n          : startTracking(undefined, { accuracy: LocationAccuracy.HIGH_ACCURACY })\n        }\n      /\u003e\n    \u003c/View\u003e\n  );\n}\n```\n\nFor step-by-step setup, see the [Quick Start Guide](docs/getting-started/QUICKSTART.md). For the direct (non-hook) API, see [Using Direct API](#api-reference).\n\n## Hooks\n\n| Hook                                                                             | Purpose                                                                                                                        |\n| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| [`useLocationPermissions`](docs/getting-started/hooks.md#uselocationpermissions) | Manages cross-platform permission flow (Android: foreground, background, notifications; iOS: WhenInUse, Always, notifications) |\n| [`useBackgroundLocation`](docs/getting-started/hooks.md#usebackgroundlocation)   | Full tracking control: start, stop, locations, trip management                                                                 |\n| [`useLocationTracking`](docs/getting-started/hooks.md#uselocationtracking)       | Lightweight tracking status monitor (read-only)                                                                                |\n| [`useLocationUpdates`](docs/getting-started/hooks.md#uselocationupdates)         | Real-time event-driven location stream with warnings and action callbacks                                                      |\n\nSee the [Hooks Guide](docs/getting-started/hooks.md) for complete documentation, options, and examples.\n\n## API Reference\n\n### Methods\n\n| Method               | Signature                                                         | Description                                          |\n| -------------------- | ----------------------------------------------------------------- | ---------------------------------------------------- |\n| `startTracking`      | `(options?: TrackingOptions) =\u003e Promise\u003cstring\u003e`                  | Start tracking (auto-generates trip ID)              |\n| `startTracking`      | `(tripId?: string, options?: TrackingOptions) =\u003e Promise\u003cstring\u003e` | Start or resume tracking with a specific trip ID     |\n| `stopTracking`       | `() =\u003e Promise\u003cvoid\u003e`                                             | Stop tracking and terminate the background service   |\n| `isTracking`         | `() =\u003e Promise\u003cTrackingStatus\u003e`                                   | Check if tracking is active                          |\n| `getLocations`       | `(tripId: string) =\u003e Promise\u003cCoords[]\u003e`                           | Retrieve all stored locations for a trip             |\n| `clearTrip`          | `(tripId: string) =\u003e Promise\u003cvoid\u003e`                               | Delete all stored data for a trip                    |\n| `updateNotification` | `(title: string, text: string) =\u003e Promise\u003cvoid\u003e`                  | Update notification content while tracking is active |\n\n### TrackingOptions\n\nAll fields are optional. Defaults are applied when omitted.\n\n| Field                     | Type                  | Default         | Description                                                                                             |\n| ------------------------- | --------------------- | --------------- | ------------------------------------------------------------------------------------------------------- |\n| `updateInterval`          | `number`              | `5000`          | Interval between location updates (ms)                                                                  |\n| `fastestInterval`         | `number`              | `3000`          | Fastest allowed update interval (ms)                                                                    |\n| `maxWaitTime`             | `number`              | `10000`         | Max wait before delivering batched updates (ms)                                                         |\n| `accuracy`                | `LocationAccuracy`    | `HIGH_ACCURACY` | Location accuracy priority                                                                              |\n| `waitForAccurateLocation` | `boolean`             | `false`         | Delay updates until accurate location is available                                                      |\n| `distanceFilter`          | `number`              | `0`             | Minimum distance (meters) between updates. `0` = no filter                                              |\n| `foregroundOnly`          | `boolean`             | `false`         | Track only while app is visible (no background permission needed)                                       |\n| `onUpdateInterval`        | `number`              | `undefined`     | Throttle callback execution (ms). Locations still collected at `updateInterval`                         |\n| `notificationOptions`     | `NotificationOptions` | see below       | Notification configuration for the foreground service. See [NotificationOptions](#notificationoptions). |\n\n#### NotificationOptions\n\nAll fields are optional. These configure the Android foreground service notification. On iOS, notification fields are silently ignored.\n\n| Field           | Type                   | Default                                  | Description                                          |\n| --------------- | ---------------------- | ---------------------------------------- | ---------------------------------------------------- |\n| `title`         | `string`               | `\"Location Tracking\"`                    | Notification title                                   |\n| `text`          | `string`               | `\"Tracking your location in background\"` | Notification body text                               |\n| `channelName`   | `string`               | `\"Background Location\"`                  | Android notification channel name                    |\n| `channelId`     | `string`               | `\"background_location_channel\"`          | Custom notification channel ID                       |\n| `priority`      | `NotificationPriority` | `LOW`                                    | Notification priority                                |\n| `smallIcon`     | `string`               | system default                           | Drawable resource name for small icon                |\n| `largeIcon`     | `string`               | `undefined`                              | Drawable resource name for large icon                |\n| `color`         | `string`               | `undefined`                              | Hex color for notification accent (e.g. `\"#FF5722\"`) |\n| `showTimestamp` | `boolean`              | `false`                                  | Show timestamp on notification                       |\n| `subtext`       | `string`               | `undefined`                              | Subtext below notification content                   |\n| `actions`       | `NotificationAction[]` | `undefined`                              | Up to 3 action buttons on the notification           |\n\n## Types\n\n### Coords\n\n```typescript\ninterface Coords {\n  latitude: string;\n  longitude: string;\n  timestamp: number;\n  accuracy?: number;\n  altitude?: number;\n  speed?: number;\n  bearing?: number;\n  verticalAccuracyMeters?: number;\n  speedAccuracyMetersPerSecond?: number;\n  bearingAccuracyDegrees?: number;\n  elapsedRealtimeNanos?: number;\n  provider?: string;\n  isFromMockProvider?: boolean;\n}\n```\n\n\u003e **Note:** `latitude` and `longitude` are strings to preserve full decimal precision. Parse with `parseFloat()` when using with map libraries.\n\n### TrackingStatus\n\n```typescript\ninterface TrackingStatus {\n  active: boolean;\n  tripId?: string;\n}\n```\n\n### LocationUpdateEvent\n\n```typescript\ninterface LocationUpdateEvent {\n  tripId: string;\n  latitude: string;\n  longitude: string;\n  timestamp: number;\n  accuracy?: number;\n  altitude?: number;\n  speed?: number;\n  bearing?: number;\n  verticalAccuracyMeters?: number;\n  speedAccuracyMetersPerSecond?: number;\n  bearingAccuracyDegrees?: number;\n  elapsedRealtimeNanos?: number;\n  provider?: string;\n  isFromMockProvider?: boolean;\n}\n```\n\n### LocationWarningEvent and LocationWarningType\n\n```typescript\ntype LocationWarningType =\n  | 'SERVICE_TIMEOUT'\n  | 'TASK_REMOVED'\n  | 'LOCATION_UNAVAILABLE';\n\ninterface LocationWarningEvent {\n  tripId: string;\n  type: LocationWarningType;\n  message: string;\n  timestamp: number;\n}\n```\n\n### NotificationAction and NotificationActionEvent\n\n```typescript\ninterface NotificationAction {\n  id: string;\n  label: string;\n}\n\ninterface NotificationActionEvent {\n  tripId: string;\n  actionId: string;\n}\n```\n\n### LocationPermissionState\n\n```typescript\ninterface LocationPermissionState {\n  hasPermission: boolean;\n  status: LocationPermissionStatus;\n  canRequestAgain: boolean;\n}\n```\n\n### NotificationPermissionState\n\n```typescript\ninterface NotificationPermissionState {\n  hasPermission: boolean;\n  status: NotificationPermissionStatus;\n  canRequestAgain: boolean;\n}\n```\n\n### PermissionState\n\n```typescript\ninterface PermissionState {\n  hasAllPermissions: boolean;\n  location: LocationPermissionState;\n  notification: NotificationPermissionState;\n}\n```\n\n`hasAllPermissions` is `true` only when both location and notification permissions are granted. Individual permission states are accessible via the `location` and `notification` sub-objects.\n\n### UseLocationPermissionsResult\n\n```typescript\ninterface UseLocationPermissionsResult {\n  permissionStatus: PermissionState;\n  requestPermissions: () =\u003e Promise\u003cboolean\u003e;\n  checkPermissions: () =\u003e Promise\u003cboolean\u003e;\n  isRequesting: boolean;\n}\n```\n\n### UseBackgroundLocationResult\n\n```typescript\ninterface UseBackgroundLocationResult {\n  tripId: string | null;\n  isTracking: boolean;\n  locations: Coords[];\n  isLoading: boolean;\n  error: Error | null;\n  startTracking: (\n    customTripId?: string,\n    options?: TrackingOptions\n  ) =\u003e Promise\u003cstring | null\u003e;\n  stopTracking: () =\u003e Promise\u003cvoid\u003e;\n  refreshLocations: () =\u003e Promise\u003cvoid\u003e;\n  clearCurrentTrip: () =\u003e Promise\u003cvoid\u003e;\n  clearError: () =\u003e void;\n}\n```\n\n### UseLocationTrackingOptions\n\n```typescript\ninterface UseLocationTrackingOptions {\n  autoStart?: boolean;\n  tripId?: string;\n  options?: TrackingOptions;\n  onTrackingStart?: (tripId: string) =\u003e void;\n  onTrackingStop?: () =\u003e void;\n  onError?: (error: Error) =\u003e void;\n}\n```\n\n### UseLocationTrackingResult\n\n```typescript\ninterface UseLocationTrackingResult {\n  isTracking: boolean;\n  tripId: string | null;\n  refresh: () =\u003e Promise\u003cvoid\u003e;\n  isLoading: boolean;\n}\n```\n\n### UseLocationUpdatesOptions\n\n```typescript\ninterface UseLocationUpdatesOptions {\n  tripId?: string;\n  onLocationUpdate?: (location: Coords) =\u003e void;\n  onUpdateInterval?: number;\n  onLocationWarning?: (warning: LocationWarningEvent) =\u003e void;\n  onNotificationAction?: (event: NotificationActionEvent) =\u003e void;\n  autoLoad?: boolean;\n}\n```\n\n### UseLocationUpdatesResult\n\n```typescript\ninterface UseLocationUpdatesResult {\n  tripId: string | null;\n  isTracking: boolean;\n  locations: Coords[];\n  lastLocation: Coords | null;\n  lastWarning: LocationWarningEvent | null;\n  isLoading: boolean;\n  error: Error | null;\n  clearError: () =\u003e void;\n  clearLocations: () =\u003e Promise\u003cvoid\u003e;\n}\n```\n\n## Enums\n\n### LocationAccuracy\n\n| Value                     | Description                                           |\n| ------------------------- | ----------------------------------------------------- |\n| `HIGH_ACCURACY`           | GPS + sensors. Best accuracy, highest battery usage.  |\n| `BALANCED_POWER_ACCURACY` | Balanced accuracy and power consumption.              |\n| `LOW_POWER`               | Network-based. Lower accuracy, better battery.        |\n| `NO_POWER`                | Only receives updates requested by other apps.        |\n| `PASSIVE`                 | Passive updates from other apps. No additional power. |\n\n### NotificationPriority\n\n| Value     | Description                     |\n| --------- | ------------------------------- |\n| `LOW`     | Minimal notification (default). |\n| `DEFAULT` | Default system priority.        |\n| `HIGH`    | More prominent notification.    |\n| `MAX`     | Urgent notification.            |\n\n### LocationPermissionStatus\n\n| Value          | Description                                                                      |\n| -------------- | -------------------------------------------------------------------------------- |\n| `GRANTED`      | All required permissions granted (full background access).                       |\n| `WHEN_IN_USE`  | iOS only: WhenInUse permission granted. Tracking works but may have limitations. |\n| `DENIED`       | Permission denied (can request again).                                           |\n| `BLOCKED`      | Permission permanently denied (must open settings).                              |\n| `UNDETERMINED` | Permission not yet requested.                                                    |\n\n### NotificationPermissionStatus\n\n| Value          | Description                            |\n| -------------- | -------------------------------------- |\n| `GRANTED`      | Notification permission granted.       |\n| `DENIED`       | Notification permission denied.        |\n| `UNDETERMINED` | Notification permission not yet asked. |\n\n## Notification Customization\n\nThe foreground service notification supports full visual customization through the `notificationOptions` field on `TrackingOptions` (see [NotificationOptions](#notificationoptions) table above).\n\n**Static defaults** can be configured without runtime code using AndroidManifest metadata or convention-named drawables:\n\n```xml\n\u003c!-- AndroidManifest.xml --\u003e\n\u003cmeta-data android:name=\"com.backgroundlocation.default_notification_icon\"\n           android:resource=\"@drawable/ic_notification\" /\u003e\n\u003cmeta-data android:name=\"com.backgroundlocation.default_notification_color\"\n           android:resource=\"@color/notification_accent\" /\u003e\n```\n\nAlternatively, place a drawable named `bg_location_notification_icon` in `res/drawable/` for automatic detection.\n\n**Resolution priority:** Runtime options \u003e AndroidManifest metadata \u003e Convention drawable \u003e System default.\n\n**Dynamic updates** allow changing notification text while tracking is active:\n\n```typescript\nawait BackgroundLocation.updateNotification(\n  'Delivery #1234',\n  'Arriving in 5 minutes'\n);\n```\n\n**Action buttons** (max 3) can be added via `notificationOptions.actions` and handled through the `onNotificationAction` callback in `useLocationUpdates`.\n\n## Documentation\n\n### Getting Started\n\n- [Quick Start Guide](docs/getting-started/QUICKSTART.md) -- Get running in 5 minutes\n- [Integration Guide](docs/getting-started/INTEGRATION_GUIDE.md) -- Detailed setup for existing apps\n- [iOS Setup Guide](docs/getting-started/IOS_SETUP.md) -- iOS-specific configuration and requirements\n- [Hooks Guide](docs/getting-started/hooks.md) -- Complete hooks documentation\n- [Real-Time Updates](docs/getting-started/REAL_TIME_UPDATES.md) -- Event-driven location watching\n\n### Production\n\n- [Google Play Compliance](docs/production/GOOGLE_PLAY_COMPLIANCE.md) -- Required steps for Play Store approval\n- [App Store Compliance](docs/production/APP_STORE_COMPLIANCE.md) -- Required steps for App Store approval (iOS)\n- [Battery Optimization](docs/production/BATTERY_OPTIMIZATION.md) -- Platform-specific battery management\n- [Crash Recovery](docs/production/CRASH_RECOVERY.md) -- Session persistence and recovery strategies\n- [Platform Comparison](docs/production/PLATFORM_COMPARISON.md) -- Android vs iOS behavior differences\n\n### Development\n\n- [Testing Guide](docs/development/TESTING.md) -- Test structure and guidelines\n- [CI/CD Guide](docs/development/CICD.md) -- Automated pipelines\n- [Publishing Guide](docs/development/PUBLISHING.md) -- How to publish to npm\n- [Realtime Debug Guide](docs/development/REALTIME_DEBUG_GUIDE.md) -- Debugging location updates\n- [Implementation Summary](docs/development/IMPLEMENTATION_SUMMARY.md) -- Technical architecture overview\n\n## Platform Support\n\n| Platform | Status    | Notes                                                               |\n| -------- | --------- | ------------------------------------------------------------------- |\n| Android  | Supported | Kotlin native implementation. Min SDK 24, target SDK 34.            |\n| iOS      | Supported | Swift native implementation. CLLocationManager, Core Data, iOS 13+. |\n\n\u003e **iOS:** Background tracking on iOS uses the system blue status bar indicator instead of a notification. The `notificationOptions` field in `TrackingOptions` is Android-only and is silently ignored on iOS. See [Platform Comparison](docs/production/PLATFORM_COMPARISON.md) for detailed differences.\n\n## Contributing\n\nContributions are welcome. See the [Contributing Guide](CONTRIBUTING.md) for development workflow, coding standards, and how to submit pull requests.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabriel-sisjr%2Freact-native-background-location","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgabriel-sisjr%2Freact-native-background-location","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabriel-sisjr%2Freact-native-background-location/lists"}