@josuelmm/cordova-background-geolocation 4.5.1 → 4.5.2

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## [4.5.2](https://github.com/josuelmm/cordova-background-geolocation/tree/4.5.2) (2026-05-10)
+
+### Added — Provider Hardening
+- **`activityConfidenceThreshold` (0-100, default 50)**: las transiciones STILL/ACTIVE por debajo de este umbral se ignoran. Antes, ACTIVITY_PROVIDER reaccionaba a cualquier ruido de baja confianza → bursts espurios de start/stop GPS. iOS normaliza `CMMotionActivityConfidence` (Low/Medium/High → 20/40/80) para que el umbral signifique lo mismo en ambas plataformas.
+- **`maxAcceptedAccuracy` (m, opcional)**: filtro global que descarta fixes con accuracy peor a este valor antes de persistir/POST/emitir al JS. Aplica a los 3 providers.
+
+### Fixed (BLOQUEANTES — ACTIVITY_PROVIDER)
+- **Android `ACTIVITY_PROVIDER` ignoraba `distanceFilter`**: el `LocationRequest.Builder` no llamaba a `setMinUpdateDistanceMeters`. Resultado: con `interval` bajo se bombardeaba al consumidor sin throttling por distancia.
+- **Android sin verificación de Google Play Services**: si GPS estaba ausente/desactualizado, `FusedLocationProviderClient` + `ActivityRecognitionClient` fallaban silenciosamente. Ahora `onCreate` emite `SERVICE_ERROR` y queda inerte.
+- **Android `ACTIVITY_RECOGNITION` denegado en Android 10+**: `requestActivityUpdates` retornaba sin emitir nada y STILL/ACTIVE nunca cambiaba → tracking continuo accidental. Ahora `attachRecorder` emite `PERMISSION_DENIED_ERROR` una vez y desiste.
+- **Android `onConfigure` siempre stop+start**: incluso si la config nueva era idéntica, se dropeaba el callback y se reanudaba. Ahora compara `desiredAccuracy/interval/fastestInterval/distanceFilter/activitiesInterval/stopOnStillActivity` y solo reinicia si cambió algo relevante.
+- **iOS `onLocationsChanged` durante NotMoving emitía DOBLE**: invocaba `onStationaryChanged` + un `onLocationChanged` por cada CLLocation. Resultado: rows "moving" fantasma durante ventana STILL. Ahora retorna tras stationary.
+- **iOS confidence cruda (0/1/2 enum) comparada con threshold 0-100**: cualquier umbral > 2 ignoraba TODO. Normalizada a 0-100 en el provider.
+- **iOS ACTIVITY/RAW/DISTANCE `onDestroy` no soltaba `delegate`**: `MAURLocationManager` y `SOMotionDetector` son singletons compartidos; un swap de provider dejaba el destruido recibiendo callbacks. `delegate = nil` en `onDestroy` + `dealloc`.
+
+### Fixed — Provider Errors
+- **Android DISTANCE_FILTER + RAW `onProviderDisabled`**: era no-op silencioso. Ahora emite `SERVICE_ERROR` cuando no queda ningún provider disponible (el JS puede repromptear al usuario).
+- **iOS `MAURLocationManager` no implementaba el callback iOS 14+ `locationManagerDidChangeAuthorization:`**: solo el legacy deprecado. RAW + ACTIVITY (que usan la singleton) no veían cambios de "Always → While Using" sin reinicio del proceso. Añadido, con guard `@available(iOS 14, *)` en el legacy para evitar doble notificación.
+- **Android RAW solo usaba GPS-o-Network (excluyente)** ignorando `desiredAccuracy`. Ahora `pickProviders` mapea: HIGH (<10 m) → GPS only, BALANCED → GPS+Network, LOW (≥1000 m) → Network only. Suscripción simultánea cuando ambos son útiles.
+- **`AbstractLocationProvider` warning si `stopOnStillActivity: false` con ACTIVITY_PROVIDER**: el provider depende del state machine STILL/ACTIVE; con eso desactivado tracking continuo accidental. Warning en logcat.
+
+### Internal
+- `AbstractLocationProvider` ahora expone `handlePermissionDenied(msg)` y `handleServiceError(msg)` para que los providers emitan `PluginException` sin tocar `mDelegate` directamente.
+
+### Fixed (post-revisión 4.5.2, cuarta iteración — hardening)
+- **`BootCompletedReceiver` ahora valida el `intent.getAction()`**: el receiver está declarado `exported="true"` para recibir `BOOT_COMPLETED` del sistema; sin validar la action, una app maliciosa podría enviarle un intent explícito y disparar el auto-start del servicio. Ahora solo acepta `BOOT_COMPLETED`, `MY_PACKAGE_REPLACED`, y los quickboot OEM (HTC/Samsung); lo demás se ignora con un log warn.
+
+### Fixed (post-revisión 4.5.2, tercera iteración)
+- **iOS `ACTIVITY_PROVIDER` no arrancaba GPS si la app abría con el usuario quieto**: `onStart` subscribía a `CMMotionActivityManager` pero NO llamaba `startTracking`. Si CoreMotion disparaba STILL antes del primer fix, `handleActivityUpdate` (cuya regla es "ACTIVE → start") nunca arrancaba el location manager, así que no llegaba ningún fix y el `onStationaryChanged` inicial nunca se emitía. Restaurado el patrón del SOMotionDetector legacy: `startTracking` se invoca inmediatamente al `onStart`. Si CoreMotion confirma STILL después, el primer fix dispara `onStationaryChanged` + `stopTracking` automáticamente — el consumo de batería sigue acotado.
+
+### Fixed (post-revisión 4.5.2, segunda iteración)
+- **iOS `MAURActivityLocationProvider` UNKNOWN seguía mutando `lastMotionType`**: en la corrección anterior el `return` por UNKNOWN ocurría DESPUÉS de actualizar `lastMotionType`. Si la secuencia era STILL → UNKNOWN, el próximo fix ya no se trataba como stationary porque `lastMotionType` había pasado a `Unknown`. Ahora el `return` es lo primero — UNKNOWN no toca estado ni emite (silenciado además para no spamear consecutivos).
+- **Android `singleUpdatePI` con `FLAG_IMMUTABLE` en API 31+**: `LocationManager.requestSingleUpdate(provider, PendingIntent)` rellena la `Location` en los extras del intent en delivery; con `FLAG_IMMUTABLE` el OS bloquea esa población y el receiver nunca veía el fix. Solo el `singleUpdatePI` se cambió a `FLAG_MUTABLE`; los demás siguen `IMMUTABLE` (alarms y monitor reciben PI sin payload).
+- **`AbstractLocationProvider.hasMockLocationsEnabled` NPE**: `Settings.Secure.getString(...)` puede devolver `null` (clave ausente en el provider de Settings del dispositivo); el `.equals("1")` crasheaba. Invertido a `"1".equals(value)` — null-safe.
+- **DISTANCE_FILTER legacy ahora suscribe GPS+Network simultáneo en modo moving normal**: antes elegía uno (GPS-o-Network excluyente). En Androids baratos/vehiculares donde GPS está "enabled" pero tarda en dar fix, esto perdía la oportunidad de un fix rápido por Network. Burst mode (acquisition) ya lo hacía; ahora moving también.
+
+### Fixed (post-revisión 4.5.2)
+- **iOS `MAURActivityLocationProvider` trataba UNKNOWN como NotMoving**: el branch `activity.stationary || activity.unknown` colapsaba ambos casos a `MAURMotionTypeNotMoving`, lo que paraba GPS al recibir un fix de baja confianza ("unknown" puede llegar con confianza alta). Ahora UNKNOWN se procesa como un tipo aparte: emite `onActivityChanged` pero **no toca el estado de tracking** y **no actualiza `lastMotionType`** (así un STILL/ACTIVE posterior produce la transición correcta). Contradecía el propio comentario "UNKNOWN keeps previous behavior (don't pause on uncertainty)".
+- **README desactualizado**: la tabla de `locationProvider` decía que `DISTANCE_FILTER_PROVIDER` era "Pure Android LocationManager" y "Works without Google Play Services". Actualizada a "hybrid (v4.5.2+)": usa FLP cuando hay Play Services, fallback a LocationManager si no.
+- **README caveats v4.5.2 añadidos**:
+  - `maxAcceptedAccuracy` está apagado por defecto (`null`); recomendaciones por escenario.
+  - `ACTIVITY_PROVIDER` sin `ACTIVITY_RECOGNITION` degrada a tracking continuo (caveat).
+
+### Refactor — Provider internals (sin cambio de API JS, sin pérdida de cobertura)
+- **iOS `ACTIVITY_PROVIDER` migrado a `CMMotionActivityManager` directo** (CoreMotion). Se eliminó la dependencia `SOMotionDetector` (sources + plugin.xml entries). Threading propio (NSOperationQueue) y manejo de permiso "Motion & Fitness" denegado (iOS 11+: `CMMotionActivityManager.authorizationStatus`) con emisión de error.
+- **Android `DISTANCE_FILTER_PROVIDER` ahora es híbrido**: detecta Google Play Services en `onCreate` y elige backend en runtime.
+  - **Play Services disponible** → `FusedLocationProviderClient` + `LocationCallback` (mezcla GPS+Network, mejor batería, `setMinUpdateDistanceMeters`/Priority).
+  - **Play Services ausente** (Huawei/HMS, AOSP, ChinaROMs) → fallback a `android.location.LocationManager` + `LocationListener` (preservando el comportamiento previo a v4.5.2 — el plugin funciona en cualquier Android).
+  - **Eliminado el path de `addProximityAlert`** (decisión de producto: sin geozonas) en ambas rutas; la salida del estado stationary se detecta exclusivamente por polling (FLP `setMaxUpdates(1)` o `LocationManager.requestSingleUpdate`).
+- `DISTANCE_FILTER_PROVIDER` emite `SERVICE_ERROR` cuando ni GPS ni Network están habilitados al `setPace`.
+
+### Matriz Play Services (Android)
+| Provider | Play Services | Comportamiento |
+|----------|---------------|----------------|
+| `RAW_PROVIDER` | No requiere | OS LocationManager directo (GPS+Network simultáneo según `desiredAccuracy`). |
+| `DISTANCE_FILTER_PROVIDER` | Opcional | FLP si está disponible, LocationManager si no. Auto. |
+| `ACTIVITY_PROVIDER` | Requerido | Sin fallback (depende de `ActivityRecognitionClient`). En dispositivos sin Play Services usar `DISTANCE_FILTER` o `RAW`. |
+
 ## [4.5.1](https://github.com/josuelmm/cordova-background-geolocation/tree/4.5.1) (2026-05-09)
 
 ### Fixed (BLOQUEANTES)

package/README.md

@@ -179,6 +179,93 @@ BackgroundGeolocation.FOREGROUND_MODE
 
 Set your preferred provider, accuracy, intervals, and optional server URLs. All options are optional; you can reconfigure later with a subset (options are merged).
 
+#### 1.1 `locationProvider` — which engine produces the fixes
+
+This is the **most important choice**. It changes how often, how accurately, and how cheaply (battery-wise) the plugin gets locations. Three values, pick **one**:
+
+| Value | Constant | Internals | When to use |
+|---|---|---|---|
+| `0` | `BackgroundGeolocation.DISTANCE_FILTER_PROVIDER` (default) | **Hybrid (v4.5.2+)**: `FusedLocationProviderClient` cuando Google Play Services está disponible, fallback automático a `LocationManager` cuando no (Huawei/HMS, AOSP, ChinaROMs). Implementa una **state machine de detección stationary**: mientras se mueve muestrea normal; al detenerse usa **polling lazy** (3 min) y **polling aggressive** (1 min cerca del borde) vía `AlarmManager`. **No usa geofences** (eliminados por decisión de producto); la salida del estado stationary se detecta solo por polling. | **Default para la mayoría de apps.** Tracking personal, couriers de delivery, cualquiera que necesite ubicación sin drenar batería al estar parado. **Funciona con o sin Google Play Services.** |
+| `1` | `BackgroundGeolocation.ACTIVITY_PROVIDER` | Google Play Services `FusedLocationProviderClient` + **Activity Recognition** (walking / driving / still). When `STILL` is detected, the provider stops requesting fixes; when activity resumes, it restarts. Uses `LocationRequest.Builder` + `Priority.PRIORITY_HIGH_ACCURACY` (or balanced, per `desiredAccuracy`). | Apps where the **activity matters** (fitness, fleet, ride-hailing). Best battery profile when the user spends a lot of time still. **Requires Google Play Services** on the device and `ACTIVITY_RECOGNITION` runtime permission on Android 10+. |
+| `2` | `BackgroundGeolocation.RAW_PROVIDER` | Direct `LocationManager` requests with **no stationary detection, no batching, no filtering**. Every fix the OS produces is forwarded. | Vehicle tracking with a **constant interval**, dashcams, anything where you want raw GPS without the plugin trying to be smart. **Highest battery cost.** |
+
+```js
+// Recommended for personal apps (Life360-style)
+BackgroundGeolocation.configure({
+  locationProvider: BackgroundGeolocation.DISTANCE_FILTER_PROVIDER,
+  desiredAccuracy: BackgroundGeolocation.MEDIUM_ACCURACY,
+  distanceFilter: 50,
+  stationaryRadius: 50
+});
+
+// Recommended for fleet/vehicle tracking
+BackgroundGeolocation.configure({
+  locationProvider: BackgroundGeolocation.ACTIVITY_PROVIDER,
+  desiredAccuracy: BackgroundGeolocation.HIGH_ACCURACY,
+  interval: 15000,
+  fastestInterval: 10000,
+  activitiesInterval: 30000
+});
+
+// Raw — every fix, no smart filtering
+BackgroundGeolocation.configure({
+  locationProvider: BackgroundGeolocation.RAW_PROVIDER,
+  desiredAccuracy: BackgroundGeolocation.HIGH_ACCURACY,
+  interval: 5000
+});
+```
+
+**iOS note:** all three constants exist for API parity, but iOS internally always uses `CLLocationManager`. The plugin maps `DISTANCE_FILTER_PROVIDER` and `RAW_PROVIDER` to standard location updates, and `ACTIVITY_PROVIDER` enables `CMMotionActivityManager` for activity detection on top.
+
+#### 1.2 `startOnBoot` — survive a reboot (Android only)
+
+When `true`, the plugin re-arms tracking automatically after the device reboots or after an app update — without the user opening the app.
+
+**How it works internally:**
+
+1. The plugin registers a `BootCompletedReceiver` that listens for `BOOT_COMPLETED`, `QUICKBOOT_POWERON` (HTC/Xiaomi), `com.htc.intent.action.QUICKBOOT_POWERON`, and `MY_PACKAGE_REPLACED` (Play Store updates).
+2. On boot, the receiver loads the **persisted `Config`** from SQLite (since v4.4.1 / v4.5.0 the full config is stored as `config_json`, so `httpMethod`, `queryParams`, `drivingEvents`, etc. survive).
+3. It checks `ACCESS_FINE_LOCATION` / `ACCESS_COARSE_LOCATION`, and on Android 10+ also `ACCESS_BACKGROUND_LOCATION`. If any is missing, it logs and gives up — it will **NOT** request permissions from a receiver (the OS forbids it).
+4. If permissions are OK, it calls `context.startForegroundService(...)`. The plugin's notification appears and tracking resumes with the same config the app had configured before reboot.
+
+**Required runtime permissions** (the app must request them at least once **while it is in foreground**, before relying on `startOnBoot`):
+
+```ts
+// Order matters — the OS dialog flow is strict on Android 11+.
+await BackgroundGeolocation.requestNotificationPermission();        // Android 13+
+// ACCESS_FINE_LOCATION via Cordova permission API or @capacitor/geolocation
+await BackgroundGeolocation.requestBackgroundLocationPermission();  // Android 10+, user MUST pick "Allow all the time"
+```
+
+Without **"Allow all the time"** the receiver runs but the foreground service is killed shortly after, because the OS treats the boot-launched service as "background-started" and a background start without background permission is not allowed.
+
+**iOS:** Apple does **not** allow third-party apps to auto-start at boot. `startOnBoot: true` is silently ignored on iOS. The closest equivalent is **`significantLocationChanges`** (already implemented), which wakes the app when the device moves to a new cell tower / region — but only if the app was running at least once after the reboot. Document this expectation to your iOS users.
+
+**Common pitfalls:**
+
+- **OEM kills (Xiaomi MIUI, Huawei EMUI, Oppo, Vivo, OnePlus, Asus)** disable auto-start by default for non-system apps. The user must enable the app in *"Autostart"* / *"Background activity"* settings of the OEM. Use `BackgroundGeolocation.openAutoStartSettings()` to take the user directly there, and `getManufacturerHelp()` for instructions.
+- **Android 12+ `ForegroundServiceStartNotAllowedException`** — if the device is in *Doze* deep-idle when it reboots, the system may block the foreground service. The plugin catches the exception and logs it; the next user-triggered `start()` (when they open the app) will succeed.
+- **Doze whitelist** — `isIgnoringBatteryOptimizations()` + `requestIgnoreBatteryOptimizations()` reduce the chance of the OS putting the app on the "restricted" list after a reboot.
+
+```js
+// Full recommended setup for "track this user across reboots"
+BackgroundGeolocation.configure({
+  locationProvider: BackgroundGeolocation.DISTANCE_FILTER_PROVIDER,
+  desiredAccuracy: BackgroundGeolocation.MEDIUM_ACCURACY,
+  distanceFilter: 50,
+  startForeground: true,            // mandatory for Android 8+ background tracking
+  notificationsEnabled: true,
+  notificationTitle: 'Live tracking',
+  notificationText: 'Your location is being shared',
+  startOnBoot: true,                // survive reboots
+  stopOnTerminate: false,           // keep tracking when user swipes the app away
+  url: 'https://my.api/locations',
+  syncUrl: 'https://my.api/sync'
+});
+```
+
+#### 1.3 Other main options
+
 **Main options:**
 
 | Option | Description |
@@ -197,14 +284,76 @@ Set your preferred provider, accuracy, intervals, and optional server URLs. All
 | `httpMethod` | **Since 3.3.0.** HTTP method for `url`. `POST` (default) `| GET | PUT | PATCH`. Use `GET` together with URL templating to deliver positions through the query string. |
 | `syncHttpMethod` | **Since 3.3.0.** HTTP method for `syncUrl`. Same values as `httpMethod`. |
 | `httpMode` / `syncMode` | **Since 3.3.0.** `batch` (default) or `single` (one HTTP request per location). `single` is required when the corresponding method is `GET`. |
-| `queryParams` | **Since 3.3.0.** Static placeholder values for URL/body templating (e.g. `{ device_id: 'USER_123' }`). See [HTTP transport](docs/api.md#http-transport-since-330). |
+| `queryParams` | **Since 3.3.0.** Static placeholder values for URL/body templating (e.g. `{ device_id: 'USER_123' }`). See [HTTP transport](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/api.md#http-transport-since-330). |
 | `postTemplate` / `bodyTemplate` | Object or array of properties to send. Supports `@latitude`, `@longitude`, ... and the new `{latitude}`, `{lon}`, `{timestamp_iso}`, ... placeholders on string values. `bodyTemplate` is the alias added in 3.3.0. |
 | `maxLocations` | Max locations kept in DB (default 10000). Should be > `syncThreshold`. |
 
+**Diagnostics / sync (3.5+):**
+
+| Option | Description |
+|--------|-------------|
+| `heartbeatInterval` | ms between `heartbeat` events. `0` (default) disables. |
+| `mockLocationPolicy` | `'allow'` (default) / `'flag'` / `'drop'` — what to do with mocked locations. |
+
+**Driver insights (4.0+):**
+
+| Option | Description |
+|--------|-------------|
+| `drivingEvents.enabled` | Master switch. Default `false`. |
+| `drivingEvents.speedLimit` | km/h for `speeding` event. `0` disables. |
+| `drivingEvents.minMovingSpeed` | m/s threshold for "moving" (default 1.0). |
+| `drivingEvents.stoppedDuration` | ms of below-threshold needed for "stopped" (default 60 000). |
+| `drivingEvents.minTripSpeed` | m/s threshold for `tripStart` (default 3.0). |
+| `drivingEvents.minTripDuration` | ms sustained to fire `tripStart` (default 30 000). |
+| `drivingEvents.hardBrakeMps2` | m/s² threshold for `hardBrake` (default 3.5; `0` disables). |
+| `drivingEvents.rapidAccelMps2` | m/s² threshold for `rapidAcceleration` (default 3.5). |
+| `drivingEvents.sharpTurnDegPerSec` | deg/s for `sharpTurn` at speed ≥ 5 m/s (default 30). |
+| `drivingEvents.crashImpactKmh` | km/h drop within window for GPS `possibleCrash` (default 25). |
+| `drivingEvents.crashWindowMs` | window for GPS crash detection (default 2 000). |
+| `drivingEvents.sensorFusion` | **4.2+.** Enable accelerometer + gyroscope. Off by default. |
+| `drivingEvents.crashImpactG` | g threshold for sensor `possibleCrash` (default 3.0). |
+| `drivingEvents.sensorCrashCooldownMs` | ms cooldown between sensor crash detections (default 10 000). |
+| `drivingEvents.phoneUsageWindowMs` | ms of sustained jitter to fire `phoneUsageWhileDriving` (default 4 000). |
+| `drivingEvents.phoneUsageCooldownMs` | ms cooldown between phone-usage events (default 60 000). |
+
+**Battery payload (4.4+):**
+
+| Option | Description |
+|--------|-------------|
+| `includeBattery` | Stamp `battery` (0-100) and `isCharging` on every fix. Default `true`. |
+
+**Battery saving (4.5.1):**
+
+| Option | Description |
+|--------|-------------|
+| `wakeLockMode` | `'none' \| 'posting' \| 'always'`. Default `'posting'`. |
+| `stationaryTimeout` | ms of no movement → declare stationary (Android `DISTANCE_FILTER_PROVIDER`). Default 300 000. |
+| `stationaryPollInterval` | Lazy poll interval while stationary (ms). Default 180 000. |
+| `stationaryPollFast` | Aggressive poll near the stationary boundary (ms). Default 60 000. |
+
+**Provider hardening (4.5.2):**
+
+| Option | Description |
+|--------|-------------|
+| `activityConfidenceThreshold` | 0-100. Ignore STILL/ACTIVE transitions below this confidence (prevents jittery GPS start/stop). iOS normalizes Low/Med/High → 20/40/80. Default 50. Applies to `ACTIVITY_PROVIDER`. |
+| `maxAcceptedAccuracy` | Maximum accepted horizontal accuracy in meters. Fixes worse than this are dropped before persist/POST/JS emission. **Off by default (`null`)** to avoid regressing existing apps. Recommended values: `100` for vehicular tracking, `500` for tolerant scenarios. All providers. |
+
+> **Caveats v4.5.2:**
+> - `maxAcceptedAccuracy` está **apagado por defecto**. Si quieres descartar fixes ruidosos (típico en GPS vehicular o indoor), seteá explícito un valor (ej. `100`).
+> - **ACTIVITY_PROVIDER sin `ACTIVITY_RECOGNITION`** (Android 10+): el provider emite `PERMISSION_DENIED_ERROR` pero **degrada a tracking continuo** (no puede detectar STILL/ACTIVE). Si querés ahorro real, pedí el permiso antes de iniciar o cambiá a `DISTANCE_FILTER_PROVIDER`.
+> - **`enableWatchdog`** está **apagado por defecto**. Reinicia el provider si deja de llegar `location` por ~60s (solo si `tripActive`). Útil en apps vehiculares/críticas; aumenta consumo. Recomendado `false` salvo necesidad real.
+> - **`postTemplate` reemplaza el payload completo** — no hay merge con el default. Si lo defines, debes incluir manualmente `@events`, `@battery`, `@isCharging` si los necesitas. Detalle en [docs/api.md](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/api.md#custom-post-template).
+> - **`events` / `battery` / `isCharging` sobreviven la cola de sync** desde v4.5.0 (Android schema v22, iOS schema v7). Si un POST falla, esos campos persisten para `forceSync`/sync automático. Auto-migración desde versiones previas.
+> - **`pendingDrivingEvents` son in-memory**: el detector almacena eventos (hardBrake, speeding, etc.) hasta anexarlos al próximo `location` (cap 20, TTL 60s). Si el proceso muere antes del próximo fix, esos eventos pueden perderse. La cola principal de ubicaciones no se afecta.
+> - **`startOnBoot`** requiere: `stopOnTerminate: false` (o config persistida), `ACCESS_BACKGROUND_LOCATION` concedido (Android 10+), y que el fabricante no bloquee autostart/battery optimization. Xiaomi/Huawei/Oppo/Vivo suelen requerir desactivar manualmente la optimización de batería — usar `openBatterySettings()` / `openAutoStartSettings()` para guiar al usuario.
+> - **Permisos por versión Android**: Android 10+ requiere `ACCESS_BACKGROUND_LOCATION` para tracking real en background. Android 10+ requiere `ACTIVITY_RECOGNITION` para `ACTIVITY_PROVIDER`. Android 13+ requiere `POST_NOTIFICATIONS` para la notificación foreground. Android 14+ requiere `FOREGROUND_SERVICE_LOCATION`. El plugin no fuerza permisos automáticamente; usar los helpers `requestBackgroundLocationPermission()`, `requestActivityRecognitionPermission()` y `requestNotificationPermission()`.
+
 **Android-only:** `notificationSyncTitle`, `notificationSyncText`, `notificationSyncCompletedText`, `notificationSyncFailedText` — texts shown in the notification while syncing (defaults in English; set for localization). `startForeground`, `notificationsEnabled`, `startOnBoot`, `stopOnTerminate`, `enableWatchdog`.
 
 **iOS-only:** `activityType`, `pauseLocationUpdates`, `saveBatteryOnBackground`, `showsBackgroundLocationIndicator` (since 3.4.0; iOS 11+, shows the blue background indicator).
 
+**Full reference** (every option, with types, defaults and platform/provider hints): [`docs/api.md`](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/api.md).
+
 Example (default POST + JSON):
 
 ```js
@@ -250,7 +399,7 @@ BackgroundGeolocation.configure({
 });
 ```
 
-> **Android runtime permissions.** With `startOnBoot: true`, the app must request `ACCESS_FINE_LOCATION` first, then `POST_NOTIFICATIONS` (Android 13+), and finally `ACCESS_BACKGROUND_LOCATION` (Android 10+, the user must pick **Allow all the time**). Without the background permission the plugin will skip the start on boot. iOS does **not** allow auto-start on device boot (Apple restriction). See [Auto-start on Android boot](docs/api.md#auto-start-on-android-boot-since-330) for the full flow.
+> **Android runtime permissions.** With `startOnBoot: true`, the app must request `ACCESS_FINE_LOCATION` first, then `POST_NOTIFICATIONS` (Android 13+), and finally `ACCESS_BACKGROUND_LOCATION` (Android 10+, the user must pick **Allow all the time**). Without the background permission the plugin will skip the start on boot. iOS does **not** allow auto-start on device boot (Apple restriction). See [Auto-start on Android boot](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/api.md#auto-start-on-android-boot-since-330) for the full flow.
 
 ### 2. Start tracking
 
@@ -298,7 +447,7 @@ When you use `syncUrl`, locations that fail to post to `url` (or that are only q
 | **`application/json`** (default) | **One POST** with a JSON **array** of all locations in the batch. |
 | **`application/x-www-form-urlencoded`** | **One POST per location** (same flat `key=value&...` as real-time to `url`). Same endpoint can handle both. |
 
-So: with **JSON** you get one request per batch (e.g. 100 locations in one body). With **form-urlencoded** you get one request per location (one record per POST). For headers, retries, `postTemplate` and full behaviour see [HTTP posting](docs/http_posting.md) and [API](docs/api.md).
+So: with **JSON** you get one request per batch (e.g. 100 locations in one body). With **form-urlencoded** you get one request per location (one record per POST). For headers, retries, `postTemplate` and full behaviour see [HTTP posting](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/http_posting.md) and [API](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/api.md).
 
 You can:
 
@@ -325,27 +474,41 @@ BackgroundGeolocation.clearSync().then(function () {
 });
 ```
 
-More on sync (headers, retries, postTemplate): [HTTP posting](docs/http_posting.md). Full options and methods: [API](docs/api.md).
+More on sync (headers, retries, postTemplate): [HTTP posting](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/http_posting.md). Full options and methods: [API](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/api.md).
 
 ### 6. Other methods (summary)
 
-| Method | Description |
-|--------|-------------|
-| `getConfig(success, fail)` | Get current configuration (merged options). |
-| `getLocations(success, fail)` | Get all stored locations. |
-| `getValidLocations(success, fail)` | Get locations not yet posted (valid only). |
-| `deleteLocation(id, success, fail)` | Delete one location by id. |
-| `deleteAllLocations(success, fail)` | Delete all stored locations. |
-| `getCurrentLocation(success, fail, options)` | One-shot location (e.g. timeout, maximumAge). |
-| `getPluginVersion(success, fail)` | Plugin version string (e.g. "3.2.0"). |
-| `checkStatus(success, fail)` | Service status (isRunning, authorization, etc.). |
-| `showAppSettings()` / `openSettings()` | Open app settings. |
-| `showLocationSettings()` | Open system location settings. |
-| `getLogEntries(limit, fromId, minLevel, success, fail)` | Debug log entries. |
-| `startSession(success, fail)` | Start session: clear session table and store all new locations until `clearSession()`. |
-| `getSessionLocations(success, fail)` | All locations in current session (restore route when reopening without internet). |
-| `clearSession(success, fail)` | Clear session table (call when route finished and sync OK). |
-| `getSessionLocationsCount(success, fail)` | Number of locations in current session. |
+| Method | Since | Description |
+|--------|-------|-------------|
+| `getConfig(success, fail)` | 1.0 | Get current configuration (merged options). |
+| `getLocations(success, fail)` | 1.0 | Get all stored locations. |
+| `getValidLocations(success, fail)` | 1.0 | Get locations not yet posted (valid only). |
+| `deleteLocation(id, success, fail)` | 1.0 | Delete one location by id. |
+| `deleteAllLocations(success, fail)` | 1.0 | Delete all stored locations. |
+| `getCurrentLocation(success, fail, options)` | 1.0 | One-shot location (e.g. timeout, maximumAge). |
+| `getPluginVersion(success, fail)` | 1.0 | Plugin version string (e.g. `"4.5.1"`). |
+| `checkStatus(success, fail)` | 1.0 | Service status (isRunning, authorization, etc.). |
+| `showAppSettings()` / `openSettings()` | 1.0 | Open app settings. |
+| `showLocationSettings()` | 1.0 | Open system location settings. |
+| `getLogEntries(limit, fromId, minLevel, success, fail)` | 1.0 | Debug log entries. |
+| `getPendingSyncCount(success, fail)` | 3.1 | Number of locations pending sync. |
+| `forceSync(success, fail)` | 3.1 | Send pending locations immediately (ignores `syncThreshold`). |
+| `clearSync(success, fail)` | 3.1 | Discard pending sync queue without sending. |
+| `startSession(success, fail)` | 3.2 | Start session: clear session table and store new locations until `clearSession()`. |
+| `getSessionLocations(success, fail)` | 3.2 | All locations in current session. |
+| `clearSession(success, fail)` | 3.2 | Clear session table (call when route finished). |
+| `getSessionLocationsCount(success, fail)` | 3.2 | Number of locations in current session. |
+| `getDiagnostics(success, fail)` | 3.5 | Extended diagnostics: permissions, battery optimisation, OEM, last fix age, pending sync, iOS precise location, etc. |
+| `isIgnoringBatteryOptimizations(success, fail)` | 3.6 | Android only. `true` if app is on the Doze whitelist. iOS always `true`. |
+| `requestIgnoreBatteryOptimizations(success, fail)` | 3.6 | Android only. Opens the system dialog to add the app to the whitelist. |
+| `openBatterySettings(success, fail)` | 3.6 | Android only. Opens the battery-related settings screen for this app. |
+| `openAutoStartSettings(success, fail)` | 3.6 | Android only. Opens the OEM-specific auto-start screen (Xiaomi/Huawei/Oppo/Vivo/OnePlus/Asus). |
+| `getManufacturerHelp(success, fail)` | 3.6 | Returns `{ manufacturer, steps[] }` with OEM-specific guidance text. |
+| `triggerSOS(payload?, success, fail)` | 4.0 | Emit a single `sos` event with the latest location plus your payload. Host app handles actual SOS workflow. |
+| `requestBackgroundLocationPermission(success, fail)` | 4.5 | Android 10+. Request `ACCESS_BACKGROUND_LOCATION`. iOS / older Android resolve `{ granted: true, notRequired: true }`. |
+| `requestActivityRecognitionPermission(success, fail)` | 4.5 | Android 10+. Request `ACTIVITY_RECOGNITION`. |
+| `requestNotificationPermission(success, fail)` | 4.5 | Android 13+. Request `POST_NOTIFICATIONS`. |
+| `headlessTask(task)` | 1.0 | **Android only.** Run JS when app is terminated and `stopOnTerminate: false`. iOS no-op. |
 
 All methods return a **Promise** if you omit the `success` / `fail` callbacks.
 
@@ -353,6 +516,8 @@ All methods return a **Promise** if you omit the `success` / `fail` callbacks.
 
 Subscribe with `BackgroundGeolocation.on(eventName, callback)`. Unsubscribe with the returned object’s `remove()` or by calling `removeAllListeners(eventName)`.
 
+#### Core (1.0+)
+
 | Event | Payload | When |
 |-------|---------|------|
 | `location` | Location object | New location (foreground/background). |
@@ -366,7 +531,57 @@ Subscribe with `BackgroundGeolocation.on(eventName, callback)`. Unsubscribe with
 | `http_authorization` | — | Server returned 401; refresh token and reconfigure headers. |
 | `abort_requested` | — | Server returned 285 (updates not required). |
 
-Full event payloads and options: [Events](docs/events.md). Full API (all options, all methods): [API](docs/api.md).
+#### Diagnostics + Sync (3.5+)
+
+| Event | Payload | When |
+|-------|---------|------|
+| `heartbeat` | `Location` or `void` | Periodic heartbeat at `heartbeatInterval` ms. Disabled when `heartbeatInterval = 0`. |
+| `syncStart` | — | Background sync POST started. |
+| `syncProgress` | `number` (0-100) | Sync upload progress. |
+| `syncSuccess` | `{ sent: number }` | Sync completed, N locations uploaded. |
+| `syncError` | `{ httpStatus, message }` | Sync failed (network or server). |
+
+#### Driver insights (4.0+)
+
+| Event | Payload | When |
+|-------|---------|------|
+| `tripStart` | `Location` | Sustained speed ≥ `minTripSpeed` for `minTripDuration` ms. |
+| `tripEnd` | `{ location, distance, durationMs }` | Stationary detected during active trip. |
+| `moving` | `Location` | Speed crossed `minMovingSpeed` upward. |
+| `stopped` | `Location` | `stoppedDuration` ms below `minMovingSpeed`. |
+| `speeding` | `{ location, speedKmh, limitKmh }` | Above `drivingEvents.speedLimit` (rearms on drop). |
+| `providerChange` | `{ provider }` | Location provider changed (gps/network/fused). |
+| `sos` | `{ location, ...payload }` | `BackgroundGeolocation.triggerSOS(payload)` invoked. |
+
+#### Driving events — GPS-derived (4.1+) / sensor fusion (4.2+)
+
+| Event | Payload | When |
+|-------|---------|------|
+| `hardBrake` | `{ location, value }` | Δspeed/Δt ≤ −`hardBrakeMps2` during active trip. `value` is m/s² (negative). |
+| `rapidAcceleration` | `{ location, value }` | Δspeed/Δt ≥ `rapidAccelMps2`. `value` is m/s² (positive). |
+| `sharpTurn` | `{ location, value }` | Bearing change rate ≥ `sharpTurnDegPerSec` and speed ≥ 5 m/s. `value` is deg/s. |
+| `possibleCrash` | `{ location, value, source }` | GPS heuristic (`source: 'gps'`, `value`: km/h drop) **or** sensor impact (`source: 'sensor'`, `value`: g). Always confirm with user before notifying contacts. |
+| `phoneUsageWhileDriving` | `Location` | Sustained device interaction during active trip with screen on. Requires `drivingEvents.sensorFusion: true`. |
+
+Full event payloads and options: [Events](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/events.md). Full API (all options, all methods): [API](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/api.md).
+
+### New in 4.5.1
+
+Stability + battery optimization release. No new features — only fixes that make the plugin safe for long-term production.
+
+- **`wakeLockMode: 'none' | 'posting' | 'always'`** (default `'posting'`). Replaces the previous always-on `PARTIAL_WAKE_LOCK`. `'posting'` acquires a bounded 30 s lock around each fix (SQLite + HTTP POST); `'none'` never acquires; `'always'` is the legacy behaviour for fleet/emergency apps.
+- **Watchdog moving-only** — `enableWatchdog: true` no longer restarts the provider when the device is intentionally stationary. Saves real battery during parking/idle.
+- **Stationary detection configurable** — `stationaryTimeout`, `stationaryPollInterval`, `stationaryPollFast` (Android `DISTANCE_FILTER_PROVIDER`). Defaults: 300 000 / 180 000 / 60 000 ms.
+- **Critical persistence fixes**: `maxLocations` recycle no longer mixes old `events_json`/`battery_level`/`is_charging` into new rows; iOS sync no longer marks rows `Deleted` before the upload finishes (was losing the whole queue on network drop). iOS rescues `SyncPending` rows stale > 15 min after a crash.
+- **iOS race condition fixed**: `MAURLocationMapper._location` was a file-scope global → real-time post + background sync running concurrently produced mixed fixes. Now per-instance ivar.
+- **`locationTransform`**: events / battery / charging now survive transforms that return a new instance (both platforms).
+
+### New in 4.5.0
+
+- **Driving events, battery and isCharging now survive the sync queue.** Android DB v22 + iOS DB v7 add `events_json` / `battery_level` / `is_charging` columns on `location`. When a real-time POST fails and the location enters SQLite, those fields travel with it to the backend on the next sync.
+- **iOS config persistence parity** — `MAURConfig` now serialises post-3.2 keys (`httpMethod`, `queryParams`, `drivingEvents`, `includeBattery`, etc.) to a `config_json` blob, matching Android v4.4.1.
+- **Runtime permission helpers** (Android): `requestBackgroundLocationPermission()`, `requestActivityRecognitionPermission()`, `requestNotificationPermission()`. iOS / older Android resolve `{ granted: true, notRequired: true }`.
+- **iOS background sync cleanup**: rows that were uploaded successfully are now removed from SQLite (the previous code re-uploaded them every cycle).
 
 ### New in 4.4.0
 
@@ -444,7 +659,7 @@ BackgroundGeolocation.on('phoneUsageWhileDriving', (location) => {
 });
 ```
 
-Full reference (all thresholds, when to enable, iOS screen-on caveat): [docs/api.md → Driver insights](docs/api.md#driver-insights-since-400).
+Full reference (all thresholds, when to enable, iOS screen-on caveat): [docs/api.md → Driver insights](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/api.md#driver-insights-since-400).
 
 ### New in 4.1.0
 
@@ -473,7 +688,7 @@ Full reference (all thresholds, when to enable, iOS screen-on caveat): [docs/api
 
 ### New in 3.5.0
 
-- **`getDiagnostics()` (Phase 4).** New extended diagnostics method that helps you debug "tracking is not running" in production. Returns permissions (`fineLocationGranted`, `coarseLocationGranted`, `backgroundLocationGranted`, `notificationPermissionGranted`, `activityRecognitionGranted`), battery optimisation state (`batteryOptimizationIgnored`), OEM manufacturer (`manufacturer`), last-fix timestamp, pending sync count, declared `foregroundServiceType` (Android), and `preciseLocationEnabled`, `backgroundRefreshStatus`, `lowPowerModeEnabled`, `motionPermissionStatus` (iOS). Use it to surface actionable hints to users like "Allow all the time" or "Disable battery optimisation". See [getDiagnostics](docs/api.md#getdiagnosticssuccess-fail).
+- **`getDiagnostics()` (Phase 4).** New extended diagnostics method that helps you debug "tracking is not running" in production. Returns permissions (`fineLocationGranted`, `coarseLocationGranted`, `backgroundLocationGranted`, `notificationPermissionGranted`, `activityRecognitionGranted`), battery optimisation state (`batteryOptimizationIgnored`), OEM manufacturer (`manufacturer`), last-fix timestamp, pending sync count, declared `foregroundServiceType` (Android), and `preciseLocationEnabled`, `backgroundRefreshStatus`, `lowPowerModeEnabled`, `motionPermissionStatus` (iOS). Use it to surface actionable hints to users like "Allow all the time" or "Disable battery optimisation". See [getDiagnostics](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/api.md#getdiagnosticssuccess-fail).
 - **`mockLocationPolicy: 'allow' | 'flag' | 'drop'`** — policy for mocked locations. Detection (`isFromMockProvider` Android, `simulated` iOS) was already present; this option controls what to do with those samples. Recommended for anti-fraud: `'flag'` (keep them but tagged) or `'drop'` (discard).
 - **`heartbeatInterval`** option plus events `heartbeat`, `syncStart`, `syncProgress`, `syncSuccess`, `syncError` are all wired end-to-end with native emission on Android and iOS. Subscribe via `BackgroundGeolocation.on('heartbeat', cb)` etc.
 - The Angular service exposes `getDiagnostics()` directly.
@@ -488,7 +703,7 @@ Full reference (all thresholds, when to enable, iOS screen-on caveat): [docs/api
 ### New in 3.3.0
 
 - **Auto-start Android (Phase 1).** The plugin's boot receiver now also handles `QUICKBOOT_POWERON` (HTC, MIUI / Xiaomi), `com.htc.intent.action.QUICKBOOT_POWERON`, and `MY_PACKAGE_REPLACED` (the service relaunches after a Play Store update). Added `ACCESS_BACKGROUND_LOCATION` to the manifest with runtime validation on Android 10+. `ForegroundServiceStartNotAllowedException` (Android 12+) is caught with clear logging — WorkManager is **not** used as a fallback for tracking. The `foregroundServiceType` is now `"location"` only (dropped `dataSync`); the runtime type is read dynamically from the merged manifest. `<uses-library org.apache.http.legacy>` and `useLibrary 'org.apache.http.legacy'` are removed (the plugin uses `HttpURLConnection`). `jcenter()` → `mavenCentral()`.
-- **Backend-agnostic HTTP transport (Phase 2).** New `httpMethod`, `syncHttpMethod`, `httpMode`, `syncMode`, `queryParams`, `headers` (alias of `httpHeaders`), `bodyTemplate` (alias of `postTemplate`). URL templating with `{latitude}`, `{longitude}`, `{lat}`, `{lon}`, `{time}`, `{timestamp}`, `{timestamp_iso}`, `{speed}`, `{altitude}`, `{bearing}`, `{accuracy}`, `{provider}` and any keys from `queryParams`. The plugin no longer hardcodes `POST` on Android (`HttpPostService`) or iOS (`MAURPostLocationTask`, `MAURBackgroundSync`). Compatibility is fully preserved — apps that only set `url` + `httpHeaders` + `postTemplate` keep working unchanged. See [HTTP transport](docs/api.md#http-transport-since-330) for backend examples (REST, GET single, form-urlencoded, Firebase, n8n).
+- **Backend-agnostic HTTP transport (Phase 2).** New `httpMethod`, `syncHttpMethod`, `httpMode`, `syncMode`, `queryParams`, `headers` (alias of `httpHeaders`), `bodyTemplate` (alias of `postTemplate`). URL templating with `{latitude}`, `{longitude}`, `{lat}`, `{lon}`, `{time}`, `{timestamp}`, `{timestamp_iso}`, `{speed}`, `{altitude}`, `{bearing}`, `{accuracy}`, `{provider}` and any keys from `queryParams`. The plugin no longer hardcodes `POST` on Android (`HttpPostService`) or iOS (`MAURPostLocationTask`, `MAURBackgroundSync`). Compatibility is fully preserved — apps that only set `url` + `httpHeaders` + `postTemplate` keep working unchanged. See [HTTP transport](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/api.md#http-transport-since-330) for backend examples (REST, GET single, form-urlencoded, Firebase, n8n).
 - **Engines:** `cordova-android >= 12.0.0` is now the minimum.
 
 ### New in 3.2.0
@@ -502,7 +717,7 @@ Full reference (all thresholds, when to enable, iOS screen-on caveat): [docs/api
 
 ### New in 3.1.1
 
-- **Browser / `ng serve` builds** — The plugin can now be bundled by webpack without "Can't resolve 'cordova/exec'" or "Can't resolve 'cordova/channel'". The package ships stub modules and a `browser` field so `ng serve` and browser builds succeed; on device/emulator the stubs delegate to the real Cordova API. See [docs/angular.md](docs/angular.md#build-ng-serve--browser).
+- **Browser / `ng serve` builds** — The plugin can now be bundled by webpack without "Can't resolve 'cordova/exec'" or "Can't resolve 'cordova/channel'". The package ships stub modules and a `browser` field so `ng serve` and browser builds succeed; on device/emulator the stubs delegate to the real Cordova API. See [docs/angular.md](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/angular.md#build-ng-serve--browser).
 
 ### New in 3.1.0
 
@@ -515,7 +730,7 @@ Full reference (all thresholds, when to enable, iOS screen-on caveat): [docs/api
 
 ---
 
-More (stationary, activity, headless task, Angular) is in the [documentation](https://josuelmm.github.io/cordova-background-geolocation/). For **Angular** (service, methods, events), see [docs/angular.md](docs/angular.md).
+More (stationary, activity, headless task, Angular) is in the [documentation](https://josuelmm.github.io/cordova-background-geolocation/). For **Angular** (service, methods, events), see [docs/angular.md](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/angular.md).
 
 ---
 
@@ -558,13 +773,13 @@ export class MyService {
 }
 ```
 
-**You must import `BackgroundGeolocationModule`** in your `AppModule` (or feature module) so the service is provided and AOT builds work. Then inject `BackgroundGeolocationService` as in the example above. See [docs/angular.md](docs/angular.md) for the full snippet.
+**You must import `BackgroundGeolocationModule`** in your `AppModule` (or feature module) so the service is provided and AOT builds work. Then inject `BackgroundGeolocationService` as in the example above. See [docs/angular.md](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/angular.md) for the full snippet.
 
-**`ng serve` / browser:** From 3.1.1 the plugin includes browser stubs so `ng serve` and web builds complete without "Can't resolve 'cordova/exec'" — see [docs/angular.md](docs/angular.md#build-ng-serve--browser).
+**`ng serve` / browser:** From 3.1.1 the plugin includes browser stubs so `ng serve` and web builds complete without "Can't resolve 'cordova/exec'" — see [docs/angular.md](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/angular.md#build-ng-serve--browser).
 
-**Lazy-loaded pages:** If you see **NG0202** or *"dependency at index N is invalid"* when opening a page that injects this service, use an app-defined token and inject by that token (the plugin token can be undefined in the lazy chunk). See [docs/angular.md](docs/angular.md) (Lazy-loaded modules).
+**Lazy-loaded pages:** If you see **NG0202** or *"dependency at index N is invalid"* when opening a page that injects this service, use an app-defined token and inject by that token (the plugin token can be undefined in the lazy chunk). See [docs/angular.md](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/angular.md) (Lazy-loaded modules).
 
-**Migrating from @awesome-cordova-plugins/background-geolocation:** there you inject a class named `BackgroundGeolocation`. In this package, `BackgroundGeolocation` is the **global plugin object**, not an injectable class. Use `BackgroundGeolocationService` instead (same API). See [docs/angular.md](docs/angular.md) for details.
+**Migrating from @awesome-cordova-plugins/background-geolocation:** there you inject a class named `BackgroundGeolocation`. In this package, `BackgroundGeolocation` is the **global plugin object**, not an injectable class. Use `BackgroundGeolocationService` instead (same API). See [docs/angular.md](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/angular.md) for details.
 
 ### Summary
 
@@ -590,6 +805,11 @@ No extra wrapper (e.g. Awesome Cordova Plugins) is required.
 > 3.3.0+: `cordova-android >= 12` is required for `targetSdk 34+` and the modernised foreground-service handling. The new iOS APIs (`showsBackgroundLocationIndicator` iOS 11+, `locationManagerDidChangeAuthorization:` iOS 14+) are gated by runtime `@available` checks, so older iOS versions still link and run.
 >
 > 4.5.0+: SQLite schemas bumped (Android v22, iOS v7) to persist `events`, `battery`, `isCharging` across the sync queue. Upgrades from any earlier version auto-migrate.
+>
+> 4.5.2+ — **Google Play Services matrix (Android)**:
+> - `RAW_PROVIDER` — no requiere Play Services (usa OS LocationManager). Funciona en Huawei/HMS, AOSP, China ROMs.
+> - `DISTANCE_FILTER_PROVIDER` — **híbrido**: usa `FusedLocationProviderClient` cuando hay Play Services, fallback automático a `LocationManager` cuando no. Funciona en todos los Android.
+> - `ACTIVITY_PROVIDER` — **requiere Play Services** (depende de `ActivityRecognitionClient`, sin equivalente OS). En dispositivos sin Play Services usar `DISTANCE_FILTER_PROVIDER` o `RAW_PROVIDER`.
 
 ---
 
@@ -599,16 +819,16 @@ This README is the main entry point. For more detail, edge cases and examples us
 
 | Doc | What you'll find |
 |-----|------------------|
-| **[API reference](docs/api.md)** | Every `configure` option, every method (`configure`, `start`, `stop`, `getPendingSyncCount`, `forceSync`, `clearSync`, `startSession`, `getSessionLocations`, `clearSession`, `getSessionLocationsCount`, `getConfig`, `getLocations`, etc.), TypeScript types. Also covers the **HTTP transport (3.3.0)** and **auto-start on Android boot (3.3.0)**. |
-| **[HTTP transport (3.3.0)](docs/http-transport.md)** | `httpMethod`, `httpMode`, URL templating, `bodyTemplate`, `queryParams`, examples for REST, GET single, form-urlencoded, Firebase, n8n, Traccar. |
-| **[Auto-start on boot (3.3.0)](docs/auto-start.md)** | Android receiver actions, `ACCESS_BACKGROUND_LOCATION` runtime flow, OEM caveats, iOS limitation. |
-| **[Traccar integration example](docs/traccar.md)** | Optional backend: how to deliver positions to Traccar (or Firebase, n8n, custom REST) via the HTTP transport. The plugin is backend-agnostic. |
-| **[Location modernization (3.4.0)](docs/location-modernization.md)** | What was modernised in Phase 3 (LocationRequest.Builder, NSURLSession, iOS 14+ auth callback) and what is still legacy. |
-| **[Roadmap](docs/ROADMAP.md)** | Phases 1–6, what's released, what's next. |
-| **[HTTP posting](docs/http_posting.md)** | `url` vs `syncUrl`, Content-Type (JSON = one POST with array; form-urlencoded = one POST per location), headers, retries, `postTemplate`, sync behaviour. |
-| **[Events](docs/events.md)** | All events (`location`, `error`, `stationary`, `activity`, `http_authorization`, etc.) and payloads. |
-| **[Angular / Ionic](docs/angular.md)** | Injectable service, module, lazy-loaded modules and token "must be defined", `ng serve` / browser build. |
-| **[Example](docs/example.md)** | Full example with events and sync. |
+| **[API reference](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/api.md)** | Every `configure` option, every method (`configure`, `start`, `stop`, `getPendingSyncCount`, `forceSync`, `clearSync`, `startSession`, `getSessionLocations`, `clearSession`, `getSessionLocationsCount`, `getConfig`, `getLocations`, etc.), TypeScript types. Also covers the **HTTP transport (3.3.0)** and **auto-start on Android boot (3.3.0)**. |
+| **[HTTP transport (3.3.0)](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/http-transport.md)** | `httpMethod`, `httpMode`, URL templating, `bodyTemplate`, `queryParams`, examples for REST, GET single, form-urlencoded, Firebase, n8n, Traccar. |
+| **[Auto-start on boot (3.3.0)](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/auto-start.md)** | Android receiver actions, `ACCESS_BACKGROUND_LOCATION` runtime flow, OEM caveats, iOS limitation. |
+| **[Traccar integration example](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/traccar.md)** | Optional backend: how to deliver positions to Traccar (or Firebase, n8n, custom REST) via the HTTP transport. The plugin is backend-agnostic. |
+| **[Location modernization (3.4.0)](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/location-modernization.md)** | What was modernised in Phase 3 (LocationRequest.Builder, NSURLSession, iOS 14+ auth callback) and what is still legacy. |
+| **[Roadmap](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/ROADMAP.md)** | Phases 1–6, what's released, what's next. |
+| **[HTTP posting](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/http_posting.md)** | `url` vs `syncUrl`, Content-Type (JSON = one POST with array; form-urlencoded = one POST per location), headers, retries, `postTemplate`, sync behaviour. |
+| **[Events](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/events.md)** | All events (`location`, `error`, `stationary`, `activity`, `http_authorization`, etc.) and payloads. |
+| **[Angular / Ionic](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/angular.md)** | Injectable service, module, lazy-loaded modules and token "must be defined", `ng serve` / browser build. |
+| **[Example](https://github.com/josuelmm/cordova-background-geolocation/blob/main/docs/example.md)** | Full example with events and sync. |
 | **[CHANGELOG](CHANGELOG.md)** | Version history. |
 
 This project is based on [@mauron85/cordova-plugin-background-geolocation](https://github.com/mauron85/cordova-plugin-background-geolocation) and the original by [christocracy](https://github.com/christocracy). Maintained at [josuelmm/cordova-background-geolocation](https://github.com/josuelmm/cordova-background-geolocation). Issues and PRs welcome.

package/android/CDVBackgroundGeolocation/src/main/java/com/marianhello/bgloc/cordova/ConfigMapper.java

@@ -198,6 +198,13 @@ public class ConfigMapper {
         if (jObject.has("stationaryPollFast") && !jObject.isNull("stationaryPollFast")) {
             config.setStationaryPollFast(jObject.getInt("stationaryPollFast"));
         }
+        // v4.5.2: provider hardening
+        if (jObject.has("activityConfidenceThreshold") && !jObject.isNull("activityConfidenceThreshold")) {
+            config.setActivityConfidenceThreshold(jObject.getInt("activityConfidenceThreshold"));
+        }
+        if (jObject.has("maxAcceptedAccuracy") && !jObject.isNull("maxAcceptedAccuracy")) {
+            config.setMaxAcceptedAccuracy((float) jObject.getDouble("maxAcceptedAccuracy"));
+        }
 
         return config;
     }
@@ -288,6 +295,9 @@ public class ConfigMapper {
         json.put("stationaryTimeout", config.getStationaryTimeout());
         json.put("stationaryPollInterval", config.getStationaryPollInterval());
         json.put("stationaryPollFast", config.getStationaryPollFast());
+        // v4.5.2 provider hardening
+        json.put("activityConfidenceThreshold", config.getActivityConfidenceThreshold());
+        json.put("maxAcceptedAccuracy", config.getMaxAcceptedAccuracy());
 
         return json;
     }

package/android/CDVBackgroundGeolocation/src/main/java/com/tenforwardconsulting/bgloc/cordova/BackgroundGeolocationPlugin.java

@@ -96,7 +96,7 @@ public class BackgroundGeolocationPlugin extends CordovaPlugin implements Plugin
     public static final String ACTION_REQUEST_NOTIFICATION_PERMISSION = "requestNotificationPermission";
 
     /** Plugin version; keep in sync with plugin.xml. */
-    public static final String PLUGIN_VERSION = "4.5.1";
+    public static final String PLUGIN_VERSION = "4.5.2";
 
     private BackgroundGeolocationFacade facade;
 

package/android/common/src/main/java/com/marianhello/bgloc/BootCompletedReceiver.java

@@ -34,6 +34,20 @@ public class BootCompletedReceiver extends BroadcastReceiver {
     @Override
      public void onReceive(Context context, Intent intent) {
         String action = intent != null ? intent.getAction() : null;
+
+        // v4.5.2 — hardening: ignore arbitrary broadcasts directed at this
+        // receiver. Without this, any explicit intent (e.g. a malicious app
+        // targeting our package) could trigger the service auto-start path.
+        // Accept only the canonical boot/package-replaced actions plus the
+        // OEM-specific quick-boot variants used by HTC and Samsung.
+        if (!Intent.ACTION_BOOT_COMPLETED.equals(action)
+                && !"android.intent.action.QUICKBOOT_POWERON".equals(action)
+                && !"com.htc.intent.action.QUICKBOOT_POWERON".equals(action)
+                && !Intent.ACTION_MY_PACKAGE_REPLACED.equals(action)) {
+            Log.w(TAG, "Ignoring unsupported broadcast: " + action);
+            return;
+        }
+
         Log.d(TAG, "Received boot/replace broadcast: " + action);
         ConfigurationDAO dao = DAOFactory.createConfigurationDAO(context);
         Config config = null;