@josuelmm/cordova-background-geolocation 3.2.0 → 4.2.2

package/android/common/src/main/java/com/marianhello/bgloc/service/LocationServiceImpl.java

@@ -113,6 +113,29 @@ public class LocationServiceImpl extends Service implements ProviderDelegate, Lo
 
     public static final int MSG_ON_HTTP_AUTHORIZATION = 107;
 
+    /** v3.5 Phase 4: sync queue events. */
+    public static final int MSG_ON_SYNC_START = 108;
+    public static final int MSG_ON_SYNC_SUCCESS = 109;
+    public static final int MSG_ON_SYNC_ERROR = 110;
+    public static final int MSG_ON_SYNC_PROGRESS = 111;
+    public static final int MSG_ON_HEARTBEAT = 112;
+    /** v4.0 Phase 6 — driver insight events. */
+    public static final int MSG_ON_TRIP_START      = 113;
+    public static final int MSG_ON_TRIP_END        = 114;
+    public static final int MSG_ON_MOVING          = 115;
+    public static final int MSG_ON_STOPPED         = 116;
+    public static final int MSG_ON_SPEEDING        = 117;
+    public static final int MSG_ON_PROVIDER_CHANGE = 118;
+    public static final int MSG_ON_SOS             = 119;
+    /** v4.1 — sensor-like GPS-derived driving events. */
+    public static final int MSG_ON_HARD_BRAKE          = 120;
+    public static final int MSG_ON_RAPID_ACCELERATION  = 121;
+    public static final int MSG_ON_SHARP_TURN          = 122;
+    public static final int MSG_ON_POSSIBLE_CRASH      = 123;
+    /** v4.2 — sensor-fusion-only events. {@code MSG_ON_POSSIBLE_CRASH} is reused
+     *  by the sensor pipeline; phone-usage is a brand-new event. */
+    public static final int MSG_ON_PHONE_USAGE_WHILE_DRIVING = 124;
+
     /** notification id */
     private static int NOTIFICATION_ID = 1;
 
@@ -141,6 +164,21 @@ public class LocationServiceImpl extends Service implements ProviderDelegate, Lo
 
     /** Last time we received a location (for watchdog). */
     private volatile long mLastLocationTime = 0L;
+    /** v3.5 Phase 4: latest received location, used as heartbeat payload. */
+    private volatile BackgroundLocation mLastReceivedLocation;
+    /** v4.0 Phase 6: static accessor for {@link com.marianhello.bgloc.BackgroundGeolocationFacade#triggerSOS}. */
+    private static volatile BackgroundLocation sLastReceivedLocation;
+    public static BackgroundLocation getLastReceivedLocation() { return sLastReceivedLocation; }
+    /** v3.5 Phase 4: heartbeat scheduler. */
+    private java.util.concurrent.ScheduledExecutorService mHeartbeatExecutor;
+    private java.util.concurrent.ScheduledFuture<?> mHeartbeatTask;
+
+    /** v4.0 Phase 6: driver-insights detector. Created lazily when config has drivingEvents.enabled. */
+    private com.marianhello.bgloc.driving.DrivingEventsDetector mDrivingDetector;
+    /** v4.2 Phase 8: real sensor-fusion detector. Created when drivingEvents.sensorFusion=true. */
+    private com.marianhello.bgloc.sensor.SensorFusionDetector mSensorFusion;
+    /** v4.2 Phase 8: cached tripActive state so hot-reload can re-inject it. */
+    private volatile boolean mDrivingTripActive = false;
     private static final long WATCHDOG_INTERVAL_MS = 60_000L;
     private final Handler mMainHandler = new Handler(Looper.getMainLooper());
     private final Runnable mWatchdogRunnable = new Runnable() {
@@ -469,6 +507,170 @@ public class LocationServiceImpl extends Service implements ProviderDelegate, Lo
         bundle.putInt("action", MSG_ON_SERVICE_STARTED);
         bundle.putLong("serviceId", mServiceId);
         broadcastMessage(bundle);
+
+        // v3.5 Phase 4: kick off heartbeat scheduler when the service starts.
+        scheduleHeartbeat();
+
+        // v4.0 Phase 6: build driver-insights detector if enabled in config.
+        configureDrivingDetector();
+    }
+
+    /** v4.0 Phase 6: instantiate / reconfigure the GPS-based driver-insights detector. */
+    private void configureDrivingDetector() {
+        if (mConfig == null) return;
+        com.marianhello.bgloc.Config.DrivingEventsOptions opts = mConfig.getDrivingEvents();
+        if (opts == null || !opts.enabled) {
+            if (mDrivingDetector != null) mDrivingDetector.reset();
+            mDrivingDetector = null;
+            return;
+        }
+        com.marianhello.bgloc.driving.DrivingEventsDetector.Config c =
+                new com.marianhello.bgloc.driving.DrivingEventsDetector.Config();
+        c.enabled = true;
+        c.speedLimitKmh     = opts.speedLimitKmh;
+        c.minMovingSpeedMps = opts.minMovingSpeedMps;
+        c.stoppedDurationMs = opts.stoppedDurationMs;
+        c.minTripSpeedMps   = opts.minTripSpeedMps;
+        c.minTripDurationMs = opts.minTripDurationMs;
+
+        mDrivingDetector = new com.marianhello.bgloc.driving.DrivingEventsDetector(
+                new com.marianhello.bgloc.driving.DrivingEventsDetector.Listener() {
+                    @Override public void onMoving(BackgroundLocation l) {
+                        Bundle b = new Bundle();
+                        b.putInt("action", MSG_ON_MOVING);
+                        if (l != null) b.putParcelable("payload", l);
+                        broadcastMessage(b);
+                    }
+                    @Override public void onStopped(BackgroundLocation l) {
+                        Bundle b = new Bundle();
+                        b.putInt("action", MSG_ON_STOPPED);
+                        if (l != null) b.putParcelable("payload", l);
+                        broadcastMessage(b);
+                    }
+                    @Override public void onTripStart(BackgroundLocation l) {
+                        Bundle b = new Bundle();
+                        b.putInt("action", MSG_ON_TRIP_START);
+                        if (l != null) b.putParcelable("payload", l);
+                        broadcastMessage(b);
+                        mDrivingTripActive = true;
+                        if (mSensorFusion != null) mSensorFusion.setTripActive(true);
+                    }
+                    @Override public void onTripEnd(BackgroundLocation l, double distance, long durationMs) {
+                        Bundle b = new Bundle();
+                        b.putInt("action", MSG_ON_TRIP_END);
+                        if (l != null) b.putParcelable("payload", l);
+                        b.putDouble("distance", distance);
+                        b.putLong("durationMs", durationMs);
+                        broadcastMessage(b);
+                        mDrivingTripActive = false;
+                        if (mSensorFusion != null) mSensorFusion.setTripActive(false);
+                    }
+                    @Override public void onSpeeding(BackgroundLocation l, double speedKmh, double limitKmh) {
+                        Bundle b = new Bundle();
+                        b.putInt("action", MSG_ON_SPEEDING);
+                        if (l != null) b.putParcelable("payload", l);
+                        b.putDouble("speedKmh", speedKmh);
+                        b.putDouble("limitKmh", limitKmh);
+                        broadcastMessage(b);
+                    }
+                    @Override public void onProviderChange(String provider) {
+                        Bundle b = new Bundle();
+                        b.putInt("action", MSG_ON_PROVIDER_CHANGE);
+                        b.putString("provider", provider != null ? provider : "");
+                        broadcastMessage(b);
+                    }
+                    @Override public void onHardBrake(BackgroundLocation l, double decelMps2) {
+                        Bundle b = new Bundle();
+                        b.putInt("action", MSG_ON_HARD_BRAKE);
+                        if (l != null) b.putParcelable("payload", l);
+                        b.putDouble("value", decelMps2);
+                        broadcastMessage(b);
+                    }
+                    @Override public void onRapidAcceleration(BackgroundLocation l, double accelMps2) {
+                        Bundle b = new Bundle();
+                        b.putInt("action", MSG_ON_RAPID_ACCELERATION);
+                        if (l != null) b.putParcelable("payload", l);
+                        b.putDouble("value", accelMps2);
+                        broadcastMessage(b);
+                    }
+                    @Override public void onSharpTurn(BackgroundLocation l, double degPerSec) {
+                        Bundle b = new Bundle();
+                        b.putInt("action", MSG_ON_SHARP_TURN);
+                        if (l != null) b.putParcelable("payload", l);
+                        b.putDouble("value", degPerSec);
+                        broadcastMessage(b);
+                    }
+                    @Override public void onPossibleCrash(BackgroundLocation l, double velocityDropKmh) {
+                        Bundle b = new Bundle();
+                        b.putInt("action", MSG_ON_POSSIBLE_CRASH);
+                        if (l != null) b.putParcelable("payload", l);
+                        b.putDouble("value", velocityDropKmh);
+                        b.putString("source", "gps");
+                        broadcastMessage(b);
+                    }
+                });
+        // Pass v4.1 thresholds from app config (with defaults from c).
+        com.marianhello.bgloc.Config.DrivingEventsOptions optsRef = mConfig.getDrivingEvents();
+        if (optsRef != null) {
+            c.hardBrakeMps2     = optsRef.hardBrakeMps2;
+            c.rapidAccelMps2    = optsRef.rapidAccelMps2;
+            c.sharpTurnDegPerSec = optsRef.sharpTurnDegPerSec;
+            c.crashImpactKmh    = optsRef.crashImpactKmh;
+            c.crashWindowMs     = optsRef.crashWindowMs;
+        }
+        mDrivingDetector.setConfig(c);
+        configureSensorFusion();
+    }
+
+    /** v4.2 Phase 8: instantiate / reconfigure the real sensor-fusion detector. */
+    private void configureSensorFusion() {
+        if (mConfig == null) {
+            if (mSensorFusion != null) { mSensorFusion.stop(); mSensorFusion = null; }
+            return;
+        }
+        com.marianhello.bgloc.Config.DrivingEventsOptions opts = mConfig.getDrivingEvents();
+        boolean wantSF = opts != null && opts.enabled && opts.sensorFusion;
+        if (!wantSF) {
+            if (mSensorFusion != null) { mSensorFusion.stop(); mSensorFusion = null; }
+            return;
+        }
+
+        com.marianhello.bgloc.sensor.SensorFusionDetector.Listener l =
+                new com.marianhello.bgloc.sensor.SensorFusionDetector.Listener() {
+                    @Override public void onSensorCrash(BackgroundLocation lastLocation, double impactG) {
+                        Bundle b = new Bundle();
+                        b.putInt("action", MSG_ON_POSSIBLE_CRASH);
+                        if (lastLocation != null) b.putParcelable("payload", lastLocation);
+                        b.putDouble("value", impactG);
+                        b.putString("source", "sensor");
+                        broadcastMessage(b);
+                    }
+                    @Override public void onPhoneUsageWhileDriving(BackgroundLocation lastLocation) {
+                        Bundle b = new Bundle();
+                        b.putInt("action", MSG_ON_PHONE_USAGE_WHILE_DRIVING);
+                        if (lastLocation != null) b.putParcelable("payload", lastLocation);
+                        broadcastMessage(b);
+                    }
+                };
+
+        if (mSensorFusion == null) {
+            mSensorFusion = new com.marianhello.bgloc.sensor.SensorFusionDetector(this, l);
+        }
+        com.marianhello.bgloc.sensor.SensorFusionDetector.Config sfc =
+                new com.marianhello.bgloc.sensor.SensorFusionDetector.Config();
+        sfc.enabled = true;
+        sfc.crashImpactG          = opts.crashImpactG;
+        sfc.crashCooldownMs       = opts.sensorCrashCooldownMs;
+        sfc.phoneUsageWindowMs    = opts.phoneUsageWindowMs;
+        sfc.phoneUsageCooldownMs  = opts.phoneUsageCooldownMs;
+        mSensorFusion.setConfig(sfc);
+        // v4.2 hot-reload: re-inject current tripActive state and last location so the
+        // sensor pipeline starts in the right mode (e.g. config arrives mid-trip).
+        mSensorFusion.setTripActive(mDrivingTripActive);
+        if (mLastReceivedLocation != null) {
+            mSensorFusion.setLastLocation(mLastReceivedLocation);
+        }
+        if (sIsRunning) mSensorFusion.start();
     }
 
     @Override
@@ -503,6 +705,17 @@ public class LocationServiceImpl extends Service implements ProviderDelegate, Lo
         stopForeground(true);
         stopSelf();
 
+        // v3.5 Phase 4: stop heartbeat scheduler.
+        cancelHeartbeat();
+        // v4.0 Phase 6: reset driver-insights state machine.
+        if (mDrivingDetector != null) mDrivingDetector.reset();
+        // v4.2 Phase 8: stop sensor fusion sampling.
+        mDrivingTripActive = false;
+        if (mSensorFusion != null) {
+            mSensorFusion.setTripActive(false);
+            mSensorFusion.stop();
+        }
+
         broadcastMessage(MSG_ON_SERVICE_STOPPED);
         sIsRunning = false;
     }
@@ -516,13 +729,10 @@ public class LocationServiceImpl extends Service implements ProviderDelegate, Lo
                 || checkSelfPermission(Manifest.permission.ACCESS_COARSE_LOCATION) == PackageManager.PERMISSION_GRANTED;
     }
 
-    /** FOREGROUND_SERVICE_TYPE_LOCATION = 4 when compileSdk >= 34. */
-    private static final int FOREGROUND_SERVICE_TYPE_LOCATION = 4;
-
     /**
      * Reads this service's foregroundServiceType from the merged AndroidManifest (API 34+).
      * Uses ComponentInfoFlags.of(0) (not GET_META_DATA) so getServiceInfo returns complete ServiceInfo.
-     * Returns the real value; never invents 0x4. If unknown, returns 0 so callers must not call startForeground.
+     * Returns the real value; never invents a hardcoded type. If unknown, returns 0 so callers must not call startForeground.
      * Requires compileSdk 33+ (ComponentInfoFlags); 34+ for ServiceInfo.foregroundServiceType.
      */
     private int getManifestForegroundServiceType() {
@@ -581,9 +791,14 @@ public class LocationServiceImpl extends Service implements ProviderDelegate, Lo
                 mProvider.onCommand(LocationProvider.CMD_SWITCH_MODE,
                         LocationProvider.FOREGROUND_MODE);
             }
-            // Android 14+ (API 34): type must match the merged manifest. If we get 0, do not start (avoid crash from invented type).
+            // Android 14+ (API 34): type must match the merged manifest. Read it dynamically; if unknown, do not start.
             if (Build.VERSION.SDK_INT >= 34) {
-                super.startForeground(NOTIFICATION_ID, notification, 0x8);
+                int type = getManifestForegroundServiceType();
+                if (type == 0) {
+                    logger.error("Cannot start foreground: manifest foregroundServiceType missing or unreadable");
+                    return;
+                }
+                super.startForeground(NOTIFICATION_ID, notification, type);
             } else {
                 super.startForeground(NOTIFICATION_ID, notification);
             }
@@ -724,10 +939,49 @@ public class LocationServiceImpl extends Service implements ProviderDelegate, Lo
                 } else {
                     mProvider.onConfigure(mConfig);
                 }
+
+                // v4.1: re-evaluate hot-reload features when config changes while service is running.
+                if (sIsRunning) {
+                    Integer prevHb = currentConfig.getHeartbeatInterval();
+                    Integer newHb = mConfig.getHeartbeatInterval();
+                    if (prevHb == null) prevHb = 0;
+                    if (newHb == null) newHb = 0;
+                    if (!prevHb.equals(newHb)) {
+                        scheduleHeartbeat(); // cancels and reschedules with the new interval (or stops if 0)
+                    }
+                    // Driver-insights detector: rebuild if the config dict changed.
+                    Config.DrivingEventsOptions prevDe = currentConfig.getDrivingEvents();
+                    Config.DrivingEventsOptions newDe = mConfig.getDrivingEvents();
+                    if (!equalsDrivingEvents(prevDe, newDe)) {
+                        configureDrivingDetector();
+                    }
+                }
             }
         });
     }
 
+    /** Shallow value equality for DrivingEventsOptions; avoids needless detector rebuilds. */
+    private static boolean equalsDrivingEvents(Config.DrivingEventsOptions a, Config.DrivingEventsOptions b) {
+        if (a == b) return true;
+        if (a == null || b == null) return false;
+        return a.enabled == b.enabled
+                && a.speedLimitKmh == b.speedLimitKmh
+                && a.minMovingSpeedMps == b.minMovingSpeedMps
+                && a.stoppedDurationMs == b.stoppedDurationMs
+                && a.minTripSpeedMps == b.minTripSpeedMps
+                && a.minTripDurationMs == b.minTripDurationMs
+                && a.hardBrakeMps2 == b.hardBrakeMps2
+                && a.rapidAccelMps2 == b.rapidAccelMps2
+                && a.sharpTurnDegPerSec == b.sharpTurnDegPerSec
+                && a.crashImpactKmh == b.crashImpactKmh
+                && a.crashWindowMs == b.crashWindowMs
+                && a.sensorFusion == b.sensorFusion
+                && a.crashImpactG == b.crashImpactG
+                && a.sensorCrashCooldownMs == b.sensorCrashCooldownMs
+                && a.phoneUsageWindowMs == b.phoneUsageWindowMs
+                && a.phoneUsageCooldownMs == b.phoneUsageCooldownMs;
+    }
+
     @Override
     public synchronized void registerHeadlessTask(String taskRunnerClass) {
         logger.debug("Registering headless task");
@@ -769,6 +1023,17 @@ public class LocationServiceImpl extends Service implements ProviderDelegate, Lo
     @Override
     public void onLocation(BackgroundLocation location) {
         mLastLocationTime = System.currentTimeMillis();
+        mLastReceivedLocation = location;
+        sLastReceivedLocation = location;
+
+        // v4.0 Phase 6: feed the driver-insights state machine.
+        if (mDrivingDetector != null) {
+            mDrivingDetector.onLocation(location);
+        }
+        // v4.2 Phase 8: keep sensor pipeline aware of the latest fix.
+        if (mSensorFusion != null) {
+            mSensorFusion.setLastLocation(location);
+        }
         if (Boolean.TRUE.equals(mConfig != null ? mConfig.getShowDistance() : null)) {
             double lat = location.getLatitude();
             double lon = location.getLongitude();
@@ -889,6 +1154,40 @@ public class LocationServiceImpl extends Service implements ProviderDelegate, Lo
         LocalBroadcastManager.getInstance(getApplicationContext()).sendBroadcast(intent);
     }
 
+    /** v3.5 Phase 4: schedule periodic heartbeat broadcasts using {@link Config#getHeartbeatInterval()}. */
+    private void scheduleHeartbeat() {
+        cancelHeartbeat();
+        if (mConfig == null) return;
+        Integer interval = mConfig.getHeartbeatInterval();
+        if (interval == null || interval <= 0) return;
+        logger.debug("Scheduling heartbeat every {} ms", interval);
+        mHeartbeatExecutor = java.util.concurrent.Executors.newSingleThreadScheduledExecutor();
+        mHeartbeatTask = mHeartbeatExecutor.scheduleAtFixedRate(new Runnable() {
+            @Override public void run() {
+                try {
+                    Bundle b = new Bundle();
+                    b.putInt("action", MSG_ON_HEARTBEAT);
+                    BackgroundLocation last = mLastReceivedLocation;
+                    if (last != null) b.putParcelable("payload", last);
+                    broadcastMessage(b);
+                } catch (Throwable t) {
+                    logger.warn("Heartbeat tick failed: {}", t.getMessage());
+                }
+            }
+        }, interval, interval, java.util.concurrent.TimeUnit.MILLISECONDS);
+    }
+
+    private void cancelHeartbeat() {
+        if (mHeartbeatTask != null) {
+            mHeartbeatTask.cancel(false);
+            mHeartbeatTask = null;
+        }
+        if (mHeartbeatExecutor != null) {
+            mHeartbeatExecutor.shutdownNow();
+            mHeartbeatExecutor = null;
+        }
+    }
+
     @Override
     public Intent registerReceiver(BroadcastReceiver receiver, IntentFilter filter) {
         return super.registerReceiver(receiver, filter, null, mServiceHandler, RECEIVER_NOT_EXPORTED);

package/android/common/src/main/java/com/marianhello/bgloc/service/LocationServiceProxy.java

@@ -5,10 +5,12 @@ import android.content.Context;
 import android.content.Intent;
 import android.content.pm.PackageManager;
 import android.os.Build;
+import android.util.Log;
 
 import com.marianhello.bgloc.Config;
 
 public class LocationServiceProxy implements LocationService, LocationServiceInfo {
+    private static final String TAG = LocationServiceProxy.class.getSimpleName();
     private final Context mContext;
     private final LocationServiceIntentBuilder mIntentBuilder;
 
@@ -78,9 +80,19 @@ public class LocationServiceProxy implements LocationService, LocationServiceInf
         Intent intent = mIntentBuilder.setCommand(CommandId.START_FOREGROUND_SERVICE).build();
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
             if (!hasLocationPermission()) {
-                mContext.startService(intent);
-            } else {
+                // Do NOT fall back to startService(): would create a non-foreground service that crashes
+                // on first location update. Caller must request the permission first.
+                Log.w(TAG, "Cannot start foreground service: ACCESS_FINE_LOCATION/COARSE_LOCATION not granted");
+                return;
+            }
+            // Note: ACCESS_BACKGROUND_LOCATION is only required when the service is started from
+            // background (e.g. BootCompletedReceiver). When called from foreground, the OS allows
+            // a location-typed FGS to run with only fine/coarse location and inherit "while-in-use".
+            try {
                 mContext.startForegroundService(intent);
+            } catch (Exception e) {
+                // Android 12+ may throw ForegroundServiceStartNotAllowedException.
+                Log.e(TAG, "startForegroundService blocked: " + e.getClass().getSimpleName() + ": " + e.getMessage(), e);
             }
         } else {
             mContext.startService(intent);

package/android/common/src/main/java/com/marianhello/bgloc/sync/SyncAdapter.java

@@ -140,7 +140,12 @@ public class SyncAdapter extends AbstractThreadedSyncAdapter implements HttpPost
         }
         httpHeaders.put("x-batch-id", String.valueOf(batchStartMillis));
 
-        if (uploadLocations(file, url, httpHeaders)) {
+        // For URL templating in sync mode we can only resolve static queryParams keys; per-location
+        // placeholders (like {lat}) cannot apply to a multi-location batch. If the user wants per-location
+        // URL substitution they should use httpMode="single" + url= ... (real-time) or syncMode="single".
+        String resolvedUrl = com.marianhello.bgloc.http.UrlTemplateResolver.resolve(url, null, config.getQueryParams());
+        String syncMethod = config.getSyncHttpMethod();
+        if (uploadLocations(file, resolvedUrl, httpHeaders, syncMethod)) {
             logger.info("Batch sync successful");
             batchManager.setBatchCompleted(batchStartMillis);
             if (file.delete()) {
@@ -154,7 +159,7 @@ public class SyncAdapter extends AbstractThreadedSyncAdapter implements HttpPost
         }
     }
 
-    private boolean uploadLocations(File file, String url, HashMap httpHeaders) {
+    private boolean uploadLocations(File file, String url, HashMap httpHeaders, String method) {
         NotificationCompat.Builder builder = null;
 
         if (notificationsEnabled) {
@@ -166,8 +171,29 @@ public class SyncAdapter extends AbstractThreadedSyncAdapter implements HttpPost
             notificationManager.notify(NOTIFICATION_ID, builder.build());
         }
 
+        // v3.5 Phase 4: emit syncStart event.
+        Bundle syncStart = new Bundle();
+        syncStart.putInt("action", LocationServiceImpl.MSG_ON_SYNC_START);
+        broadcastMessage(syncStart);
+
+        // Count locations being uploaded (best-effort, API-21+ safe).
+        int locationsAttempted = 0;
+        java.io.FileInputStream fis = null;
         try {
-            int responseCode = HttpPostService.postJSONFile(url, file, httpHeaders, this);
+            fis = new java.io.FileInputStream(file);
+            java.io.ByteArrayOutputStream baos = new java.io.ByteArrayOutputStream();
+            byte[] buf = new byte[4096];
+            int n;
+            while ((n = fis.read(buf)) > 0) baos.write(buf, 0, n);
+            org.json.JSONArray arr = new org.json.JSONArray(new String(baos.toByteArray(), "UTF-8"));
+            locationsAttempted = arr.length();
+        } catch (Throwable ignored) { /* best-effort; emit 0 if we cannot read */
+        } finally {
+            if (fis != null) try { fis.close(); } catch (Exception ignored) {}
+        }
+
+        try {
+            int responseCode = HttpPostService.postJSONFile(url, file, httpHeaders, this, method);
 
             // All 2xx statuses are okay
             boolean isStatusOkay = responseCode >= 200 && responseCode < 300;
@@ -198,6 +224,16 @@ public class SyncAdapter extends AbstractThreadedSyncAdapter implements HttpPost
 
             if (!isStatusOkay) {
                 logger.warn("Batch sync failed: server returned HTTP {} (check server logs or sync URL)", responseCode);
+                Bundle errBundle = new Bundle();
+                errBundle.putInt("action", LocationServiceImpl.MSG_ON_SYNC_ERROR);
+                errBundle.putInt("httpStatus", responseCode);
+                errBundle.putString("message", "HTTP " + responseCode);
+                broadcastMessage(errBundle);
+            } else {
+                Bundle okBundle = new Bundle();
+                okBundle.putInt("action", LocationServiceImpl.MSG_ON_SYNC_SUCCESS);
+                okBundle.putInt("sent", locationsAttempted);
+                broadcastMessage(okBundle);
             }
 
             return isStatusOkay;
@@ -208,6 +244,11 @@ public class SyncAdapter extends AbstractThreadedSyncAdapter implements HttpPost
             if (builder != null) {
                 builder.setContentText(currentSyncConfig.getNotificationSyncFailedText() + ": " + errMsg);
             }
+            Bundle errBundle = new Bundle();
+            errBundle.putInt("action", LocationServiceImpl.MSG_ON_SYNC_ERROR);
+            errBundle.putInt("httpStatus", 0);
+            errBundle.putString("message", errMsg);
+            broadcastMessage(errBundle);
         } finally {
             logger.info("Syncing endAt: {}", System.currentTimeMillis());
 
@@ -244,6 +285,12 @@ public class SyncAdapter extends AbstractThreadedSyncAdapter implements HttpPost
             builder.setProgress(100, progress, false);
             notificationManager.notify(NOTIFICATION_ID, builder.build());
         }
+
+        // v3.5 Phase 4: forward progress percentage to JS via syncProgress event.
+        Bundle progBundle = new Bundle();
+        progBundle.putInt("action", LocationServiceImpl.MSG_ON_SYNC_PROGRESS);
+        progBundle.putInt("progress", progress);
+        broadcastMessage(progBundle);
     }
 
     private void broadcastMessage(Bundle bundle) {

package/android/dependencies.gradle

@@ -8,6 +8,3 @@ dependencies {
     implementation 'com.github.jparkie:promise:1.0.3'
 }
 
-android {
-    useLibrary 'org.apache.http.legacy'
-}

package/angular/background-geolocation-events.ts

@@ -14,4 +14,25 @@ export enum BackgroundGeolocationEvents {
   activity = 'activity',
   stationary = 'stationary',
   location = 'location',
+  // v3.5+
+  heartbeat = 'heartbeat',
+  syncStart = 'syncStart',
+  syncProgress = 'syncProgress',
+  syncSuccess = 'syncSuccess',
+  syncError = 'syncError',
+  // v4.0
+  tripStart = 'tripStart',
+  tripEnd = 'tripEnd',
+  moving = 'moving',
+  stopped = 'stopped',
+  speeding = 'speeding',
+  providerChange = 'providerChange',
+  sos = 'sos',
+  // v4.1
+  hardBrake = 'hardBrake',
+  rapidAcceleration = 'rapidAcceleration',
+  sharpTurn = 'sharpTurn',
+  possibleCrash = 'possibleCrash',
+  // v4.2 sensor fusion
+  phoneUsageWhileDriving = 'phoneUsageWhileDriving',
 }

package/angular/background-geolocation.service.ts

@@ -83,6 +83,69 @@ export class BackgroundGeolocationService {
     return this.ensurePlugin().checkStatus(success, fail);
   }
 
+  /**
+   * Extended diagnostics. Returns permissions, battery optimisation state,
+   * last fix age, pending sync count, OEM info and (on iOS) precise location /
+   * background refresh / low power flags.
+   *
+   * @since 3.5.0
+   */
+  getDiagnostics(
+    success?: (diagnostics: any) => void,
+    fail?: (error: any) => void
+  ): Promise<any> {
+    return this.ensurePlugin().getDiagnostics(success, fail);
+  }
+
+  /** @since 3.6.0 */
+  isIgnoringBatteryOptimizations(
+    success?: (whitelisted: boolean) => void,
+    fail?: (error: any) => void
+  ): Promise<boolean> {
+    return this.ensurePlugin().isIgnoringBatteryOptimizations(success, fail);
+  }
+
+  /** @since 3.6.0 */
+  requestIgnoreBatteryOptimizations(
+    success?: (whitelisted: boolean) => void,
+    fail?: (error: any) => void
+  ): Promise<boolean> {
+    return this.ensurePlugin().requestIgnoreBatteryOptimizations(success, fail);
+  }
+
+  /** @since 3.6.0 */
+  openBatterySettings(
+    success?: () => void,
+    fail?: (error: any) => void
+  ): Promise<void> {
+    return this.ensurePlugin().openBatterySettings(success, fail);
+  }
+
+  /** @since 3.6.0 */
+  openAutoStartSettings(
+    success?: (info: { opened: boolean; manufacturer: string; screen: string }) => void,
+    fail?: (error: any) => void
+  ): Promise<{ opened: boolean; manufacturer: string; screen: string }> {
+    return this.ensurePlugin().openAutoStartSettings(success, fail);
+  }
+
+  /** @since 3.6.0 */
+  getManufacturerHelp(
+    success?: (info: { manufacturer: string; steps: string[] }) => void,
+    fail?: (error: any) => void
+  ): Promise<{ manufacturer: string; steps: string[] }> {
+    return this.ensurePlugin().getManufacturerHelp(success, fail);
+  }
+
+  /** @since 4.0.0 */
+  triggerSOS(
+    payload?: { [key: string]: any },
+    success?: () => void,
+    fail?: (error: any) => void
+  ): Promise<void> {
+    return this.ensurePlugin().triggerSOS(payload, success, fail);
+  }
+
   showAppSettings(): Promise<void> {
     return this.ensurePlugin().showAppSettings();
   }

package/angular/dist/background-geolocation-events.d.ts

@@ -13,5 +13,22 @@ export declare enum BackgroundGeolocationEvents {
     start = "start",
     activity = "activity",
     stationary = "stationary",
-    location = "location"
+    location = "location",
+    heartbeat = "heartbeat",
+    syncStart = "syncStart",
+    syncProgress = "syncProgress",
+    syncSuccess = "syncSuccess",
+    syncError = "syncError",
+    tripStart = "tripStart",
+    tripEnd = "tripEnd",
+    moving = "moving",
+    stopped = "stopped",
+    speeding = "speeding",
+    providerChange = "providerChange",
+    sos = "sos",
+    hardBrake = "hardBrake",
+    rapidAcceleration = "rapidAcceleration",
+    sharpTurn = "sharpTurn",
+    possibleCrash = "possibleCrash",
+    phoneUsageWhileDriving = "phoneUsageWhileDriving"
 }