@josuelmm/cordova-background-geolocation 4.2.2 → 4.5.1

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

@@ -188,12 +188,22 @@ public class BatchManager {
         }
 
         private void writeValue(Object value) throws IOException {
-            if (value instanceof String ) {
+            if (value == null || value == JSONObject.NULL) {
+                writer.nullValue();
+            } else if (value instanceof String ) {
                 writer.value((String) value);
             } else if (value instanceof Map) {
                 writeMap((Map) value);
             } else if (value instanceof List) {
                 writeList((List) value);
+            // v4.5.1 — handle JSONArray / JSONObject so that placeholders that resolve to
+            // structured data (@events → JSONArray of events) are written as real JSON arrays /
+            // objects, not as escaped strings. Without this, a fix coming out of the sync queue
+            // serialised "events" as "[{\"type\":\"hardBrake\"}]" literal.
+            } else if (value instanceof org.json.JSONArray) {
+                writeJsonArray((org.json.JSONArray) value);
+            } else if (value instanceof org.json.JSONObject) {
+                writeJsonObject((org.json.JSONObject) value);
             } else if (Integer.class.isInstance(value)) {
                 writer.value((Integer) value);
             } else if (Double.class.isInstance(value)) {
@@ -204,13 +214,44 @@ public class BatchManager {
                 writer.value((Long) value);
             } else if (Boolean.class.isInstance(value)) {
                 writer.value((Boolean) value);
-            } else if (value == JSONObject.NULL) {
-                writer.nullValue();
             } else {
                 writer.value(String.valueOf(value));
             }
         }
 
+        private void writeJsonArray(org.json.JSONArray arr) throws IOException {
+            writer.beginArray();
+            for (int i = 0; i < arr.length(); i++) {
+                Object v = arr.opt(i);
+                writeValue(v == null ? JSONObject.NULL : v);
+            }
+            writer.endArray();
+        }
+
+        private void writeJsonObject(org.json.JSONObject obj) throws IOException {
+            writer.beginObject();
+            Iterator<String> keys = obj.keys();
+            while (keys.hasNext()) {
+                String k = keys.next();
+                writer.name(k);
+                writeValue(obj.opt(k));
+            }
+            writer.endObject();
+        }
+
+        /** v4.5.1 — resolve a template string. If it is a placeholder ("@foo") and the location
+         *  has no value, return JSONObject.NULL so the writer emits `null` instead of the literal
+         *  "@foo" string. */
+        private Object resolveTemplateValue(Object value) {
+            if (value instanceof String) {
+                String s = (String) value;
+                Object resolved = location.getValueForKey(s);
+                if (resolved != null) return resolved;
+                if (s.startsWith("@")) return JSONObject.NULL;
+            }
+            return value;
+        }
+
         public void writeMap(Map values) throws IOException {
             writer.beginObject();
             Iterator<?> it = values.entrySet().iterator();
@@ -218,12 +259,8 @@ public class BatchManager {
                 Map.Entry<String, Object> pair = (Map.Entry) it.next();
                 String key = pair.getKey();
                 Object value = pair.getValue();
-                Object locationValue = null;
-                if (value instanceof String) {
-                    locationValue = location.getValueForKey((String)value);
-                }
                 writer.name(key);
-                writeValue(locationValue != null ? locationValue : value);
+                writeValue(resolveTemplateValue(value));
             }
             writer.endObject();
         }
@@ -233,11 +270,7 @@ public class BatchManager {
             Iterator<?> it = values.iterator();
             while (it.hasNext()) {
                 Object value = it.next();
-                Object locationValue = null;
-                if (value instanceof  String) {
-                    locationValue = location.getValueForKey((String) value);
-                }
-                writeValue(locationValue != null ? locationValue : value);
+                writeValue(resolveTemplateValue(value));
             }
             writer.endArray();
         }

package/ios/CDVBackgroundGeolocation/CDVBackgroundGeolocation.m

@@ -135,6 +135,28 @@ static NSString * const TAG = @"CDVBackgroundGeolocation";
                                 callbackId:command.callbackId];
 }
 
+// v4.5: runtime permission helpers — paridad de API con Android. iOS no expone gates
+// separados para background location / activity recognition / notifications, así que
+// resolvemos siempre con notRequired:YES.
+- (void) requestBackgroundLocationPermission:(CDVInvokedUrlCommand *)command
+{
+    [self sendNotRequiredPermissionResult:command];
+}
+- (void) requestActivityRecognitionPermission:(CDVInvokedUrlCommand *)command
+{
+    [self sendNotRequiredPermissionResult:command];
+}
+- (void) requestNotificationPermission:(CDVInvokedUrlCommand *)command
+{
+    [self sendNotRequiredPermissionResult:command];
+}
+- (void) sendNotRequiredPermissionResult:(CDVInvokedUrlCommand *)command
+{
+    NSDictionary *r = @{ @"granted": @YES, @"notRequired": @YES };
+    [self.commandDelegate sendPluginResult:[CDVPluginResult resultWithStatus:CDVCommandStatus_OK messageAsDictionary:r]
+                                callbackId:command.callbackId];
+}
+
 // v4.1 GPS-derived sensor-like events
 - (void) sendDrivingEventN:(NSString *)name note:(NSNotification *)note
 {
@@ -513,7 +535,7 @@ static NSString * const TAG = @"CDVBackgroundGeolocation";
 - (void) getPluginVersion:(CDVInvokedUrlCommand*)command
 {
     NSLog(@"%@ #%@", TAG, @"getPluginVersion");
-    NSString *version = @"4.2.2"; // keep in sync with plugin.xml and Android PLUGIN_VERSION
+    NSString *version = @"4.5.1"; // keep in sync with plugin.xml and Android PLUGIN_VERSION
     CDVPluginResult *result = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK messageAsString:version];
     [self.commandDelegate sendPluginResult:result callbackId:command.callbackId];
 }

package/ios/common/BackgroundGeolocation/MAURBackgroundGeolocationFacade.m

@@ -104,6 +104,8 @@ NSString * const MAURPhoneUsageWhileDrivingNotification = @"MAURPhoneUsageWhileD
     NSTimeInterval drLastHardBrakeAt, drLastRapidAccelAt, drLastSharpTurnAt, drLastCrashAt;
     // v4.2 sensor fusion
     MAURSensorFusionDetector *sensorFusion;
+    // v4.3 — events buffered when no simultaneous fix is available; drained onto next location.
+    NSMutableArray *pendingDrivingEvents;
 }
 
 
@@ -132,12 +134,27 @@ NSString * const MAURPhoneUsageWhileDrivingNotification = @"MAURPhoneUsageWhileD
     
     postLocationTask = [[MAURPostLocationTask alloc] init];
     postLocationTask.delegate = self;
-    
+
     localNotification = [[UILocalNotification alloc] init];
     localNotification.timeZone = [NSTimeZone defaultTimeZone];
-    
+
     isStarted = NO;
-    
+    pendingDrivingEvents = [[NSMutableArray alloc] init];
+
+    // v4.5.1 — wire pending events + battery snapshot into the post task so they run AFTER
+    // any locationTransform that may produce a new instance / return nil. The previous flow
+    // (flush BEFORE add:) lost buffered events whenever the transform returned nil.
+    postLocationTask.pendingDrivingEventsBuffer = pendingDrivingEvents;
+    __weak typeof(self) weakSelf = self;
+    postLocationTask.attachBatterySnapshot = ^(MAURLocation * _Nonnull loc) {
+        __strong typeof(self) strongSelf = weakSelf;
+        if (strongSelf == nil) return;
+        BOOL includeBat = (strongSelf->_config == nil
+                || strongSelf->_config.includeBattery == nil
+                || [strongSelf->_config.includeBattery boolValue]);
+        if (includeBat) [strongSelf attachBatterySnapshotTo:loc];
+    };
+
     return self;
 }
 
@@ -401,6 +418,7 @@ NSString * const MAURPhoneUsageWhileDrivingNotification = @"MAURPhoneUsageWhileD
 // MAURSensorFusionListener
 - (void) onSensorCrashWithImpactG:(double)impactG location:(MAURLocation *)location
 {
+    [self bufferPendingEvent:@"possibleCrash" extra:@{@"value": @(impactG), @"source": @"sensor"}];
     NSMutableDictionary *userInfo = [NSMutableDictionary dictionary];
     if (location != nil) userInfo[@"location"] = location;
     userInfo[@"value"] = @(impactG);
@@ -411,6 +429,7 @@ NSString * const MAURPhoneUsageWhileDrivingNotification = @"MAURPhoneUsageWhileD
 }
 - (void) onPhoneUsageWhileDriving:(MAURLocation *)location
 {
+    [self bufferPendingEvent:@"phoneUsageWhileDriving" extra:nil];
     NSMutableDictionary *userInfo = [NSMutableDictionary dictionary];
     if (location != nil) userInfo[@"location"] = location;
     [[NSNotificationCenter defaultCenter] postNotificationName:MAURPhoneUsageWhileDrivingNotification
@@ -418,6 +437,77 @@ NSString * const MAURPhoneUsageWhileDrivingNotification = @"MAURPhoneUsageWhileD
                                                       userInfo:userInfo];
 }
 
+// v4.3 — driving event helpers
+- (void) attachDrivingEvent:(NSString *)type to:(MAURLocation *)loc extra:(NSDictionary *)extra
+{
+    if (loc == nil || type == nil) return;
+    NSMutableDictionary *ev = [NSMutableDictionary dictionary];
+    ev[@"type"] = type;
+    ev[@"time"] = @((long long)([[NSDate date] timeIntervalSince1970] * 1000.0));
+    if (extra != nil) [ev addEntriesFromDictionary:extra];
+    if (loc.drivingEvents == nil) loc.drivingEvents = [NSMutableArray array];
+    [loc.drivingEvents addObject:ev];
+}
+
+// v4.4.1 — pending driving events: cap + TTL.
+static NSInteger      const kPendingDrivingEventsMax     = 20;
+static NSTimeInterval const kPendingDrivingEventsTTLMs   = 60000.0;
+
+- (void) bufferPendingEvent:(NSString *)type extra:(NSDictionary *)extra
+{
+    if (type == nil) return;
+    NSMutableDictionary *ev = [NSMutableDictionary dictionary];
+    ev[@"type"] = type;
+    ev[@"time"] = @((long long)([[NSDate date] timeIntervalSince1970] * 1000.0));
+    if (extra != nil) [ev addEntriesFromDictionary:extra];
+    @synchronized (pendingDrivingEvents) {
+        while ((NSInteger)[pendingDrivingEvents count] >= kPendingDrivingEventsMax) {
+            [pendingDrivingEvents removeObjectAtIndex:0];
+        }
+        [pendingDrivingEvents addObject:ev];
+    }
+}
+
+- (void) flushPendingDrivingEventsTo:(MAURLocation *)loc
+{
+    if (loc == nil) return;
+    NSTimeInterval nowMs = [[NSDate date] timeIntervalSince1970] * 1000.0;
+    @synchronized (pendingDrivingEvents) {
+        if ([pendingDrivingEvents count] == 0) return;
+        if (loc.drivingEvents == nil) loc.drivingEvents = [NSMutableArray array];
+        for (NSDictionary *ev in pendingDrivingEvents) {
+            NSNumber *t = ev[@"time"];
+            NSTimeInterval evMs = t != nil ? [t doubleValue] : nowMs;
+            if (nowMs - evMs <= kPendingDrivingEventsTTLMs) {
+                [loc.drivingEvents addObject:ev];
+            }
+        }
+        [pendingDrivingEvents removeAllObjects];
+    }
+}
+
+// v4.4 — read device battery via UIDevice. Calling main thread; safe from any thread.
+- (void) attachBatterySnapshotTo:(MAURLocation *)loc
+{
+    if (loc == nil) return;
+    void (^read)(void) = ^{
+        UIDevice *device = [UIDevice currentDevice];
+        if (!device.batteryMonitoringEnabled) device.batteryMonitoringEnabled = YES;
+        float lvl = device.batteryLevel; // 0.0 - 1.0, or -1 if unknown
+        if (lvl >= 0) {
+            loc.batteryLevel = @((int) round(lvl * 100.0));
+        }
+        UIDeviceBatteryState state = device.batteryState;
+        BOOL charging = (state == UIDeviceBatteryStateCharging || state == UIDeviceBatteryStateFull);
+        loc.isCharging = @(charging);
+    };
+    if ([NSThread isMainThread]) {
+        read();
+    } else {
+        dispatch_sync(dispatch_get_main_queue(), read);
+    }
+}
+
 - (void) drivingDetectorFeed:(MAURLocation *)loc
 {
     if (loc == nil || _config == nil) return;
@@ -446,6 +536,7 @@ NSString * const MAURPhoneUsageWhileDrivingNotification = @"MAURPhoneUsageWhileD
     NSString *provider = loc.provider;
     if (provider != nil && ![provider isEqualToString:drLastProvider]) {
         drLastProvider = provider;
+        [self attachDrivingEvent:@"providerChange" to:loc extra:@{@"provider": provider}];
         [[NSNotificationCenter defaultCenter] postNotificationName:MAURProviderChangeNotification
                                                             object:self
                                                           userInfo:@{@"provider": provider}];
@@ -465,6 +556,7 @@ NSString * const MAURPhoneUsageWhileDrivingNotification = @"MAURPhoneUsageWhileD
         drBelowMovingSince = 0;
         if (!drIsMoving) {
             drIsMoving = YES;
+            [self attachDrivingEvent:@"moving" to:loc extra:nil];
             [[NSNotificationCenter defaultCenter] postNotificationName:MAURMovingNotification
                                                                 object:self
                                                               userInfo:@{@"location": loc}];
@@ -476,6 +568,7 @@ NSString * const MAURPhoneUsageWhileDrivingNotification = @"MAURPhoneUsageWhileD
                     drTripActive = YES;
                     drTripStartedAt = now;
                     drTripDistanceMeters = 0;
+                    [self attachDrivingEvent:@"tripStart" to:loc extra:nil];
                     [[NSNotificationCenter defaultCenter] postNotificationName:MAURTripStartNotification
                                                                         object:self
                                                                       userInfo:@{@"location": loc}];
@@ -490,6 +583,7 @@ NSString * const MAURPhoneUsageWhileDrivingNotification = @"MAURPhoneUsageWhileD
         if (drBelowMovingSince == 0) drBelowMovingSince = now;
         if (drIsMoving && (now - drBelowMovingSince) >= stoppedDuration) {
             drIsMoving = NO;
+            [self attachDrivingEvent:@"stopped" to:loc extra:nil];
             [[NSNotificationCenter defaultCenter] postNotificationName:MAURStoppedNotification
                                                                 object:self
                                                               userInfo:@{@"location": loc}];
@@ -497,6 +591,7 @@ NSString * const MAURPhoneUsageWhileDrivingNotification = @"MAURPhoneUsageWhileD
                 NSTimeInterval durMs = (now - drTripStartedAt) * 1000.0;
                 double dist = drTripDistanceMeters;
                 drTripActive = NO;
+                [self attachDrivingEvent:@"tripEnd" to:loc extra:@{@"distance": @(dist), @"durationMs": @((long long)durMs)}];
                 [[NSNotificationCenter defaultCenter] postNotificationName:MAURTripEndNotification
                                                                     object:self
                                                                   userInfo:@{
@@ -514,6 +609,7 @@ NSString * const MAURPhoneUsageWhileDrivingNotification = @"MAURPhoneUsageWhileD
         if (kmh > speedLimit) {
             if (!drWasSpeeding) {
                 drWasSpeeding = YES;
+                [self attachDrivingEvent:@"speeding" to:loc extra:@{@"speedKmh": @(kmh), @"limitKmh": @(speedLimit)}];
                 [[NSNotificationCenter defaultCenter] postNotificationName:MAURSpeedingNotification
                                                                     object:self
                                                                   userInfo:@{
@@ -546,12 +642,14 @@ NSString * const MAURPhoneUsageWhileDrivingNotification = @"MAURPhoneUsageWhileD
             double accel = dv / dt;
             if (hardBrakeMps2 > 0 && accel <= -hardBrakeMps2 && (now - drLastHardBrakeAt) >= kCooldown) {
                 drLastHardBrakeAt = now;
+                [self attachDrivingEvent:@"hardBrake" to:loc extra:@{@"value": @(accel)}];
                 [[NSNotificationCenter defaultCenter] postNotificationName:MAURHardBrakeNotification
                                                                     object:self
                                                                   userInfo:@{@"location": loc, @"value": @(accel)}];
             }
             if (rapidAccelMps2 > 0 && accel >= rapidAccelMps2 && (now - drLastRapidAccelAt) >= kCooldown) {
                 drLastRapidAccelAt = now;
+                [self attachDrivingEvent:@"rapidAcceleration" to:loc extra:@{@"value": @(accel)}];
                 [[NSNotificationCenter defaultCenter] postNotificationName:MAURRapidAccelerationNotification
                                                                     object:self
                                                                   userInfo:@{@"location": loc, @"value": @(accel)}];
@@ -563,6 +661,7 @@ NSString * const MAURPhoneUsageWhileDrivingNotification = @"MAURPhoneUsageWhileD
                     && drPrevSpeed * 3.6 >= crashImpactKmh
                     && (now - drLastCrashAt) >= kCooldown) {
                     drLastCrashAt = now;
+                    [self attachDrivingEvent:@"possibleCrash" to:loc extra:@{@"value": @(dropKmh), @"source": @"gps"}];
                     [[NSNotificationCenter defaultCenter] postNotificationName:MAURPossibleCrashNotification
                                                                         object:self
                                                                       userInfo:@{@"location": loc, @"value": @(dropKmh), @"source": @"gps"}];
@@ -581,6 +680,7 @@ NSString * const MAURPhoneUsageWhileDrivingNotification = @"MAURPhoneUsageWhileD
             double rate = diff / dt;
             if (rate >= sharpTurnDegPerSec && (now - drLastSharpTurnAt) >= kCooldown) {
                 drLastSharpTurnAt = now;
+                [self attachDrivingEvent:@"sharpTurn" to:loc extra:@{@"value": @(rate)}];
                 [[NSNotificationCenter defaultCenter] postNotificationName:MAURSharpTurnNotification
                                                                     object:self
                                                                   userInfo:@{@"location": loc, @"value": @(rate)}];
@@ -917,7 +1017,10 @@ NSString * const MAURPhoneUsageWhileDrivingNotification = @"MAURPhoneUsageWhileD
 {
     DDLogDebug(@"%@ #onStationaryChanged", TAG);
     stationaryLocation = location;
-    
+
+    // v4.5.1 — enrichment moved into MAURPostLocationTask.add: so pending events / battery
+    // land on the post-transform instance (and survive transforms that return new instances).
+
     [postLocationTask add:location];
     
     MAURConfig *config = [self getConfig];
@@ -946,10 +1049,13 @@ NSString * const MAURPhoneUsageWhileDrivingNotification = @"MAURPhoneUsageWhileD
     stationaryLocation = nil;
     lastReceivedLocation = location; // v3.5 Phase 4: cached for heartbeat payload
 
-    // v4.0 Phase 6: feed driver-insights state machine.
+    // v4.0 Phase 6: feed driver-insights state machine. Listener may attach events to `location`.
     [self drivingDetectorFeed:location];
     // v4.2 Phase 8: keep sensor pipeline aware of the latest fix.
     sensorFusion.lastLocation = location;
+    // v4.5.1 — pending events drain + battery snapshot moved into MAURPostLocationTask.add:
+    // so they run AFTER any user-supplied locationTransform. The previous order lost them
+    // whenever the transform returned nil.
 
     [postLocationTask add:location];
     

package/ios/common/BackgroundGeolocation/MAURBackgroundSync.m

@@ -117,6 +117,10 @@ NSString * const MAURBackgroundSyncDidProgressNotification = @"MAURBackgroundSyn
 
     // Stash count so didCompleteWithError can report it as syncSuccess payload.
     objc_setAssociatedObject(task, "locationsSent", @([jsonArray count]), OBJC_ASSOCIATION_RETAIN_NONATOMIC);
+    // v4.5.1: capture cutoff timestamp NOW so on success we delete only the rows that existed
+    // before the upload started. Locations persisted DURING the upload are preserved.
+    objc_setAssociatedObject(task, "uploadCutoff",
+        @([[NSDate date] timeIntervalSince1970]), OBJC_ASSOCIATION_RETAIN_NONATOMIC);
 
     [task resume];
 
@@ -216,6 +220,10 @@ totalBytesExpectedToSend:(int64_t)totalBytesExpectedToSend
 
     dispatch_async(dispatch_get_main_queue(), ^{
         if (error != nil) {
+            // v4.5.1 — restore SyncPending → PostPending so the failed locations get retried
+            // on the next sync window. Without this, a single network drop loses everything.
+            NSError *restErr = nil;
+            [[MAURSQLiteLocationDAO sharedInstance] restoreFailedSyncLocations:&restErr];
             NSString *msg = error.localizedDescription ?: @"";
             if (_delegate && [_delegate respondsToSelector:@selector(backgroundSyncFailed:httpStatus:message:)]) {
                 [_delegate backgroundSyncFailed:self httpStatus:0 message:msg];
@@ -225,6 +233,9 @@ totalBytesExpectedToSend:(int64_t)totalBytesExpectedToSend
                               object:self
                             userInfo:@{@"httpStatus": @0, @"message": msg}];
         } else if (!isStatusOkay) {
+            // v4.5.1 — server-side failure (5xx, 4xx other than 285/401): also restore the rows.
+            NSError *restErr = nil;
+            [[MAURSQLiteLocationDAO sharedInstance] restoreFailedSyncLocations:&restErr];
             NSString *msg = [NSString stringWithFormat:@"HTTP %ld", (long)statusCode];
             if (_delegate && [_delegate respondsToSelector:@selector(backgroundSyncFailed:httpStatus:message:)]) {
                 [_delegate backgroundSyncFailed:self httpStatus:statusCode message:msg];
@@ -234,6 +245,15 @@ totalBytesExpectedToSend:(int64_t)totalBytesExpectedToSend
                               object:self
                             userInfo:@{@"httpStatus": @(statusCode), @"message": msg}];
         } else {
+            // v4.5.1: drop SYNC_PENDING locations whose recorded_at is <= the captured upload-start
+            // cutoff. This preserves any new locations persisted DURING the upload (race window).
+            NSNumber *cutoffNum = objc_getAssociatedObject(task, "uploadCutoff");
+            NSTimeInterval cutoff = cutoffNum != nil ? [cutoffNum doubleValue] : [[NSDate date] timeIntervalSince1970];
+            NSError *delErr = nil;
+            BOOL deleted = [[MAURSQLiteLocationDAO sharedInstance] deleteSyncedLocationsBefore:cutoff error:&delErr];
+            if (!deleted) {
+                NSLog(@"deleteSyncedLocationsBefore after success failed: %@", delErr.localizedDescription ?: @"unknown");
+            }
             if (_delegate && [_delegate respondsToSelector:@selector(backgroundSyncSucceeded:locationsSent:)]) {
                 [_delegate backgroundSyncSucceeded:self locationsSent:locationsSent];
             }

package/ios/common/BackgroundGeolocation/MAURConfig.h

@@ -44,6 +44,8 @@ enum {
 @property NSString *mockLocationPolicy;       // allow | flag | drop (default allow)
 // v4.0 Phase 6: driver insights — passed through as a dictionary; the facade reads keys at runtime.
 @property NSDictionary *drivingEvents;
+// v4.4: stamp battery percentage + charging state onto every location (default ON).
+@property NSNumber *includeBattery;
 @property NSNumber *_saveBatteryOnBackground;
 @property NSNumber *maxLocations;
 @property NSNumber *_pauseLocationUpdates;

package/ios/common/BackgroundGeolocation/MAURConfig.m

@@ -12,7 +12,7 @@
 
 @implementation MAURConfig 
 
-@synthesize stationaryRadius, distanceFilter, desiredAccuracy, _debug, activityType, activitiesInterval, _stopOnTerminate, url, syncUrl, syncThreshold, syncEnabled, httpHeaders, httpMethod, syncHttpMethod, httpMode, syncMode, queryParams, _showsBackgroundLocationIndicator, heartbeatInterval, mockLocationPolicy, drivingEvents, _saveBatteryOnBackground, maxLocations, _pauseLocationUpdates, locationProvider, _template;
+@synthesize stationaryRadius, distanceFilter, desiredAccuracy, _debug, activityType, activitiesInterval, _stopOnTerminate, url, syncUrl, syncThreshold, syncEnabled, httpHeaders, httpMethod, syncHttpMethod, httpMode, syncMode, queryParams, _showsBackgroundLocationIndicator, heartbeatInterval, mockLocationPolicy, drivingEvents, includeBattery, _saveBatteryOnBackground, maxLocations, _pauseLocationUpdates, locationProvider, _template;
 
 -(instancetype) initWithDefaults {
     self = [super init];
@@ -117,6 +117,9 @@
     if ([config[@"drivingEvents"] isKindOfClass:[NSDictionary class]]) {
         instance.drivingEvents = config[@"drivingEvents"];
     }
+    if (isNotNull(config[@"includeBattery"])) {
+        instance.includeBattery = config[@"includeBattery"];
+    }
     if (isNotNull(config[@"saveBatteryOnBackground"])) {
         instance._saveBatteryOnBackground = config[@"saveBatteryOnBackground"];
     }
@@ -215,6 +218,9 @@
     if (newConfig.drivingEvents != nil) {
         merger.drivingEvents = newConfig.drivingEvents;
     }
+    if (newConfig.includeBattery != nil) {
+        merger.includeBattery = newConfig.includeBattery;
+    }
     if ([newConfig hasSaveBatteryOnBackground]) {
         merger._saveBatteryOnBackground = newConfig._saveBatteryOnBackground;
     }
@@ -259,6 +265,7 @@
         copy.heartbeatInterval = heartbeatInterval;
         copy.mockLocationPolicy = mockLocationPolicy;
         copy.drivingEvents = drivingEvents;
+        copy.includeBattery = includeBattery;
         copy._saveBatteryOnBackground = _saveBatteryOnBackground;
         copy.maxLocations = maxLocations;
         copy._pauseLocationUpdates = _pauseLocationUpdates;
@@ -512,9 +519,15 @@
              @"altitude": @"@altitude",
              @"latitude": @"@latitude",
              @"longitude": @"@longitude",
-             @"provider": @"provider",
+             @"provider": @"@provider",          // v4.5.1 — was literal "provider" (bug)
              @"locationProvider": @"@locationProvider",
              @"radius": @"@radius",
+             // v4.5.1 — README promete events/battery/isCharging en payload default. Sin esto,
+             // el template default que se usa siempre que la app no configura postTemplate omitía
+             // estos campos al serializar via toResultFromTemplate.
+             @"events": @"@events",
+             @"battery": @"@battery",
+             @"isCharging": @"@isCharging",
              };
 }
 
@@ -576,6 +589,7 @@
     if (self.heartbeatInterval != nil) [dict setObject:self.heartbeatInterval forKey:@"heartbeatInterval"];
     if (self.mockLocationPolicy != nil) [dict setObject:self.mockLocationPolicy forKey:@"mockLocationPolicy"];
     if (self.drivingEvents != nil) [dict setObject:self.drivingEvents forKey:@"drivingEvents"];
+    if (self.includeBattery != nil) [dict setObject:self.includeBattery forKey:@"includeBattery"];
     if ([self hasStationaryRadius]) [dict setObject:self.stationaryRadius forKey:@"stationaryRadius"];
     if ([self hasDistanceFilter]) [dict setObject:self.distanceFilter forKey:@"distanceFilter"];
     if ([self hasDesiredAccuracy]) [dict setObject:self.desiredAccuracy forKey:@"desiredAccuracy"];

package/ios/common/BackgroundGeolocation/MAURConfigurationContract.h

@@ -40,6 +40,9 @@
 #define CC_COLUMN_NAME_PAUSE_LOCATION_UPDATES "pause_updates"
 #define CC_COLUMN_NAME_TEMPLATE               "template"
 #define CC_COLUMN_NAME_LAST_UPDATED_AT        "updated_at"
+// v4.5: full Config JSON blob — paridad con Android. Storage of post-3.2 keys without
+// new per-field columns (httpMethod, queryParams, drivingEvents, includeBattery, ...).
+#define CC_COLUMN_NAME_CONFIG_JSON            "config_json"
 
 @interface MAURConfigurationContract : NSObject
 

package/ios/common/BackgroundGeolocation/MAURConfigurationContract.m

@@ -43,7 +43,9 @@
         @{ @"name": @CC_COLUMN_NAME_MAX_LOCATIONS, @"type": [SQLColumnType sqlColumnWithType: kInteger]},
         @{ @"name": @CC_COLUMN_NAME_PAUSE_LOCATION_UPDATES, @"type": [SQLColumnType sqlColumnWithType: kInteger]},
         @{ @"name": @CC_COLUMN_NAME_TEMPLATE, @"type": [SQLColumnType sqlColumnWithType: kText]},
-        @{ @"name": @CC_COLUMN_NAME_LAST_UPDATED_AT, @"type": [SQLColumnType sqlColumnWithType: kInteger]}        
+        @{ @"name": @CC_COLUMN_NAME_LAST_UPDATED_AT, @"type": [SQLColumnType sqlColumnWithType: kInteger]},
+        // v4.5: full Config JSON blob
+        @{ @"name": @CC_COLUMN_NAME_CONFIG_JSON, @"type": [SQLColumnType sqlColumnWithType: kText]}
     ];
     
     return [MAURSQLiteHelper createTableSqlStatement:@CC_TABLE_NAME columns:columns];

package/ios/common/BackgroundGeolocation/MAURGeolocationOpenHelper.m

@@ -15,7 +15,9 @@
 @implementation MAURGeolocationOpenHelper
 
 static NSString *const kDatabaseName = @"cordova_bg_geolocation.db";
-static NSInteger const kDatabaseVersion = 5;
+// v4.5.0: bumped to 7 to add events_json + battery_level + is_charging on locations,
+// and config_json on configuration (paridad con Android v22).
+static NSInteger const kDatabaseVersion = 7;
 
 - (instancetype)init
 {
@@ -94,6 +96,18 @@ static NSInteger const kDatabaseVersion = 5;
                 [MAURSessionLocationContract createTableSQL],
                 [NSString stringWithFormat:@"CREATE INDEX session_recorded_at_idx ON %@ (%@)", @LSC_TABLE_NAME, @LSC_COLUMN_NAME_RECORDED_AT]
             ]];
+        case 5:
+            // v4.5.0: persist driving events / battery / charging on locations.
+            [sql addObjectsFromArray: @[
+                @"ALTER TABLE " @LC_TABLE_NAME @" ADD COLUMN " @LC_COLUMN_NAME_EVENTS_JSON @" TEXT",
+                @"ALTER TABLE " @LC_TABLE_NAME @" ADD COLUMN " @LC_COLUMN_NAME_BATTERY_LEVEL @" INTEGER",
+                @"ALTER TABLE " @LC_TABLE_NAME @" ADD COLUMN " @LC_COLUMN_NAME_IS_CHARGING @" INTEGER"
+            ]];
+        case 6:
+            // v4.5.0: full config persisted as JSON blob (paridad con Android config_json).
+            [sql addObjectsFromArray: @[
+                [NSString stringWithFormat:@"ALTER TABLE %s ADD COLUMN %s TEXT", CC_TABLE_NAME, CC_COLUMN_NAME_CONFIG_JSON]
+            ]];
             break; // break only for previous db version (cascade statements)
         default:
             return;

package/ios/common/BackgroundGeolocation/MAURLocation.h

@@ -39,6 +39,18 @@ typedef NS_ENUM(NSInteger, MAURLocationStatus) {
 @property (nonatomic, retain) NSDate *recordedAt;
 /** True if location was simulated by software (e.g. Simulator). iOS 15+. */
 @property (nonatomic, retain) NSNumber *simulated;
+/**
+ * v4.3 — Driving events anexados a este fix.
+ * v4.5: persiste en SQLite (events_json TEXT) — sobrevive a la cola de sync.
+ * Cada elemento es un NSDictionary con al menos { "type": NSString, "time": NSNumber }.
+ */
+@property (nonatomic, retain) NSMutableArray *drivingEvents;
+/** v4.4 — Battery percentage (0-100) at the time of this fix.
+ *  v4.5: persisted in SQLite (battery_level INTEGER). */
+@property (nonatomic, retain) NSNumber *batteryLevel;
+/** v4.4 — Whether the device is charging at the time of this fix.
+ *  v4.5: persisted in SQLite (is_charging INTEGER). */
+@property (nonatomic, retain) NSNumber *isCharging;
 
 + (instancetype) fromCLLocation:(CLLocation*)location;
 + (NSTimeInterval) locationAge:(CLLocation*)location;

package/ios/common/BackgroundGeolocation/MAURLocation.m

@@ -20,13 +20,25 @@ enum {
 + (instancetype) map:(MAURLocation*)location;
 @end
 
-@implementation MAURLocationMapper
-MAURLocation* _location;
+// v4.5.1 — _location was previously a file-scope global. With real-time post (background queue)
+// and background sync (NSURLSession queue) running concurrently, the second [+map:] invocation
+// overwrote _location while the first mapper was mid-serialize, producing mixed location fields
+// at the backend. Now per-instance ivar.
+@implementation MAURLocationMapper {
+    MAURLocation *_location;
+}
 
 - (id) mapValue:(id)value
 {
     if ([value isKindOfClass:[NSString class]]) {
         id locationValue = [_location getValueForKey:value];
+        // v4.5.1 — for placeholder keys ("@time", "@events", "@battery", ...), if the location
+        // has no value, return NSNull instead of leaking the literal "@events" string to the
+        // backend. For non-placeholder static strings (e.g. a `deviceId` literal in postTemplate)
+        // keep the previous behaviour and return the string as-is.
+        if ([value hasPrefix:@"@"]) {
+            return locationValue != nil ? locationValue : [NSNull null];
+        }
         return locationValue != nil ? locationValue : value;
     } else if ([value isKindOfClass:[NSDictionary class]]) {
         return [self withDictionary:value];
@@ -63,7 +75,7 @@ MAURLocation* _location;
 + (instancetype) map:(MAURLocation*)location
 {
     MAURLocationMapper *instance = [[MAURLocationMapper alloc] init];
-    _location = location;
+    instance->_location = location;
     return instance;
 }
 @end
@@ -71,7 +83,7 @@ MAURLocation* _location;
 
 @implementation MAURLocation
 
-@synthesize locationId, time, accuracy, altitudeAccuracy, speed, heading, altitude, latitude, longitude, provider, locationProvider, radius, isValid, recordedAt, simulated;
+@synthesize locationId, time, accuracy, altitudeAccuracy, speed, heading, altitude, latitude, longitude, provider, locationProvider, radius, isValid, recordedAt, simulated, drivingEvents, batteryLevel, isCharging;
 
 + (instancetype) fromCLLocation:(CLLocation*)location;
 {
@@ -172,6 +184,11 @@ MAURLocation* _location;
     if (radius != nil) [dict setObject:radius forKey:@"radius"];
     if (recordedAt != nil) [dict setObject:[NSNumber numberWithDouble:([recordedAt timeIntervalSince1970] * 1000)] forKey:@"recordedAt"];
     if (simulated != nil) [dict setObject:simulated forKey:@"simulated"];
+    // v4.3 — driving events anexados a este fix
+    if (drivingEvents != nil && [drivingEvents count] > 0) [dict setObject:drivingEvents forKey:@"events"];
+    // v4.4 — battery snapshot
+    if (batteryLevel != nil) [dict setObject:batteryLevel forKey:@"battery"];
+    if (isCharging != nil)   [dict setObject:isCharging   forKey:@"isCharging"];
 
     return dict;
 }
@@ -227,6 +244,13 @@ MAURLocation* _location;
     if ([key isEqualToString:@"@simulated"]) {
         return simulated;
     }
+    // v4.3 — driving events array (nil when no events on this fix; mapper drops nil keys).
+    if ([key isEqualToString:@"@events"]) {
+        return (drivingEvents != nil && [drivingEvents count] > 0) ? drivingEvents : nil;
+    }
+    // v4.4 — battery snapshot
+    if ([key isEqualToString:@"@battery"])    return batteryLevel;
+    if ([key isEqualToString:@"@isCharging"]) return isCharging;
 
     return nil;
 }
@@ -355,6 +379,11 @@ MAURLocation* _location;
         copy.radius = radius;
         copy.isValid = isValid;
         copy.simulated = simulated;
+        // v4.3: copy driving events array reference (transient; mutating one affects the other,
+        // but in practice the original is discarded right after the copy is posted).
+        copy.drivingEvents = drivingEvents != nil ? [drivingEvents mutableCopy] : nil;
+        copy.batteryLevel = batteryLevel;
+        copy.isCharging = isCharging;
     }
 
     return copy;

package/ios/common/BackgroundGeolocation/MAURLocationContract.h

@@ -23,6 +23,10 @@
 #define LC_COLUMN_NAME_LOCATION_PROVIDER   "service_provider"
 #define LC_COLUMN_NAME_STATUS              "valid"
 #define LC_COLUMN_NAME_RECORDED_AT         "recorded_at"
+// v4.5 — survive sync queue
+#define LC_COLUMN_NAME_EVENTS_JSON         "events_json"
+#define LC_COLUMN_NAME_BATTERY_LEVEL       "battery_level"
+#define LC_COLUMN_NAME_IS_CHARGING         "is_charging"
 
 @interface MAURLocationContract : NSObject