# dp-geo-coordinates

> Advanced React Native TurboModule for background geolocation tracking and native HTTP uploading — even when the app is minimized or the phone is locked.

---

## 🚀 Features

- ✅ Get one-time current location
- ✅ Foreground continuous location tracking
- ✅ Background location tracking via Android service
- ✅ Native background HTTP uploading using WorkManager
- ✅ Auto location updates to JS via `DeviceEventEmitter`
- ✅ Real-time updates even when the app is inactive
- ✅ Fully configurable upload endpoint + headers (Supabase-ready)
- ✅ Example app included
- ✅ Permission handled from JS (foreground + background)

---

## 📦 Installation

```sh
npm install dp-geo-coordinates
```

Make sure your project is set up for React Native New Architecture (TurboModules enabled).

🔧 Android Setup

1. Android Permissions

Add the following to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.INTERNET" />

2. Manual Linking (if auto-linking fails)

In android/settings.gradle:

include ':dp-geo-coordinates'
project(':dp-geo-coordinates').projectDir = new File(rootProject.projectDir, '../node_modules/dp-geo-coordinates/android')

In android/app/build.gradle:

dependencies {
  implementation project(':dp-geo-coordinates')
}

🧠 API

Permission & Location

Geo.requestPermission(): Promise<boolean | "REQUESTED">;
Geo.getCurrentLocation(): Promise<Location>;

Tracking

Geo.startWatching(): void;
Geo.stopWatching(): void;

Geo.startBackgroundTracking(): void;
Geo.stopBackgroundTracking(): void;

Upload Config

Geo.setUploadConfig(url: string, headers: { [key: string]: string }): void;
Geo.uploadData(url: string, headers, body): Promise<'ENQUEUED'>;

Events

import { DeviceEventEmitter } from 'react-native';

DeviceEventEmitter.addListener('locationUpdated', (location) => {
  console.log(location);
});

💡 Example Usage

Geo.requestPermission();

Geo.setUploadConfig('https://your-api.com/track', {
  'Authorization': 'Bearer YOUR_TOKEN',
  'Content-Type': 'application/json',
});

Geo.startBackgroundTracking();

DeviceEventEmitter.addListener('locationUpdated', (loc) => {
  console.log('📍 New location:', loc);
});

🧪 Example App UI

• 📍 One-time location button
• 🛰️ Foreground tracking (start/stop)
• 📦 Background tracking (start/stop)
• 📤 Manual upload test button
• Real-time logs via console.log

📤 Uploads (Background Mode)

The module uses Android WorkManager to:

• Persist location data in SharedPreferences
• Upload data even if JS is paused or app is minimized
• Automatically retry failed requests

You can configure your own API using:

Geo.setUploadConfig(url, headers);

No need to call uploadData manually — all updates happen from the native side automatically.

📱 Platform Support

• ✅ Android 7.0+ (API 24+)
• ❌ iOS support coming soon

📚 Developer Info

• Author: Dilakshan Kamalathasan
• LinkedIn: kamalathasan-dilakshan

🪪 License

MIT

🙏 Acknowledgements

Built with ❤️ to support offline-first location apps with modern React Native architecture.