react-native-bg-geolocation 0.2.0

package/BgGeolocation.podspec

@@ -0,0 +1,39 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+react_native_package = Pod::Executable.execute_command(
+  "node",
+  [
+    "-p",
+    "require.resolve('react-native/package.json', { paths: [process.argv[1]] })",
+    __dir__,
+  ]
+).strip
+require File.join(File.dirname(react_native_package), "scripts/react_native_pods")
+
+Pod::Spec.new do |s|
+  s.name         = "BgGeolocation"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => "15.1" }
+  s.source       = { :git => "https://github.com/ZohaibNaseer786/react-native-bg-geolocation.git", :tag => "#{s.version}" }
+
+  # ObjC++ TurboModule wrapper + all Swift engine files.
+  # No binary dependency — the engine is compiled from Swift source directly.
+  # The location-push extension's PRINCIPAL class (BGLocationPushService.swift)
+  # is excluded from the pod — it belongs only to the
+  # CLLocationPushServiceExtension target. The shared constants, socket client,
+  # and deliverer ARE compiled into the engine so the in-app background-push
+  # handler can deliver natively without React Native.
+  s.source_files = "ios/**/*.{h,m,mm,cpp}", "ios/engine/**/*.swift", "ios/liveactivity/**/*.swift", "ios/locationpush/BGLocationPushShared.swift", "ios/locationpush/BGLocationPushSocketClient.swift", "ios/locationpush/BGLocationPushDeliverer.swift"
+
+  s.libraries    = 'sqlite3', 'z', 'stdc++'
+  s.frameworks   = "CoreLocation", "CoreMotion", "AVFoundation", "AudioToolbox", "MediaPlayer", "UIKit", "CoreData",
+                   "MessageUI", "UserNotifications", "BackgroundTasks", "ActivityKit"
+
+  install_modules_dependencies(s)
+end

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Zohaib Naseer
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,366 @@
+# react-native-bg-geolocation
+
+Background geolocation tracking for React Native in foreground, background, Android kill state, and iOS kill state (server-triggered via the Location Push Service Extension, plus eligible OS-managed relaunches), with motion detection (moving/stationary), geofencing, and pluggable delivery (socket / HTTP / headless).
+
+> Educational re-implementation of the `react-native-background-geolocation` API using only public platform APIs (FusedLocationProvider + Activity Recognition on Android, CoreLocation + CoreMotion + BGTaskScheduler on iOS). No proprietary binaries.
+
+## Features
+
+- ✅ Foreground / background location tracking with OS relaunch-capable events
+- ✅ Moving ↔ stationary detection (motion state machine + activity recognition)
+- ✅ OS-owned delivery (Android PendingIntent, iOS significant-change + regions)
+- ✅ **iOS Location Push Service Extension** — server-triggered location even when the app is force-quit (APNs `location` push → extension captures + uploads natively)
+- ✅ iOS Live Activity for Lock Screen and Dynamic Island tracking status
+- ✅ Headless JS task (Android) for kill-state JS execution
+- ✅ Pluggable delivery: native socket (Socket.IO) → REST fallback, or your own JS handler
+- ✅ Geofencing (`CLCircularRegion` / `GeofencingClient`)
+- ✅ Reboot persistence
+- ✅ Same API shape as `react-native-background-geolocation` (`AuthorizationStatus`, `DesiredAccuracy`, nested `Config`, etc.)
+
+## Installation
+
+```sh
+npm install react-native-bg-geolocation
+# or
+yarn add react-native-bg-geolocation
+```
+
+### iOS
+
+Add to `Info.plist`:
+
+```xml
+<key>NSLocationWhenInUseUsageDescription</key>
+<string>Used to track your location.</string>
+<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
+<string>Used to track your location in the background.</string>
+<key>NSMotionUsageDescription</key>
+<string>Used to detect movement.</string>
+<key>UIBackgroundModes</key>
+<array>
+  <string>location</string>
+  <!-- Required only when app.trackingAudioEnabled is approved and enabled. -->
+  <string>audio</string>
+  <string>fetch</string>
+  <string>processing</string>
+  <!-- Required for the app-alive background push path (Location Push). -->
+  <string>remote-notification</string>
+</array>
+<key>BGTaskSchedulerPermittedIdentifiers</key>
+<array>
+  <string>com.bggeolocation.location-refresh</string>
+</array>
+```
+
+For the Location Push Service Extension (kill-state), the app and extension also
+need the `aps-environment` and `com.apple.developer.location.push` entitlements
+and a shared App Group — see [iOS Location Push Service Extension](#ios-location-push-service-extension-kill-state-tracking).
+
+Register the BGTask in `AppDelegate` (see the example app's `AppDelegate.swift`).
+
+#### iOS Live Activity
+
+Live Activities require iOS 16.2 or newer and a WidgetKit extension in the
+host application. The example includes a complete extension in
+`example/ios/BgGeolocationLiveActivity`.
+
+Add these keys to the app `Info.plist`:
+
+```xml
+<key>NSSupportsLiveActivities</key>
+<true/>
+<key>NSSupportsLiveActivitiesFrequentUpdates</key>
+<true/>
+```
+
+Add `ios/liveactivity/TSLiveTrackingAttributes.swift` to the WidgetKit
+extension target and create an `ActivityConfiguration` for
+`TSLiveTrackingAttributes`. The package starts, updates, recovers, and ends the
+activity from native iOS location callbacks.
+
+#### iOS Tracking Audio
+
+For Apple-approved use cases, the package can run a real audible audio session
+beside Core Location while tracking is active:
+
+```ts
+app: {
+  trackingAudioEnabled: true,
+  trackingAudioVolume: 0.04,
+  trackingAudioMixWithOthers: true,
+}
+```
+
+Audio playback has no iOS runtime permission dialog. The host app must obtain
+clear user consent in its own UI before starting it. The app's Start and Stop
+actions control both tracking and audio. The package publishes the approved
+playback session through Now Playing, where Pause or Stop ends both playback and
+tracking. The tracking Live Activity remains a separate status surface. Add
+`audio` to `UIBackgroundModes` and enable this only
+for an audio use case and distribution model Apple has approved. Explicitly
+swiping the app away still terminates audio and location execution.
+Runtime status is available from
+`(await BackgroundGeolocation.getState()).trackingAudio`.
+
+#### iOS Location Push Service Extension (kill-state tracking)
+
+This is the production mechanism for getting a location from a **force-quit**
+app. Your server sends an APNs push to the device's *location-push token*; iOS
+launches a tiny `CLLocationPushServiceExtension` (a **separate process**, no
+React Native), which grabs one fix and uploads it — then the app is left
+untouched. This is how rideshare / delivery apps keep tracking after the user
+swipes the app away.
+
+> **There is no JavaScript in the extension process.** Delivery from a push is
+> done **natively** by the SDK (Socket.IO → REST fallback), because on a
+> kill-state / background wake the RN bridge is not running and JS event
+> listeners would be dropped.
+
+**Two push types, two paths** (your server may send either/both; the device
+uses whichever fires):
+
+| App state | Push to send | Wakes | Who delivers |
+|---|---|---|---|
+| Alive (fg / backgrounded) | `apns-push-type: background`, `content-available: 1` (standard APNs token) | the app | SDK natively, then fires the `locationpush` JS event for awareness |
+| **Force-quit** | `apns-push-type: location` to `<bundle-id>.location-query` (location-push token) | the **extension** | SDK natively inside the extension |
+
+The push payload must carry a `location-query` id (any of `location-query`,
+`locationQuery`, `location_query`, `locationQueryId`, `queryId`). Its presence
+means "report a location now"; it is echoed back in the upload so the server can
+correlate.
+
+**1. Request the Apple entitlement** (one-time, ~24–48h):
+<https://developer.apple.com/contact/request/location-push-service-extension>.
+Once approved, add `com.apple.developer.location.push` to the app entitlements.
+
+**2. Add an App Group** shared by the app and the extension (e.g.
+`group.<your-bundle-id>`). The SDK writes its delivery config into this suite so
+the separate-process extension can read where/how to upload. Add the same
+identifier to both targets' `Info.plist` files:
+
+```xml
+<key>BGLocationPushAppGroupIdentifier</key>
+<string>group.your.bundle.id</string>
+```
+
+**3. Add a Location Push Service Extension target** whose principal class is the
+SDK's `BGLocationPushService`. The example app ships a ready-made target and a
+script that wires it (`example/ios/add_location_push_target.rb`) — copy that
+target, or run the equivalent for your project. The extension's `Info.plist`:
+
+```xml
+<key>NSExtension</key>
+<dict>
+  <key>NSExtensionPointIdentifier</key>
+  <string>com.apple.location.push.service</string>
+  <key>NSExtensionPrincipalClass</key>
+  <string>BGLocationPushService</string>
+</dict>
+```
+
+**4. Register the location-push token in `AppDelegate`** and ship it to your
+server:
+
+```swift
+import CoreLocation
+// keep a strong ref or the manager is deallocated before the callback
+private var locationPushManager: CLLocationManager?
+
+if #available(iOS 15.0, *) {
+  let mgr = CLLocationManager()
+  locationPushManager = mgr
+  mgr.startMonitoringLocationPushes { tokenData, error in
+    guard let data = tokenData else { return }
+    let token = data.map { String(format: "%02hhx", $0) }.joined()
+    UserDefaults.standard.set(token, forKey: "BGLocationManager_locationPushToken")
+  }
+}
+```
+
+Then in JS, after `ready()`:
+
+```ts
+const token = await BackgroundGeolocation.getLocationPushToken(); // iOS only, else null
+if (token) await myApi.registerLocationPushToken(token); // your endpoint
+```
+
+**5. Configure delivery** (where the extension uploads). Call once after
+`ready()`:
+
+```ts
+await BackgroundGeolocation.setLocationPushConfig({
+  socketUrl: 'https://your.server',     // Socket.IO base URL (tried first)
+  socketPath: '/socket/location',
+  socketEvent: 'location:update',
+  socketAuthToken: jwt,                  // sent in the socket CONNECT auth + REST Bearer
+  socketTimeout: 8,                      // seconds before falling back to REST
+  fallbackUrl: 'https://your.server/api/location/fallback',
+  fcmToken,                              // available as the {fcmToken} token
+  // Custom HTTP headers for the REST fallback.
+  headers: { 'Device-Type': 'ios' },
+  // OPTIONAL: define the exact upload shape (socket emit + REST fallback).
+  // Values may contain {tokens} the SDK substitutes with live values. Omit to
+  // use the built-in default body.
+  payloadTemplate: {
+    lat: '{latitude}',                   // exact single token → stays numeric
+    long: '{longitude}',
+    fcm_token: '{fcmToken}',
+    device_type: 'ios',                  // literal value, passed through
+    user_current_time: '{userCurrentTime}',
+    location_query_id: '{queryId}',
+  },
+});
+```
+
+**`payloadTemplate`** lets you ship any payload shape from JS — no native
+patching. Tokens (use inside string values): `{latitude}`/`{lat}`,
+`{longitude}`/`{long}`, `{accuracy}`, `{speed}`, `{heading}`, `{altitude}`,
+`{timestamp}`, `{fcmToken}`, `{queryId}`, `{userCurrentTime}` (local `HH:mm`),
+`{deviceType}`. A value that is exactly one token (`'{latitude}'`) keeps its
+native type (numbers stay numbers); inline tokens (`'v2-{queryId}'`) interpolate
+as strings; nested objects/arrays are supported. Without `payloadTemplate` the
+deliverer posts the default body
+`{ lat, long, fcm_token, device_type: "ios", user_current_time, location_query_id }`
+(applies to both the socket emit and the REST fallback).
+
+**6. App-alive handler (optional).** When the app is alive, the SDK still
+delivers natively and emits a `locationpush` event so your JS can react. The
+event carries `delivered: true` when native already sent it — **do not re-send**:
+
+```ts
+BackgroundGeolocation.onLocationPush(async (event) => {
+  if (event.delivered) return; // native already uploaded it
+  // fallback: deliver event.location yourself, then:
+  await BackgroundGeolocation.finishLocationPush(event.requestId);
+});
+```
+
+**7. Server.** Send `apns-push-type: location` to the location-push token with
+topic `<bundle-id>.location-query` (and/or a `background` push to the standard
+APNs token for the app-alive path). Requires "Always" location authorization.
+
+Set `app.locationPushEnabled: true` in your config to signal this flow is in use.
+
+### Android
+
+Permissions are declared by the library manifest (`ACCESS_FINE_LOCATION`, `ACCESS_BACKGROUND_LOCATION`, `FOREGROUND_SERVICE_LOCATION`, `ACTIVITY_RECOGNITION`, `WAKE_LOCK`, `RECEIVE_BOOT_COMPLETED`). Request the runtime permissions in JS (see the example).
+
+## Usage
+
+```ts
+import BackgroundGeolocation from 'react-native-bg-geolocation';
+
+// 1. Configure (nested config, same shape as the original library)
+await BackgroundGeolocation.ready({
+  geolocation: {
+    desiredAccuracy: BackgroundGeolocation.DesiredAccuracy.High,
+    distanceFilter: 10,
+    stopTimeout: 5,
+    locationAuthorizationRequest: 'Always',
+  },
+  app: {
+    stopOnTerminate: false,
+    startOnBoot: true,
+    enableHeadless: true,
+    heartbeatInterval: 60,
+    liveActivityEnabled: true,
+    liveActivityTitle: 'Live location',
+    liveActivitySubtitle: 'Background tracking is active',
+    // Enable only after adding Push Notifications and ActivityKit APNs.
+    liveActivityPushUpdates: false,
+    trackingAudioEnabled: true,
+    trackingAudioVolume: 0.04,
+    trackingAudioMixWithOthers: true,
+    foregroundService: true,
+    notification: { title: 'Tracking', text: 'Location is active' },
+  },
+  logger: { logLevel: BackgroundGeolocation.LogLevel.Verbose },
+});
+
+// 2. Listen
+const sub = BackgroundGeolocation.onLocation(location => {
+  console.log('[location]', location.coords.latitude, location.coords.longitude);
+});
+BackgroundGeolocation.onMotionChange(event => {
+  console.log('[motionchange]', event.isMoving ? 'moving' : 'stationary');
+});
+
+// 3. Request permission + start
+const status = await BackgroundGeolocation.requestPermission();
+if (status === BackgroundGeolocation.AuthorizationStatus.Always) {
+  await BackgroundGeolocation.start();
+}
+
+// 4. Cleanup
+sub.remove();
+await BackgroundGeolocation.stop();
+```
+
+### Headless task (Android kill state)
+
+Register at module scope (e.g. in `index.js`) so it survives app kill:
+
+```ts
+import BackgroundGeolocation from 'react-native-bg-geolocation';
+
+const headlessTask = async (event) => {
+  if (event.name === 'location') {
+    const { coords } = event.params;
+    // POST to your server with fetch(), connect a socket, etc.
+  }
+};
+
+BackgroundGeolocation.registerHeadlessTask(headlessTask);
+```
+
+## How kill-state delivery works
+
+| Platform | Mechanism |
+|---|---|
+| **Android** | A FusedLocation `PendingIntent` is owned by the OS and delivered to a `BroadcastReceiver` even when the process is dead. A `START_STICKY` foreground service keeps the process priority high; `onTaskRemoved` reschedules it via `AlarmManager`. Kill-state events fire the **HeadlessJsTask**, where your JS runs. |
+| **iOS (OS relaunch)** | Continuous background updates use Core Location. Significant-change and region events can relaunch an app the system terminated. Each native fix is persisted before upload; interrupted HTTP delivery retries on the next wake. After an explicit force-quit, iOS will **not** relaunch via Core Location until the app is reopened. |
+| **iOS (force-quit, push-driven)** | Your server sends an APNs `location` push (topic `<bundle-id>.location-query`) to the device's location-push token. iOS launches the **Location Push Service Extension** — a separate process, even when the app is force-quit — which captures one fix and uploads it natively (Socket.IO → REST fallback). See the [Location Push section](#ios-location-push-service-extension-kill-state-tracking). Requires the Apple `location.push` entitlement, an App Group, and "Always" authorization. |
+
+Live Activities do not collect location and do not provide unrestricted
+background execution. Their extension cannot access the network or receive
+location updates. Core Location performs tracking; ActivityKit presents the
+latest state. For updates while the app process is unavailable, read
+`(await BackgroundGeolocation.getState()).liveActivity.pushToken`, send it to
+your server, and update the activity through APNs using the
+`<bundle-id>.push-type.liveactivity` topic.
+
+Devices without a Dynamic Island, including iPhone 12, show the Live Activity
+on the Lock Screen rather than persistently in the status bar.
+
+## API
+
+- **Lifecycle:** `ready`, `start`, `stop`, `getState`, `setConfig`, `reset`
+- **Location:** `getCurrentPosition`, `watchPosition`, `stopWatchPosition`, `changePace`, `getOdometer`, `setOdometer`, `resetOdometer`
+- **Permissions:** `requestPermission`, `requestTemporaryFullAccuracy`, `getProviderState`
+- **Persistence:** `getLocations`, `getCount`, `destroyLocations`, `insertLocation`, `sync`
+- **Geofencing:** `addGeofence(s)`, `removeGeofence(s)`, `getGeofences`, `getGeofence`, `geofenceExists`
+- **Events:** `onLocation`, `onMotionChange`, `onActivityChange`, `onHeartbeat`, `onProviderChange`, `onGeofence`, `onEnabledChange`, `onHttp`, `onLocationPush`, …
+- **iOS Location Push (kill-state):** `getLocationPushToken`, `getApnsDeviceToken`, `setLocationPushConfig`, `onLocationPush`, `finishLocationPush` — all iOS-only (resolve `null` / no-op on Android)
+- **Enums:** `AuthorizationStatus`, `DesiredAccuracy`, `LogLevel`, `NotificationPriority`, `ActivityType`, `PersistMode`, `AccuracyAuthorization`
+
+## Example
+
+The [`example/`](example) app demonstrates app-level tracking, socket delivery, motion detection and a live event log. See `example/src/backgroundLocationService.ts` for the recommended app-level integration pattern.
+
+```sh
+yarn
+yarn example android   # or: yarn example ios
+```
+
+## Contributing
+
+- [Development workflow](CONTRIBUTING.md#development-workflow)
+- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
+
+## License
+
+MIT
+
+---
+
+Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)

package/android/build.gradle

@@ -0,0 +1,69 @@
+buildscript {
+  ext.BgGeolocation = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return BgGeolocation[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.bggeolocation"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "com.google.android.gms:play-services-location:21.0.1"
+  implementation "com.squareup.okhttp3:okhttp:4.12.0"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,53 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+  <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.INTERNET" />
+  <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.RECEIVE_BOOT_COMPLETED" />
+  <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
+  <!-- Required by React Native's HeadlessJsTaskService (kill-state JS execution) -->
+  <uses-permission android:name="android.permission.WAKE_LOCK" />
+
+  <application>
+
+    <!-- Foreground service — the single active location source. Runs FusedLocation
+         with foregroundServiceType=location, so the OS grants continuous fresh GPS
+         in the background & after kill (this is what shows the location indicator). -->
+    <service
+      android:name=".BgGeolocationForegroundService"
+      android:foregroundServiceType="location"
+      android:exported="false"
+      android:stopWithTask="false" />
+
+    <!-- Boot receiver — restarts tracking after device reboot -->
+    <receiver
+      android:name=".BgGeolocationBootReceiver"
+      android:exported="false">
+      <intent-filter>
+        <action android:name="android.intent.action.BOOT_COMPLETED" />
+        <action android:name="android.intent.action.QUICKBOOT_POWERON" />
+      </intent-filter>
+    </receiver>
+
+    <!-- Activity recognition receiver — receives motion activity updates from Play Services -->
+    <receiver
+      android:name=".BgGeolocationActivityRecognitionReceiver"
+      android:exported="false" />
+
+    <!-- Geofence receiver — receives ENTER/EXIT/DWELL transitions (bg + kill state) -->
+    <receiver
+      android:name=".BgGeolocationGeofenceReceiver"
+      android:exported="false" />
+
+    <!-- HeadlessTask service — executes JS in a headless context when app is killed -->
+    <service
+      android:name=".BgGeolocationHeadlessTask"
+      android:exported="false" />
+
+  </application>
+
+</manifest>

package/android/src/main/java/com/bggeolocation/BgGeolocationActivityRecognitionReceiver.kt

@@ -0,0 +1,116 @@
+package com.bggeolocation
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.util.Log
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.modules.core.DeviceEventManagerModule
+import com.google.android.gms.location.ActivityRecognitionResult
+import com.google.android.gms.location.DetectedActivity
+
+/**
+ * Receives activity-recognition updates from Google Play Services.
+ *
+ * Because the PendingIntent that drives this receiver is owned by the OS, it
+ * fires in ALL app states — foreground, background AND after the app is killed.
+ *
+ * On every update it:
+ *   1. Persists the latest {type, confidence, isMoving} to SharedPreferences so
+ *      the module / foreground-service can stamp it onto every location.
+ *   2. Emits a `motionchange` event when the moving<->stationary state flips:
+ *        - to JS via DeviceEventEmitter when the React context is alive
+ *        - via the HeadlessTask when the app is killed.
+ *
+ * Declared in AndroidManifest.xml as a non-exported receiver.
+ */
+class BgGeolocationActivityRecognitionReceiver : BroadcastReceiver() {
+
+  companion object {
+    private const val TAG  = "BgGeoActivity"
+    private const val PREFS = "bg_geolocation_prefs"
+    const val KEY_ACTIVITY_TYPE = "activity_type"
+    const val KEY_ACTIVITY_CONF = "activity_confidence"
+    const val KEY_IS_MOVING     = "activity_is_moving"
+
+    /** Map a Play-Services activity to our string + moving flag. */
+    fun describe(type: Int): Pair<String, Boolean> = when (type) {
+      DetectedActivity.IN_VEHICLE -> "in_vehicle" to true
+      DetectedActivity.ON_BICYCLE -> "on_bicycle" to true
+      DetectedActivity.ON_FOOT    -> "on_foot" to true
+      DetectedActivity.RUNNING    -> "running" to true
+      DetectedActivity.WALKING    -> "walking" to true
+      DetectedActivity.STILL      -> "still" to false
+      DetectedActivity.TILTING    -> "tilting" to false
+      else                        -> "unknown" to false
+    }
+
+    fun readActivityType(context: Context): String =
+      context.getSharedPreferences(PREFS, Context.MODE_PRIVATE)
+        .getString(KEY_ACTIVITY_TYPE, "unknown") ?: "unknown"
+
+    fun readActivityConfidence(context: Context): Int =
+      context.getSharedPreferences(PREFS, Context.MODE_PRIVATE)
+        .getInt(KEY_ACTIVITY_CONF, 0)
+
+    fun readIsMoving(context: Context): Boolean =
+      context.getSharedPreferences(PREFS, Context.MODE_PRIVATE)
+        .getBoolean(KEY_IS_MOVING, false)
+  }
+
+  override fun onReceive(context: Context, intent: Intent) {
+    if (!ActivityRecognitionResult.hasResult(intent)) return
+    val result = ActivityRecognitionResult.extractResult(intent) ?: return
+
+    val mostProbable = result.mostProbableActivity
+    val (typeStr, isMoving) = describe(mostProbable.type)
+    val confidence = mostProbable.confidence
+
+    val prefs = context.getSharedPreferences(PREFS, Context.MODE_PRIVATE)
+    val wasMoving = prefs.getBoolean(KEY_IS_MOVING, false)
+    val hadPrevious = prefs.contains(KEY_IS_MOVING)
+
+    // Persist latest activity so locations can be stamped with it in any state.
+    prefs.edit()
+      .putString(KEY_ACTIVITY_TYPE, typeStr)
+      .putInt(KEY_ACTIVITY_CONF, confidence)
+      .putBoolean(KEY_IS_MOVING, isMoving)
+      .apply()
+
+    Log.d("BgGeoTest", "[ACTIVITY] $typeStr (moving=$isMoving conf=$confidence)")
+
+    // Only emit motionchange on an actual transition.
+    if (hadPrevious && wasMoving == isMoving) return
+
+    val payload = Arguments.createMap().apply {
+      putBoolean("isMoving", isMoving)
+      putMap("activity", Arguments.createMap().apply {
+        putString("type", typeStr)
+        putInt("confidence", confidence)
+      })
+    }
+
+    val reactContext = BgGeolocationModule.getReactContext()
+
+    if (reactContext != null) {
+      // App alive — emit straight to JS.
+      try {
+        reactContext
+          .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+          ?.emit("motionchange", payload)
+        Log.d("BgGeoTest", "[ACTIVITY] motionchange → JS (isMoving=$isMoving)")
+      } catch (e: Exception) {
+        Log.w(TAG, "emit motionchange failed: ${e.message}")
+      }
+    } else {
+      // App killed — route through the headless task.
+      val headlessMap = Arguments.createMap().apply {
+        putBoolean("isMoving", isMoving)
+        putString("activityType", typeStr)
+        putInt("confidence", confidence)
+      }
+      BgGeolocationHeadlessTask.onEvent(context.applicationContext, "motionchange", headlessMap)
+      Log.d("BgGeoTest", "[ACTIVITY] motionchange → HEADLESS (isMoving=$isMoving)")
+    }
+  }
+}