react-native-background-live-tracking 1.0.0

package/README.md

@@ -0,0 +1,153 @@
+# react-native-background-live-tracking
+
+Android-only React Native library for **continuous driver GPS tracking** in the foreground, background, and after the user swipes the app away. Locations are sent to your backend over **REST** and optionally **WebSocket** or **Socket.IO**, with an **offline queue**, **retries**, and a **foreground service** with a persistent notification.
+
+iOS autolinking is disabled; the JavaScript API no-ops on iOS so your monorepo can still import the module safely.
+
+## Features
+
+- Fused location updates with configurable interval (milliseconds)
+- `START_STICKY` foreground service; optional restart after **boot** if tracking was active
+- REST `POST` (JSON body) on every fix, plus optional real-time channel
+- Offline **JSONL queue** on disk and periodic flush + per-request retries
+- Permission checks with clear promise rejections
+- Optional `openBatterySettings()` to request **ignore battery optimizations**
+- JS events: `Tracking.addLocationListener`, `Tracking.addStatusListener`, `Tracking.isActive()`
+- Optional **notification map preview**: static map **image** via Google Static Maps (not a live map)
+
+## Why not a live map like iOS / Uber on the lock screen?
+
+- **iOS** “Live Activities” use **ActivityKit** with SwiftUI and **MapKit**. That is a separate system UI; it is not how Android works.
+- **Android** foreground-service notifications are built from **RemoteViews**: mostly `TextView` / `ImageView`. You **cannot** put a real, continuously updating **Google Map (MapView)** inside the notification shade the same way.
+- Ride apps on Android usually combine a **text notification** plus **in-app** or **full-screen** UI. A **similar visual** in the tray is normally a **bitmap**: either a **Static Maps** image (what we support optionally) or your own server-rendered snapshot.
+
+### Optional: map snapshot in the expanded notification
+
+Enable the [Google Static Maps API](https://developers.google.com/maps/documentation/maps-static/overview) on a Cloud project (billing required). Then:
+
+```ts
+await Tracking.start({
+  driverId: 'driver-123',
+  interval: 5000,
+  serverUrl: 'https://api.example.com/v1/drivers/location',
+  notificationTitle: 'Driver En Route',
+  notificationBody: 'Live location is active',
+  notificationMapPreview: true,
+  googleStaticMapsApiKey: 'YOUR_KEY',
+  pickup: { latitude: 12.97, longitude: 77.59 }, // optional second marker
+});
+```
+
+The image appears in the **expanded** notification (pull down / long press depending on OEM). Updates are **throttled** (about every 45s) to limit API usage.
+
+## Install
+
+```bash
+npm install react-native-background-live-tracking
+# or
+yarn add react-native-background-live-tracking
+```
+
+### Metro (monorepo / `file:` dependency)
+
+If the package lives outside your app root, add its folder to `watchFolders` in `metro.config.js` (see this repo’s root config).
+
+### Autolinking
+
+Android is configured via `react-native.config.js` (`TrackingPackage`). Rebuild the native app after install.
+
+## Permissions
+
+The library declares the required permissions. Your app must **request** at runtime (in order on Android 10+):
+
+1. `ACCESS_FINE_LOCATION`
+2. `ACCESS_BACKGROUND_LOCATION` (needed when the app is killed)
+3. `POST_NOTIFICATIONS` (Android 13+)
+
+Use `PermissionsAndroid` or your preferred permission helper **before** calling `Tracking.start`.
+
+## JavaScript API
+
+```ts
+import { Tracking } from 'react-native-background-live-tracking';
+
+await Tracking.start({
+  driverId: 'driver-123',
+  interval: 5000, // milliseconds (e.g. 5 seconds)
+  serverUrl: 'https://api.example.com/v1/drivers/location',
+  socketUrl: 'wss://realtime.example.com/driver', // optional
+  socketTransport: 'websocket', // optional: 'websocket' | 'socket.io' | omit to auto-detect
+  notificationTitle: 'Driver En Route',
+  notificationBody: 'Sharing live location',
+  autoStartOnBoot: true,
+  restHeaders: { Authorization: 'Bearer …' },
+  notificationMapPreview: false,
+  googleStaticMapsApiKey: '',
+});
+
+await Tracking.stop();
+
+const active = await Tracking.isActive();
+```
+
+### Events
+
+```ts
+const sub = Tracking.addLocationListener((loc) => {
+  // { latitude, longitude, timestamp, driverId, accuracy, speed, bearing }
+});
+sub.remove();
+
+Tracking.addStatusListener(({ active }) => { ... });
+```
+
+### Battery optimization
+
+```ts
+await Tracking.openBatterySettings();
+```
+
+OEMs may still restrict background work; combining a foreground service + user opt-out of optimization is the practical maximum on stock Android.
+
+## Backend contract
+
+### REST
+
+`POST` to `serverUrl` with `Content-Type: application/json` and body:
+
+```json
+{
+  "latitude": 19.076,
+  "longitude": 72.8777,
+  "timestamp": 1711728000123,
+  "driverId": "driver-123",
+  "accuracy": 12.5,
+  "speed": 8.2,
+  "bearing": 90.0
+}
+```
+
+Optional headers come from `restHeaders`.
+
+### WebSocket
+
+When `socketTransport` is `websocket` (or inferred), each fix is sent as a **text frame** containing the same JSON string. Use `wss://` or `ws://` URLs (or `https://` / `http://`, which are normalized to WebSocket schemes).
+
+### Socket.IO
+
+When `socketTransport` is `socket.io` (or the URL suggests it), the client connects with the **socket.io-java-client** and emits event name **`location`** with a JSON object payload (same fields as above). Point `socketUrl` at your server origin, e.g. `https://api.example.com` (path `/socket.io` is default).
+
+## Native implementation notes
+
+- **Service:** `LocationForegroundService`, `foregroundServiceType="location"`
+- **Location:** Google Play services `FusedLocationProviderClient`, balanced power by default (tunable in native code if you fork)
+- **Boot:** `BootCompletedReceiver` restarts the service when `autoStartOnBoot` is true and tracking was active
+- **Queue:** `filesDir/rn_blt_location_queue.jsonl`, capped length 2000
+
+## Example app
+
+This repository’s root React Native app depends on the package via `file:./packages/react-native-background-live-tracking` and includes a minimal driver-style UI in `App.tsx`.
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,36 @@
+apply plugin: "com.android.library"
+apply plugin: "org.jetbrains.kotlin.android"
+
+def safeExtGet = { String prop, def fallback ->
+  return rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+android {
+  namespace "com.reactnativebackgroundlivetracking"
+  compileSdkVersion safeExtGet("compileSdkVersion", 36)
+  defaultConfig {
+    minSdkVersion safeExtGet("minSdkVersion", 24)
+    targetSdkVersion safeExtGet("targetSdkVersion", 36)
+    consumerProguardFiles "consumer-rules.pro"
+  }
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+  kotlinOptions {
+    jvmTarget = "17"
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib"
+  implementation "com.google.android.gms:play-services-location:21.3.0"
+  implementation "com.squareup.okhttp3:okhttp:4.12.0"
+  implementation "io.socket:socket.io-client:2.1.1"
+}

package/android/consumer-rules.pro

@@ -0,0 +1,3 @@
+-keep class okhttp3.** { *; }
+-dontwarn okhttp3.**
+-dontwarn okio.**

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,30 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+  <uses-permission android:name="android.permission.INTERNET" />
+  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+  <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.FOREGROUND_SERVICE_LOCATION" />
+  <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+  <uses-permission android:name="android.permission.WAKE_LOCK" />
+  <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
+  <uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
+
+  <application>
+    <service
+      android:name=".LocationForegroundService"
+      android:exported="false"
+      android:foregroundServiceType="location" />
+
+    <receiver
+      android:name=".BootCompletedReceiver"
+      android:exported="true"
+      android:permission="android.permission.RECEIVE_BOOT_COMPLETED">
+      <intent-filter>
+        <action android:name="android.intent.action.BOOT_COMPLETED" />
+      </intent-filter>
+    </receiver>
+  </application>
+</manifest>

package/android/src/main/java/com/reactnativebackgroundlivetracking/BootCompletedReceiver.kt

@@ -0,0 +1,21 @@
+package com.reactnativebackgroundlivetracking
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.os.Build
+
+class BootCompletedReceiver : BroadcastReceiver() {
+  override fun onReceive(context: Context, intent: Intent?) {
+    if (intent?.action != Intent.ACTION_BOOT_COMPLETED) return
+    val prefs = TrackingPreferences(context.applicationContext)
+    if (!prefs.isTrackingActive || !prefs.autoStartOnBoot) return
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+      // Foreground service from boot: ensure manifest permission is present
+    }
+    try {
+      LocationForegroundService.start(context.applicationContext)
+    } catch (_: Exception) {
+    }
+  }
+}

package/android/src/main/java/com/reactnativebackgroundlivetracking/LocationForegroundService.kt

@@ -0,0 +1,287 @@
+package com.reactnativebackgroundlivetracking
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.graphics.Bitmap
+import android.app.PendingIntent
+import android.app.Service
+import android.content.Context
+import android.content.Intent
+import android.content.pm.ServiceInfo
+import android.location.Location
+import android.os.Build
+import android.os.Handler
+import android.os.IBinder
+import android.os.Looper
+import androidx.core.app.NotificationCompat
+import androidx.core.content.ContextCompat
+import com.google.android.gms.location.LocationCallback
+import com.google.android.gms.location.LocationRequest
+import com.google.android.gms.location.LocationResult
+import com.google.android.gms.location.LocationServices
+import com.google.android.gms.location.Priority
+import java.util.concurrent.Executors
+import org.json.JSONObject
+
+class LocationForegroundService : Service() {
+  private val executor = Executors.newSingleThreadExecutor()
+  private val staticMapExecutor = Executors.newSingleThreadExecutor()
+  private val mainHandler = Handler(Looper.getMainLooper())
+  private var locationCallback: LocationCallback? = null
+  private var networkClient: LocationNetworkClient? = null
+  private var queueStore: LocationQueueStore? = null
+
+  private var lastStaticMapFetchMs = 0L
+  private val flushRunnable =
+    object : Runnable {
+      override fun run() {
+        executor.execute {
+          try {
+            networkClient?.flushQueue()
+          } catch (_: Exception) {
+          }
+        }
+        mainHandler.postDelayed(this, QUEUE_FLUSH_INTERVAL_MS)
+      }
+    }
+
+  override fun onBind(intent: Intent?): IBinder? = null
+
+  override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+    if (intent?.action == ACTION_STOP) {
+      shutdown()
+      return START_NOT_STICKY
+    }
+
+    val prefs = TrackingPreferences(this)
+    if (!prefs.isTrackingActive) {
+      stopSelf()
+      return START_NOT_STICKY
+    }
+
+    queueStore = LocationQueueStore(this)
+    networkClient = LocationNetworkClient(this, prefs, queueStore!!)
+    networkClient?.connectSocketsIfNeeded()
+
+    ensureNotificationChannel(prefs)
+    val notification = buildNotification(prefs, mapBitmap = null)
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+      startForeground(
+        NOTIFICATION_ID,
+        notification,
+        ServiceInfo.FOREGROUND_SERVICE_TYPE_LOCATION,
+      )
+    } else {
+      startForeground(NOTIFICATION_ID, notification)
+    }
+
+    requestLocationUpdates(prefs)
+    mainHandler.removeCallbacks(flushRunnable)
+    mainHandler.post(flushRunnable)
+
+    return START_STICKY
+  }
+
+  override fun onDestroy() {
+    mainHandler.removeCallbacks(flushRunnable)
+    shutdownLocationUpdates()
+    networkClient?.disconnectSockets()
+    super.onDestroy()
+  }
+
+  private fun shutdown() {
+    mainHandler.removeCallbacks(flushRunnable)
+    shutdownLocationUpdates()
+    networkClient?.disconnectSockets()
+    staticMapExecutor.shutdownNow()
+    stopForeground(STOP_FOREGROUND_REMOVE)
+    stopSelf()
+  }
+
+  private fun useMapStyleChannel(prefs: TrackingPreferences): Boolean {
+    return prefs.notificationMapPreview && prefs.staticMapsApiKey.isNotBlank()
+  }
+
+  private fun ensureNotificationChannel(prefs: TrackingPreferences) {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+    val nm = getSystemService(NotificationManager::class.java)
+    val low =
+      NotificationChannel(
+        getString(R.string.rn_blt_channel_id),
+        getString(R.string.rn_blt_channel_name),
+        NotificationManager.IMPORTANCE_LOW,
+      )
+    nm.createNotificationChannel(low)
+    val map =
+      NotificationChannel(
+        getString(R.string.rn_blt_channel_id_map),
+        getString(R.string.rn_blt_channel_name_map),
+        NotificationManager.IMPORTANCE_DEFAULT,
+      )
+    nm.createNotificationChannel(map)
+  }
+
+  private fun notificationChannelId(prefs: TrackingPreferences): String {
+    return if (useMapStyleChannel(prefs)) {
+      getString(R.string.rn_blt_channel_id_map)
+    } else {
+      getString(R.string.rn_blt_channel_id)
+    }
+  }
+
+  private fun buildNotification(
+    prefs: TrackingPreferences,
+    mapBitmap: Bitmap?,
+  ): Notification {
+    val channelId = notificationChannelId(prefs)
+    val launchIntent = packageManager.getLaunchIntentForPackage(packageName)
+    val pendingIntent =
+      PendingIntent.getActivity(
+        this,
+        0,
+        launchIntent,
+        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+      )
+    val priority =
+      if (useMapStyleChannel(prefs)) {
+        NotificationCompat.PRIORITY_DEFAULT
+      } else {
+        NotificationCompat.PRIORITY_LOW
+      }
+    val builder =
+      NotificationCompat.Builder(this, channelId)
+        .setContentTitle(prefs.notificationTitle)
+        .setContentText(prefs.notificationBody)
+        .setSmallIcon(android.R.drawable.ic_menu_mylocation)
+        .setOngoing(true)
+        .setContentIntent(pendingIntent)
+        .setCategory(NotificationCompat.CATEGORY_SERVICE)
+        .setPriority(priority)
+
+    if (mapBitmap != null) {
+      builder.setLargeIcon(mapBitmap)
+      builder.setStyle(
+        NotificationCompat.BigPictureStyle()
+          .bigPicture(mapBitmap)
+          .setSummaryText(prefs.notificationBody),
+      )
+    }
+    return builder.build()
+  }
+
+  private fun requestLocationUpdates(prefs: TrackingPreferences) {
+    shutdownLocationUpdates()
+    val interval = prefs.intervalMs.coerceIn(1000L, 60_000L)
+    val request =
+      LocationRequest.Builder(Priority.PRIORITY_BALANCED_POWER_ACCURACY, interval)
+        .setMinUpdateIntervalMillis((interval / 2).coerceAtLeast(1000L))
+        .setMaxUpdateDelayMillis(interval * 2)
+        .setWaitForAccurateLocation(false)
+        .build()
+
+    val fused = LocationServices.getFusedLocationProviderClient(this)
+    locationCallback =
+      object : LocationCallback() {
+        override fun onLocationResult(result: LocationResult) {
+          val loc = result.lastLocation ?: return
+          executor.execute { handleLocation(loc, prefs) }
+        }
+      }
+    try {
+      fused.requestLocationUpdates(
+        request,
+        locationCallback!!,
+        Looper.getMainLooper(),
+      )
+    } catch (_: SecurityException) {
+      stopSelf()
+    }
+  }
+
+  private fun handleLocation(location: Location, prefs: TrackingPreferences) {
+    val ts = System.currentTimeMillis()
+    val json =
+      JSONObject()
+        .put("latitude", location.latitude)
+        .put("longitude", location.longitude)
+        .put("timestamp", ts)
+        .put("driverId", prefs.driverId)
+        .put("accuracy", location.accuracy.toDouble())
+        .put("speed", location.speed.toDouble())
+        .put("bearing", location.bearing.toDouble())
+        .toString()
+
+    TrackingEventBridge.emitLocation(
+      location.latitude,
+      location.longitude,
+      ts,
+      prefs.driverId,
+      location.accuracy,
+      location.speed,
+      location.bearing,
+    )
+
+    networkClient?.sendLocationJson(json)
+    maybeRefreshMapNotification(location, prefs)
+  }
+
+  /**
+   * Android cannot embed a live MapView in a notification (unlike iOS Live Activities). This uses
+   * Google Static Maps to show a periodically refreshed image in the expanded notification.
+   */
+  private fun maybeRefreshMapNotification(location: Location, prefs: TrackingPreferences) {
+    if (!prefs.notificationMapPreview || prefs.staticMapsApiKey.isBlank()) return
+    staticMapExecutor.execute {
+      val now = System.currentTimeMillis()
+      if (now - lastStaticMapFetchMs < STATIC_MAP_MIN_INTERVAL_MS) return@execute
+      val plat = if (prefs.hasPickup) prefs.pickupLatitude else null
+      val plng = if (prefs.hasPickup) prefs.pickupLongitude else null
+      val bmp =
+        StaticMapFetcher.fetch(
+          location.latitude,
+          location.longitude,
+          plat,
+          plng,
+          prefs.staticMapsApiKey,
+        )
+          ?: return@execute
+      lastStaticMapFetchMs = System.currentTimeMillis()
+      mainHandler.post {
+        val nm = getSystemService(NotificationManager::class.java)
+        nm.notify(NOTIFICATION_ID, buildNotification(prefs, bmp))
+      }
+    }
+  }
+
+  private fun shutdownLocationUpdates() {
+    locationCallback?.let { cb ->
+      try {
+        LocationServices.getFusedLocationProviderClient(this).removeLocationUpdates(cb)
+      } catch (_: Exception) {
+      }
+    }
+    locationCallback = null
+  }
+
+  companion object {
+    private const val NOTIFICATION_ID = 90421
+    private const val QUEUE_FLUSH_INTERVAL_MS = 30_000L
+    /** Limits Static Maps quota / network; expanded notification still updates on this cadence. */
+    private const val STATIC_MAP_MIN_INTERVAL_MS = 45_000L
+    const val ACTION_STOP = "com.reactnativebackgroundlivetracking.action.STOP"
+
+    fun start(context: Context) {
+      val i = Intent(context, LocationForegroundService::class.java)
+      ContextCompat.startForegroundService(context, i)
+    }
+
+    fun stop(context: Context) {
+      val i =
+        Intent(context, LocationForegroundService::class.java).apply {
+          action = ACTION_STOP
+        }
+      context.startService(i)
+    }
+  }
+}