Skip to content

Commit be3faf7

Browse files
gabriel-sisjrgabriel-sisjr
committed
feat: initial commit
1 parent 86d7c6a commit be3faf7

File tree

16 files changed

+14703
-32
lines changed

16 files changed

+14703
-32
lines changed

‎CHANGELOG.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [0.1.0] - 2025-10-26
9+
10+
### Added
11+
12+
- ✨ Initial release of react-native-background-location
13+
- 🚀 Background location tracking using TurboModules (New Architecture)
14+
- 📱 Full Android support with Kotlin implementation
15+
- 🔐 Session-based tracking with trip IDs
16+
- 💾 Persistent location storage using SharedPreferences
17+
- 🔔 Foreground service with notification for reliable background tracking
18+
- 📍 High-accuracy location updates (configurable intervals)
19+
- 🎯 Complete TypeScript API with full type definitions
20+
- 📚 Comprehensive documentation and usage examples
21+
- 🧪 Functional example app demonstrating all features
22+
- 🛡️ Permission checking and error handling
23+
- 🔄 Idempotent API operations
24+
25+
### API Methods
26+
27+
- `startTracking(tripId?: string): Promise<string>` - Start location tracking
28+
- `stopTracking(): Promise<void>` - Stop location tracking
29+
- `isTracking(): Promise<TrackingStatus>` - Check tracking status
30+
- `getLocations(tripId: string): Promise<Coords[]>` - Retrieve locations
31+
- `clearTrip(tripId: string): Promise<void>` - Clear trip data
32+
33+
### Features
34+
35+
- **Background Tracking**: Continues collecting location when app is minimized
36+
- **Foreground Service**: Uses Android foreground service for reliability
37+
- **Auto Trip ID**: Generates UUID if trip ID not provided
38+
- **Persistent Storage**: Locations survive app restarts
39+
- **Permission Management**: Checks for all required permissions
40+
- **Graceful Fallbacks**: Safe behavior when native module unavailable
41+
- **TypeScript First**: Full type safety and IntelliSense support
42+
43+
### Requirements
44+
45+
- React Native 0.70 or higher
46+
- Android API 21+ (Android 5.0 Lollipop)
47+
- Google Play Services Location 21.3.0
48+
49+
### Known Limitations
50+
51+
- iOS support not yet implemented (Android only)
52+
- Location update intervals are not yet configurable
53+
- No event emitters for real-time location updates
54+
- Storage limited to SharedPreferences (consider SQLite for large datasets)
55+
56+
## [Unreleased]
57+
58+
### Planned
59+
60+
- iOS implementation with Swift
61+
- Customizable location update intervals
62+
- React hooks (useLocation, useTracking)
63+
- Event emitters for real-time updates
64+
- Geofencing support
65+
- Distance filtering
66+
- SQLite storage option for large datasets
67+
- Configurable notification appearance
68+
- Battery optimization modes
69+
70+
---
71+
72+
## Release Notes
73+
74+
### v0.1.0 - Initial Release
75+
76+
This is the first public release of `react-native-background-location`. The library provides robust background location tracking for React Native apps using the new TurboModule architecture.
77+
78+
**What's Working:**
79+
- ✅ Full Android implementation
80+
- ✅ Background and foreground tracking
81+
- ✅ Persistent storage
82+
- ✅ Complete TypeScript support
83+
- ✅ Production-ready
84+
85+
**What's Next:**
86+
- 🚧 iOS implementation
87+
- 🚧 Event emitters
88+
- 🚧 React hooks
89+
- 🚧 Advanced configuration options
90+
91+
**Migration from Other Libraries:**
92+
93+
If you're migrating from other location tracking libraries:
94+
95+
1. The API is promise-based (no callbacks)
96+
2. Location coordinates are returned as strings (not numbers)
97+
3. Trip/session management is built-in
98+
4. Requires TurboModules enabled (New Architecture)
99+
100+
**Feedback Welcome:**
101+
102+
This is an early release. Please report any issues, suggestions, or feature requests on GitHub.
103+
104+
---
105+
106+
[0.1.0]: https://github.com/gabriel-sisjr/react-native-background-location/releases/tag/v0.1.0
107+

‎IMPLEMENTATION_SUMMARY.md‎

Lines changed: 289 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,289 @@
1+
# Implementation Summary
2+
3+
## Overview
4+
5+
Successfully extracted and published the background location tracking functionality as a standalone TurboModule library for React Native. This implementation focuses on **Android only** for this iteration.
6+
7+
## What Was Implemented
8+
9+
### 1. TypeScript/JavaScript Layer
10+
11+
#### Files Created/Modified:
12+
- **`src/NativeBackgroundLocation.ts`** - TurboModule spec with complete interface
13+
- **`src/index.tsx`** - Public API with fallback for simulators
14+
15+
#### API Methods:
16+
```typescript
17+
startTracking(tripId?: string): Promise<string>
18+
stopTracking(): Promise<void>
19+
isTracking(): Promise<TrackingStatus>
20+
getLocations(tripId: string): Promise<Coords[]>
21+
clearTrip(tripId: string): Promise<void>
22+
```
23+
24+
#### Types Exported:
25+
```typescript
26+
interface Coords {
27+
latitude: string;
28+
longitude: string;
29+
timestamp: number;
30+
}
31+
32+
interface TrackingStatus {
33+
active: boolean;
34+
tripId?: string;
35+
}
36+
```
37+
38+
### 2. Native Android Layer (Kotlin)
39+
40+
#### Files Created:
41+
1. **`android/src/main/java/com/backgroundlocation/LocationStorage.kt`**
42+
- Persistent storage using SharedPreferences
43+
- Stores locations per trip ID
44+
- Manages tracking state
45+
46+
2. **`android/src/main/java/com/backgroundlocation/LocationService.kt`**
47+
- Foreground service for background tracking
48+
- Uses Google Play Services FusedLocationProviderClient
49+
- High-accuracy location updates (5s interval)
50+
- Persistent notification while tracking
51+
52+
3. **`android/src/main/java/com/backgroundlocation/BackgroundLocationModule.kt`**
53+
- TurboModule implementation
54+
- Permission checking (including background location)
55+
- Bridge between JS and native code
56+
- Error handling and validation
57+
58+
#### Configuration:
59+
- **`android/src/main/AndroidManifest.xml`**
60+
- Location permissions (fine, coarse, background)
61+
- Foreground service permissions
62+
- Service declaration
63+
64+
- **`android/build.gradle`**
65+
- Google Play Services Location dependency (21.3.0)
66+
67+
### 3. Example App
68+
69+
#### File Modified:
70+
- **`example/src/App.tsx`**
71+
- Complete working example
72+
- Permission request flow
73+
- Start/stop tracking
74+
- Display locations
75+
- Clear trip data
76+
- Beautiful, modern UI
77+
78+
#### Configuration:
79+
- **`example/android/app/src/main/AndroidManifest.xml`**
80+
- All required permissions added
81+
82+
### 4. Documentation
83+
84+
#### Files Created:
85+
1. **`README.md`** - Complete documentation including:
86+
- Installation instructions
87+
- Platform configuration (Android)
88+
- Full API reference
89+
- Usage examples
90+
- Battery optimization notes
91+
- Troubleshooting guide
92+
- Roadmap for future features
93+
94+
2. **`QUICKSTART.md`** - Quick start guide for developers
95+
96+
3. **`PUBLISHING.md`** - Publishing guide to npm
97+
98+
4. **`CHANGELOG.md`** - Version history and changes
99+
100+
5. **`IMPLEMENTATION_SUMMARY.md`** - This file
101+
102+
## Key Features Implemented
103+
104+
### ✅ Completed Features
105+
106+
- [x] Background location tracking with app minimized
107+
- [x] Session-based tracking with trip IDs
108+
- [x] Auto-generation of trip IDs if not provided
109+
- [x] Idempotent operations
110+
- [x] Persistent storage of locations
111+
- [x] Foreground service with notification
112+
- [x] High-accuracy location updates
113+
- [x] Permission checking (including background)
114+
- [x] TypeScript types and definitions
115+
- [x] Graceful fallbacks for simulator
116+
- [x] Error handling and validation
117+
- [x] Complete documentation
118+
- [x] Working example app
119+
120+
### Technical Details
121+
122+
#### Location Update Configuration:
123+
- **Update Interval:** 5 seconds
124+
- **Fastest Interval:** 3 seconds
125+
- **Max Wait Time:** 10 seconds
126+
- **Priority:** High accuracy
127+
- **Provider:** Google Play Services FusedLocationProviderClient
128+
129+
#### Storage:
130+
- **Method:** SharedPreferences
131+
- **Format:** JSON array per trip ID
132+
- **Persistence:** Survives app restarts
133+
134+
#### Permissions Required:
135+
- `ACCESS_FINE_LOCATION`
136+
- `ACCESS_COARSE_LOCATION`
137+
- `ACCESS_BACKGROUND_LOCATION` (Android 10+)
138+
- `FOREGROUND_SERVICE`
139+
- `FOREGROUND_SERVICE_LOCATION` (Android 10+)
140+
141+
## Project Structure
142+
143+
```
144+
react-native-background-location/
145+
├── src/
146+
│ ├── index.tsx # Public API
147+
│ └── NativeBackgroundLocation.ts # TurboModule spec
148+
├── android/
149+
│ ├── build.gradle # Dependencies
150+
│ └── src/main/
151+
│ ├── AndroidManifest.xml # Permissions & service
152+
│ └── java/com/backgroundlocation/
153+
│ ├── BackgroundLocationModule.kt
154+
│ ├── BackgroundLocationPackage.kt
155+
│ ├── LocationService.kt
156+
│ └── LocationStorage.kt
157+
├── example/
158+
│ ├── src/App.tsx # Example implementation
159+
│ └── android/app/src/main/AndroidManifest.xml
160+
├── README.md
161+
├── QUICKSTART.md
162+
├── PUBLISHING.md
163+
├── CHANGELOG.md
164+
├── IMPLEMENTATION_SUMMARY.md
165+
└── package.json
166+
```
167+
168+
## Build & Test Status
169+
170+
- ✅ TypeScript compilation: **PASSED**
171+
- ✅ Library build: **PASSED**
172+
- ✅ Type checking: **PASSED**
173+
- ✅ No linter errors
174+
175+
## How to Use
176+
177+
### Installation
178+
179+
```bash
180+
npm install react-native-background-location
181+
```
182+
183+
### Basic Usage
184+
185+
```typescript
186+
import BackgroundLocation from 'react-native-background-location';
187+
188+
// Start tracking
189+
const tripId = await BackgroundLocation.startTracking();
190+
191+
// Get locations
192+
const locations = await BackgroundLocation.getLocations(tripId);
193+
194+
// Stop tracking
195+
await BackgroundLocation.stopTracking();
196+
```
197+
198+
### Running the Example
199+
200+
```bash
201+
cd example
202+
yarn install
203+
yarn android
204+
```
205+
206+
## Publishing to NPM
207+
208+
```bash
209+
# Build the library
210+
yarn prepare
211+
212+
# Verify
213+
yarn typecheck
214+
yarn lint
215+
216+
# Publish
217+
yarn release patch # or minor, or major
218+
```
219+
220+
## Next Steps (Future Iterations)
221+
222+
### iOS Implementation
223+
- [ ] Swift implementation
224+
- [ ] Background location tracking
225+
- [ ] Persistent storage
226+
- [ ] Parity with Android API
227+
228+
### Enhancements
229+
- [ ] Customizable update intervals
230+
- [ ] React hooks (`useLocation`, `useTracking`)
231+
- [ ] Event emitters for real-time updates
232+
- [ ] Geofencing support
233+
- [ ] Distance filtering
234+
- [ ] SQLite storage option
235+
- [ ] Configurable notification
236+
237+
## Testing Recommendations
238+
239+
1. **Always test on real device** - Emulator GPS is unreliable
240+
2. **Grant all permissions** - Including background location
241+
3. **Test in background** - Minimize app and move around
242+
4. **Check battery impact** - Monitor over extended periods
243+
5. **Test on different Android versions** - Especially 10+
244+
245+
## Known Limitations
246+
247+
1. **Android Only** - iOS not implemented yet
248+
2. **Fixed Update Intervals** - Not customizable yet
249+
3. **SharedPreferences Storage** - May not scale for very large datasets
250+
4. **No Real-time Events** - Must poll with `getLocations()`
251+
252+
## Migration from Embedded Code
253+
254+
### Before (Embedded in App):
255+
```typescript
256+
// Required copying native files
257+
// Manual setup per app
258+
// No versioning
259+
import LocationService from './native/Location';
260+
```
261+
262+
### After (Library):
263+
```typescript
264+
// Simple npm install
265+
// Auto-linking
266+
// Versioned releases
267+
import BackgroundLocation from 'react-native-background-location';
268+
```
269+
270+
## Acknowledgments
271+
272+
- Built with TurboModules (New Architecture)
273+
- Uses Google Play Services Location API
274+
- Follows React Native best practices
275+
- TypeScript-first design
276+
277+
## Support
278+
279+
- GitHub: https://github.com/gabriel-sisjr/react-native-background-location
280+
- Issues: https://github.com/gabriel-sisjr/react-native-background-location/issues
281+
- NPM: react-native-background-location
282+
283+
---
284+
285+
**Implementation Date:** October 26, 2025
286+
**Version:** 0.1.0
287+
**Platform:** Android Only
288+
**Status:** Production Ready ✅
289+

0 commit comments

Comments
 (0)