react-native-background-live-tracking 1.0.0

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "react-native-background-live-tracking",
+  "version": "1.0.0",
+  "description": "Production-ready Android background GPS tracking with REST/WebSocket, offline queue, and foreground service.",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "license": "MIT",
+  "author": "",
+  "homepage": "https://github.com/your-org/react-native-background-live-tracking#readme",
+  "keywords": [
+    "react-native",
+    "background",
+    "location",
+    "tracking",
+    "foreground-service",
+    "android"
+  ],
+  "files": [
+    "src",
+    "android/build.gradle",
+    "android/consumer-rules.pro",
+    "android/src",
+    "README.md",
+    "react-native.config.js"
+  ],
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.73.0"
+  }
+}

package/react-native.config.js

@@ -0,0 +1,12 @@
+module.exports = {
+  dependency: {
+    platforms: {
+      android: {
+        packageImportPath:
+          'import com.reactnativebackgroundlivetracking.TrackingPackage;',
+        packageInstance: 'new TrackingPackage()',
+      },
+      ios: null,
+    },
+  },
+};

package/src/NativeTracking.ts

@@ -0,0 +1,26 @@
+import { NativeModules, Platform } from 'react-native';
+
+type NativeApi = {
+  startTracking: (configJson: string) => Promise<void>;
+  stopTracking: () => Promise<void>;
+  isTracking: () => Promise<boolean>;
+  openBatteryOptimizationSettings: () => Promise<void>;
+};
+
+const LINKING_ERROR =
+  "The package 'react-native-background-live-tracking' doesn't seem to be linked. Make sure: \n\n" +
+  Platform.select({ android: '- You rebuilt the app after installing the package.\n', default: '' }) +
+  '- You are not using Expo Go (native modules require a dev build).\n';
+
+const Native: NativeApi = NativeModules.RNBackgroundLiveTracking
+  ? NativeModules.RNBackgroundLiveTracking
+  : new Proxy(
+      {},
+      {
+        get() {
+          throw new Error(LINKING_ERROR);
+        },
+      },
+    ) as NativeApi;
+
+export default Native;

package/src/index.ts

@@ -0,0 +1,103 @@
+import { DeviceEventEmitter, EmitterSubscription, Platform } from 'react-native';
+import Native from './NativeTracking';
+import type { LocationPayload, TrackingStartOptions, TrackingStatus } from './types';
+
+const EVENT_LOCATION = 'RNBackgroundLiveTracking_location';
+const EVENT_STATUS = 'RNBackgroundLiveTracking_status';
+
+export const Tracking = {
+  /**
+   * Start continuous background location tracking and sync to your backend.
+   * Android only (this package disables iOS autolinking).
+   */
+  async start(options: TrackingStartOptions): Promise<void> {
+    if (Platform.OS !== 'android') {
+      console.warn(
+        '[react-native-background-live-tracking] Tracking.start is a no-op on this platform (Android-only library).',
+      );
+      return;
+    }
+    const {
+      driverId,
+      interval,
+      serverUrl,
+      socketUrl,
+      socketTransport,
+      notificationTitle,
+      notificationBody,
+      autoStartOnBoot,
+      restHeaders,
+      notificationMapPreview,
+      googleStaticMapsApiKey,
+      pickup,
+    } = options;
+    if (!driverId || !serverUrl || !interval || interval < 1000) {
+      throw new Error(
+        'Tracking.start requires driverId, serverUrl, and interval (minimum 1000 ms).',
+      );
+    }
+    const payload = {
+      driverId,
+      intervalMs: Math.floor(interval),
+      serverUrl,
+      socketUrl: socketUrl ?? null,
+      socketTransport: socketTransport ?? null,
+      notificationTitle: notificationTitle ?? 'Driver tracking',
+      notificationBody:
+        notificationBody ?? 'Live location is being shared in the background.',
+      autoStartOnBoot: autoStartOnBoot !== false,
+      restHeaders: restHeaders ?? {},
+      notificationMapPreview: notificationMapPreview === true,
+      googleStaticMapsApiKey: googleStaticMapsApiKey ?? '',
+      pickup: pickup ?? null,
+    };
+    await Native.startTracking(JSON.stringify(payload));
+  },
+
+  async stop(): Promise<void> {
+    if (Platform.OS !== 'android') {
+      return;
+    }
+    await Native.stopTracking();
+  },
+
+  async isActive(): Promise<boolean> {
+    if (Platform.OS !== 'android') {
+      return false;
+    }
+    return Native.isTracking();
+  },
+
+  async getStatus(): Promise<TrackingStatus> {
+    const active = await this.isActive();
+    return { active };
+  },
+
+  /** Opens the screen where the user can disable battery optimization for your app (Android). */
+  async openBatterySettings(): Promise<void> {
+    if (Platform.OS !== 'android') {
+      return;
+    }
+    await Native.openBatteryOptimizationSettings();
+  },
+
+  /**
+   * Subscribe to location updates (same payload sent to the server).
+   * Useful for showing the driver UI while the service runs.
+   */
+  addLocationListener(
+    listener: (location: LocationPayload) => void,
+  ): EmitterSubscription {
+    return DeviceEventEmitter.addListener(EVENT_LOCATION, listener);
+  },
+
+  addStatusListener(
+    listener: (status: TrackingStatus) => void,
+  ): EmitterSubscription {
+    return DeviceEventEmitter.addListener(EVENT_STATUS, listener);
+  },
+};
+
+export type { LocationPayload, TrackingStartOptions, TrackingStatus };
+export { EVENT_LOCATION, EVENT_STATUS };
+export default Tracking;

package/src/types.ts

@@ -0,0 +1,41 @@
+export type SocketTransport = 'rest' | 'websocket' | 'socket.io';
+
+export type TrackingStartOptions = {
+  driverId: string;
+  interval: number;
+  serverUrl: string;
+  socketUrl?: string;
+  /** How to use socketUrl when provided. Default: 'socket.io' if URL path suggests it, else 'websocket'. */
+  socketTransport?: SocketTransport;
+  /** Shown in the ongoing notification. */
+  notificationTitle?: string;
+  /** Shown in the ongoing notification body. */
+  notificationBody?: string;
+  /** Restart tracking after device reboot if it was active. Default true. */
+  autoStartOnBoot?: boolean;
+  /** Extra headers for REST POST (JSON string map). */
+  restHeaders?: Record<string, string>;
+  /**
+   * Show a map image in the expanded notification (Android only). This is **not** a live MapView:
+   * it uses the Google Static Maps API, so you need a key and it refreshes on an interval (see README).
+   */
+  notificationMapPreview?: boolean;
+  /** Google Cloud API key with Static Maps API enabled (billing). */
+  googleStaticMapsApiKey?: string;
+  /** Optional green “pickup” marker on the static map preview. */
+  pickup?: { latitude: number; longitude: number };
+};
+
+export type TrackingStatus = {
+  active: boolean;
+};
+
+export type LocationPayload = {
+  latitude: number;
+  longitude: number;
+  timestamp: number;
+  driverId: string;
+  accuracy?: number;
+  speed?: number;
+  bearing?: number;
+};