@josuelmm/cordova-background-geolocation 3.2.0 → 4.2.2

package/ios/common/BackgroundGeolocation/MAURConfig.h

@@ -31,6 +31,19 @@ enum {
 @property NSNumber *syncThreshold;
 @property NSNumber *syncEnabled;
 @property NSMutableDictionary* httpHeaders;
+// v3.3 Phase 2: backend-agnostic HTTP transport
+@property NSString *httpMethod;        // POST | GET | PUT | PATCH (default POST)
+@property NSString *syncHttpMethod;    // POST | GET | PUT | PATCH (default POST)
+@property NSString *httpMode;          // batch | single (default batch)
+@property NSString *syncMode;          // batch | single (default batch)
+@property NSMutableDictionary* queryParams; // static placeholder values for URL templating
+// v3.4 Phase 3: location API modernization
+@property NSNumber *_showsBackgroundLocationIndicator; // iOS 11+: show blue bar when app uses location in background
+// v3.5 Phase 4: diagnostics
+@property NSNumber *heartbeatInterval;        // ms; 0 disables (default)
+@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;
 @property NSNumber *_saveBatteryOnBackground;
 @property NSNumber *maxLocations;
 @property NSNumber *_pauseLocationUpdates;
@@ -57,6 +70,8 @@ enum {
 - (BOOL) syncEnabled;
 - (BOOL) hasHttpHeaders;
 - (BOOL) hasSaveBatteryOnBackground;
+- (BOOL) hasShowsBackgroundLocationIndicator;
+- (BOOL) showsBackgroundLocationIndicator;
 - (BOOL) hasMaxLocations;
 - (BOOL) hasPauseLocationUpdates;
 - (BOOL) hasLocationProvider;

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, _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, _saveBatteryOnBackground, maxLocations, _pauseLocationUpdates, locationProvider, _template;
 
 -(instancetype) initWithDefaults {
     self = [super init];
@@ -34,8 +34,14 @@
     syncEnabled = [NSNumber numberWithBool:YES];
     _pauseLocationUpdates = [NSNumber numberWithBool:NO];
     locationProvider = [NSNumber numberWithInt:DISTANCE_FILTER_PROVIDER];
+    httpMethod = @"POST";
+    syncHttpMethod = @"POST";
+    httpMode = @"batch";
+    syncMode = @"batch";
+    heartbeatInterval = [NSNumber numberWithInt:0];
+    mockLocationPolicy = @"allow";
 //    template =
-    
+
     return self;
 }
 
@@ -58,7 +64,7 @@
     if (isNotNull(config[@"activityType"])) {
         instance.activityType = config[@"activityType"];
     }
-    if (isNull(config[@"activitiesInterval"])) {
+    if (isNotNull(config[@"activitiesInterval"])) {
         instance.activitiesInterval = config[@"activitiesInterval"];
     }
     if (isNotNull(config[@"stopOnTerminate"])) {
@@ -79,6 +85,38 @@
     if (config[@"httpHeaders"] != nil) {
         instance.httpHeaders = config[@"httpHeaders"];
     }
+    // headers (alias of httpHeaders)
+    if (config[@"headers"] != nil) {
+        instance.httpHeaders = config[@"headers"];
+    }
+    // v3.3 Phase 2: HTTP transport
+    if (isNotNull(config[@"httpMethod"])) {
+        instance.httpMethod = [(NSString*)config[@"httpMethod"] uppercaseString];
+    }
+    if (isNotNull(config[@"syncHttpMethod"])) {
+        instance.syncHttpMethod = [(NSString*)config[@"syncHttpMethod"] uppercaseString];
+    }
+    if (isNotNull(config[@"httpMode"])) {
+        instance.httpMode = [(NSString*)config[@"httpMode"] lowercaseString];
+    }
+    if (isNotNull(config[@"syncMode"])) {
+        instance.syncMode = [(NSString*)config[@"syncMode"] lowercaseString];
+    }
+    if (config[@"queryParams"] != nil) {
+        instance.queryParams = config[@"queryParams"];
+    }
+    if (isNotNull(config[@"showsBackgroundLocationIndicator"])) {
+        instance._showsBackgroundLocationIndicator = config[@"showsBackgroundLocationIndicator"];
+    }
+    if (isNotNull(config[@"heartbeatInterval"])) {
+        instance.heartbeatInterval = config[@"heartbeatInterval"];
+    }
+    if (isNotNull(config[@"mockLocationPolicy"])) {
+        instance.mockLocationPolicy = [(NSString*)config[@"mockLocationPolicy"] lowercaseString];
+    }
+    if ([config[@"drivingEvents"] isKindOfClass:[NSDictionary class]]) {
+        instance.drivingEvents = config[@"drivingEvents"];
+    }
     if (isNotNull(config[@"saveBatteryOnBackground"])) {
         instance._saveBatteryOnBackground = config[@"saveBatteryOnBackground"];
     }
@@ -94,6 +132,10 @@
     if (config[@"postTemplate"] != nil) {
         instance._template = config[@"postTemplate"];
     }
+    // bodyTemplate (alias of postTemplate)
+    if (config[@"bodyTemplate"] != nil) {
+        instance._template = config[@"bodyTemplate"];
+    }
 
     return instance;
 }
@@ -146,6 +188,33 @@
     if ([newConfig hasHttpHeaders]) {
         merger.httpHeaders = newConfig.httpHeaders;
     }
+    if (newConfig.httpMethod != nil) {
+        merger.httpMethod = newConfig.httpMethod;
+    }
+    if (newConfig.syncHttpMethod != nil) {
+        merger.syncHttpMethod = newConfig.syncHttpMethod;
+    }
+    if (newConfig.httpMode != nil) {
+        merger.httpMode = newConfig.httpMode;
+    }
+    if (newConfig.syncMode != nil) {
+        merger.syncMode = newConfig.syncMode;
+    }
+    if (newConfig.queryParams != nil) {
+        merger.queryParams = newConfig.queryParams;
+    }
+    if ([newConfig hasShowsBackgroundLocationIndicator]) {
+        merger._showsBackgroundLocationIndicator = newConfig._showsBackgroundLocationIndicator;
+    }
+    if (newConfig.heartbeatInterval != nil) {
+        merger.heartbeatInterval = newConfig.heartbeatInterval;
+    }
+    if (newConfig.mockLocationPolicy != nil) {
+        merger.mockLocationPolicy = newConfig.mockLocationPolicy;
+    }
+    if (newConfig.drivingEvents != nil) {
+        merger.drivingEvents = newConfig.drivingEvents;
+    }
     if ([newConfig hasSaveBatteryOnBackground]) {
         merger._saveBatteryOnBackground = newConfig._saveBatteryOnBackground;
     }
@@ -181,6 +250,15 @@
         copy.syncThreshold = syncThreshold;
         copy.syncEnabled = syncEnabled;
         copy.httpHeaders = httpHeaders;
+        copy.httpMethod = httpMethod;
+        copy.syncHttpMethod = syncHttpMethod;
+        copy.httpMode = httpMode;
+        copy.syncMode = syncMode;
+        copy.queryParams = queryParams;
+        copy._showsBackgroundLocationIndicator = _showsBackgroundLocationIndicator;
+        copy.heartbeatInterval = heartbeatInterval;
+        copy.mockLocationPolicy = mockLocationPolicy;
+        copy.drivingEvents = drivingEvents;
         copy._saveBatteryOnBackground = _saveBatteryOnBackground;
         copy.maxLocations = maxLocations;
         copy._pauseLocationUpdates = _pauseLocationUpdates;
@@ -322,6 +400,16 @@
     return _saveBatteryOnBackground != nil;
 }
 
+- (BOOL) hasShowsBackgroundLocationIndicator
+{
+    return _showsBackgroundLocationIndicator != nil;
+}
+
+- (BOOL) showsBackgroundLocationIndicator
+{
+    return _showsBackgroundLocationIndicator != nil ? [_showsBackgroundLocationIndicator boolValue] : NO;
+}
+
 - (BOOL) hasMaxLocations
 {
     return maxLocations != nil;
@@ -479,6 +567,15 @@
     if ([self hasUrl]) [dict setObject:self.url forKey:@"url"];
     if ([self hasSyncUrl]) [dict setObject:self.syncUrl forKey:@"syncUrl"];
     if ([self hasHttpHeaders]) [dict setObject:self.httpHeaders forKey:@"httpHeaders"];
+    if (self.httpMethod != nil) [dict setObject:self.httpMethod forKey:@"httpMethod"];
+    if (self.syncHttpMethod != nil) [dict setObject:self.syncHttpMethod forKey:@"syncHttpMethod"];
+    if (self.httpMode != nil) [dict setObject:self.httpMode forKey:@"httpMode"];
+    if (self.syncMode != nil) [dict setObject:self.syncMode forKey:@"syncMode"];
+    if (self.queryParams != nil) [dict setObject:self.queryParams forKey:@"queryParams"];
+    if ([self hasShowsBackgroundLocationIndicator]) [dict setObject:self._showsBackgroundLocationIndicator forKey:@"showsBackgroundLocationIndicator"];
+    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 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/MAURDistanceFilterLocationProvider.m

@@ -87,6 +87,12 @@ enum {
     _config = config;
 
     locationManager.pausesLocationUpdatesAutomatically = [_config pauseLocationUpdates];
+    // v3.4 Phase 3: showsBackgroundLocationIndicator (iOS 11+).
+    if (@available(iOS 11.0, *)) {
+        if ([_config hasShowsBackgroundLocationIndicator]) {
+            locationManager.showsBackgroundLocationIndicator = [_config showsBackgroundLocationIndicator];
+        }
+    }
     locationManager.activityType = [_config decodeActivityType];
     locationManager.distanceFilter = _config.distanceFilter.integerValue; // meters
     locationManager.desiredAccuracy = [_config decodeDesiredAccuracy];
@@ -376,13 +382,34 @@ enum {
     }
 }
 
+// v3.4 Phase 3: iOS 14+ delegate callback. Replaces the legacy `didChangeAuthorizationStatus:`
+// (which is deprecated in iOS 14 but still delivered). On iOS 14+ this is the canonical entry
+// point and exposes accuracyAuthorization (Precise vs Reduced).
+- (void) locationManagerDidChangeAuthorization:(CLLocationManager *)manager API_AVAILABLE(ios(14.0))
+{
+    CLAuthorizationStatus status = manager.authorizationStatus;
+    DDLogInfo(@"LocationManager didChangeAuthorization (iOS 14+) status=%d accuracy=%ld",
+              (int)status, (long)manager.accuracyAuthorization);
+    [self handleAuthorizationStatusChange:status];
+}
+
 - (void) locationManager:(CLLocationManager *)manager didChangeAuthorizationStatus:(CLAuthorizationStatus)status
 {
-    DDLogInfo(@"LocationManager didChangeAuthorizationStatus %u", status);
+    // On iOS 14+ the system also delivers `locationManagerDidChangeAuthorization:`; ignore this
+    // legacy callback there to avoid double-notifying delegates.
+    if (@available(iOS 14.0, *)) {
+        return;
+    }
+    DDLogInfo(@"LocationManager didChangeAuthorizationStatus (legacy) %u", status);
+    [self handleAuthorizationStatusChange:status];
+}
+
+- (void) handleAuthorizationStatusChange:(CLAuthorizationStatus)status
+{
     if ([_config isDebugging]) {
         [self notify:[NSString stringWithFormat:@"Authorization status changed %u", status]];
     }
-    
+
     switch(status) {
         case kCLAuthorizationStatusRestricted:
         case kCLAuthorizationStatusDenied:

package/ios/common/BackgroundGeolocation/MAURPostLocationTask.h

@@ -19,6 +19,10 @@
 @optional
 - (void)postLocationTaskRequestedAbortUpdates:(MAURPostLocationTask * _Nonnull)task;
 - (void)postLocationTaskHttpAuthorizationUpdates:(MAURPostLocationTask * _Nonnull)task;
+// v3.5 Phase 4
+- (void)postLocationTaskSyncStarted:(MAURPostLocationTask * _Nonnull)task;
+- (void)postLocationTaskSyncSucceeded:(MAURPostLocationTask * _Nonnull)task locationsSent:(NSInteger)locationsSent;
+- (void)postLocationTaskSyncFailed:(MAURPostLocationTask * _Nonnull)task httpStatus:(NSInteger)httpStatus message:(NSString * _Nullable)message;
 
 @end
 

package/ios/common/BackgroundGeolocation/MAURPostLocationTask.m

@@ -15,6 +15,7 @@
 #import "MAURPostLocationTask.h"
 #import "MAURSQLiteLocationDAO.h"
 #import "MAURSessionLocationDAO.h"
+#import "MAURUrlTemplateResolver.h"
 
 static NSString * const TAG = @"MAURPostLocationTask";
 
@@ -80,15 +81,26 @@ static MAURLocationTransform s_locationTransform = nil;
     dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_BACKGROUND, 0), ^{
         
         MAURLocation *location = inLocation;
-        
+
         if (locationTransform != nil) {
             location = locationTransform(location);
-            
+
             if (location == nil) {
                 return;
             }
         }
-        
+
+        // v3.5 Phase 4: mock location policy. Detection already exists in MAURLocation.simulated.
+        if (location.simulated != nil && [location.simulated boolValue]) {
+            NSString *policy = self.config.mockLocationPolicy ?: @"allow";
+            if ([@"drop" isEqualToString:policy]) {
+                DDLogInfo(@"%@ Simulated/mock location dropped (mockLocationPolicy=drop)", TAG);
+                return;
+            }
+            // "flag": leave it. The simulated NSNumber is already on the model and propagates via toResultFromTemplate.
+            // "allow": no-op.
+        }
+
         MAURSQLiteLocationDAO *locationDAO = [MAURSQLiteLocationDAO sharedInstance];
         // TODO: investigate location id always 0
         NSNumber *locationId = [locationDAO persistLocation:location limitRows:self.config.maxLocations.integerValue];
@@ -117,28 +129,47 @@ static MAURLocationTransform s_locationTransform = nil;
     });
 }
 
-- (BOOL) post:(MAURLocation*)location 
-         toUrl:(NSString*)url 
-    withTemplate:(id)locationTemplate 
- withHttpHeaders:(NSMutableDictionary*)httpHeaders 
+- (BOOL) post:(MAURLocation*)location
+         toUrl:(NSString*)url
+    withTemplate:(id)locationTemplate
+ withHttpHeaders:(NSMutableDictionary*)httpHeaders
          error:(NSError * __autoreleasing *)outError
 {
-    NSArray *locations = [[NSArray alloc] initWithObjects:[location toResultFromTemplate:locationTemplate], nil];
-    NSData *data = [NSJSONSerialization dataWithJSONObject:locations options:0 error:outError];
-    if (!data) {
-        return NO;
+    // v3.3 Phase 2: backend-agnostic transport.
+    // Resolve URL template using current location + queryParams (for both single and batch modes).
+    NSString *resolvedUrl = [MAURUrlTemplateResolver resolve:url location:location queryParams:self.config.queryParams];
+
+    NSString *method = self.config.httpMethod ?: @"POST";
+    NSString *mode = self.config.httpMode ?: @"batch";
+    BOOL isBodyless = [@"GET" isEqualToString:method];
+    BOOL singleMode = isBodyless || [@"single" isEqualToString:mode];
+
+    NSData *data = nil;
+    if (!isBodyless) {
+        // For single mode (or body methods that prefer one location per request) send a JSONObject;
+        // for batch send the array (current behaviour).
+        if (singleMode) {
+            data = [NSJSONSerialization dataWithJSONObject:[location toResultFromTemplate:locationTemplate] options:0 error:outError];
+        } else {
+            NSArray *locations = [[NSArray alloc] initWithObjects:[location toResultFromTemplate:locationTemplate], nil];
+            data = [NSJSONSerialization dataWithJSONObject:locations options:0 error:outError];
+        }
+        if (!data) {
+            return NO;
+        }
     }
-    
-    NSString *jsonStr = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
-    
+
+    NSString *jsonStr = data ? [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding] : nil;
     NSString *contentType = [httpHeaders objectForKey:@"Content-Type"];
     if (!contentType) {
         contentType = @"application/json";
     }
-    
-    NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:url]];
-    [request setValue:contentType forHTTPHeaderField:@"Content-Type"];
-    [request setHTTPMethod:@"POST"];
+
+    NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:resolvedUrl]];
+    [request setHTTPMethod:method];
+    if (!isBodyless) {
+        [request setValue:contentType forHTTPHeaderField:@"Content-Type"];
+    }
     if (httpHeaders != nil) {
         for (id key in httpHeaders) {
             if (![key isEqualToString:@"Content-Type"]) {
@@ -147,36 +178,54 @@ static MAURLocationTransform s_locationTransform = nil;
             }
         }
     }
-    
-    if ([contentType isEqualToString:@"application/x-www-form-urlencoded"]) {
-        id jsonObject = [NSJSONSerialization JSONObjectWithData:data options:0 error:outError];
-        NSDictionary *dict = nil;
-        if ([jsonObject isKindOfClass:[NSArray class]] && [jsonObject count] == 1) {
-            dict = [jsonObject firstObject];
-        } else if ([jsonObject isKindOfClass:[NSDictionary class]]) {
-            dict = jsonObject;
-        }
-        if (dict) {
-            NSMutableArray *parts = [NSMutableArray array];
-            for (NSString *key in dict) {
-                NSString *value = [NSString stringWithFormat:@"%@", dict[key]];
-                NSString *encodedKey = [key stringByAddingPercentEncodingWithAllowedCharacters:[NSCharacterSet URLQueryAllowedCharacterSet]];
-                NSString *encodedValue = [value stringByAddingPercentEncodingWithAllowedCharacters:[NSCharacterSet URLQueryAllowedCharacterSet]];
-                NSString *part = [NSString stringWithFormat:@"%@=%@", encodedKey, encodedValue];
-                [parts addObject:part];
+
+    if (!isBodyless) {
+        if ([contentType isEqualToString:@"application/x-www-form-urlencoded"]) {
+            id jsonObject = [NSJSONSerialization JSONObjectWithData:data options:0 error:outError];
+            NSDictionary *dict = nil;
+            if ([jsonObject isKindOfClass:[NSArray class]] && [jsonObject count] == 1) {
+                dict = [jsonObject firstObject];
+            } else if ([jsonObject isKindOfClass:[NSDictionary class]]) {
+                dict = jsonObject;
+            }
+            if (dict) {
+                NSMutableArray *parts = [NSMutableArray array];
+                for (NSString *key in dict) {
+                    NSString *value = [NSString stringWithFormat:@"%@", dict[key]];
+                    NSString *encodedKey = [key stringByAddingPercentEncodingWithAllowedCharacters:[NSCharacterSet URLQueryAllowedCharacterSet]];
+                    NSString *encodedValue = [value stringByAddingPercentEncodingWithAllowedCharacters:[NSCharacterSet URLQueryAllowedCharacterSet]];
+                    NSString *part = [NSString stringWithFormat:@"%@=%@", encodedKey, encodedValue];
+                    [parts addObject:part];
+                }
+                NSString *encodedString = [parts componentsJoinedByString:@"&"];
+                [request setHTTPBody:[encodedString dataUsingEncoding:NSUTF8StringEncoding]];
+            } else {
+                [request setHTTPBody:[jsonStr dataUsingEncoding:NSUTF8StringEncoding]];
             }
-            NSString *encodedString = [parts componentsJoinedByString:@"&"];
-            [request setHTTPBody:[encodedString dataUsingEncoding:NSUTF8StringEncoding]];
         } else {
             [request setHTTPBody:[jsonStr dataUsingEncoding:NSUTF8StringEncoding]];
         }
-    } else {
-        [request setHTTPBody:[jsonStr dataUsingEncoding:NSUTF8StringEncoding]];
     }
-    
-    NSHTTPURLResponse* urlResponse = nil;
-    [NSURLConnection sendSynchronousRequest:request returningResponse:&urlResponse error:outError];
-    
+
+    // v3.4: NSURLSession (iOS 7+) replaces deprecated [NSURLConnection sendSynchronousRequest:].
+    // We run on a background queue (see -add: dispatch_async) so a semaphore-based wait is safe.
+    __block NSHTTPURLResponse *urlResponse = nil;
+    __block NSError *taskError = nil;
+    dispatch_semaphore_t sema = dispatch_semaphore_create(0);
+    NSURLSessionDataTask *dataTask = [[NSURLSession sharedSession]
+        dataTaskWithRequest:request
+          completionHandler:^(NSData * _Nullable d, NSURLResponse * _Nullable response, NSError * _Nullable err) {
+            urlResponse = (NSHTTPURLResponse *)response;
+            taskError = err;
+            dispatch_semaphore_signal(sema);
+        }];
+    [dataTask resume];
+    // 120s ceiling to mirror the previous synchronous timeout; URLSession also enforces its own.
+    dispatch_semaphore_wait(sema, dispatch_time(DISPATCH_TIME_NOW, (int64_t)(120 * NSEC_PER_SEC)));
+    if (taskError != nil && outError != NULL) {
+        *outError = taskError;
+    }
+
     NSInteger statusCode = urlResponse.statusCode;
     
     if (statusCode == 285)
@@ -220,7 +269,11 @@ static MAURLocationTransform s_locationTransform = nil;
     if (![self.config syncEnabled] || ![self.config hasValidSyncUrl]) {
         return;
     }
-    [uploader sync:self.config.syncUrl withTemplate:self.config._template withHttpHeaders:self.config.httpHeaders];
+    // For sync (batch) only static queryParams placeholders apply; per-location templating
+    // belongs in real-time post (httpMode="single" + httpMethod=GET) instead.
+    NSString *resolvedSyncUrl = [MAURUrlTemplateResolver resolve:self.config.syncUrl location:nil queryParams:self.config.queryParams];
+    NSString *syncMethod = self.config.syncHttpMethod ?: @"POST";
+    [uploader sync:resolvedSyncUrl withTemplate:self.config._template withHttpHeaders:self.config.httpHeaders withMethod:syncMethod];
 }
 
 #pragma mark - Location transform

package/ios/common/BackgroundGeolocation/MAURSensorFusionDetector.h

@@ -0,0 +1,41 @@
+//
+//  MAURSensorFusionDetector.h
+//  BackgroundGeolocation
+//
+//  v4.2 Phase 8 — Real sensor fusion detector for iOS.
+//  Uses CMMotionManager to sample userAcceleration (gravity removed) and rotationRate.
+//  Refines possibleCrash via accelerometer impact and detects phoneUsageWhileDriving.
+//
+
+#ifndef MAURSensorFusionDetector_h
+#define MAURSensorFusionDetector_h
+
+#import <Foundation/Foundation.h>
+
+@class MAURLocation;
+
+@protocol MAURSensorFusionListener <NSObject>
+- (void)onSensorCrashWithImpactG:(double)impactG location:(MAURLocation *)location;
+- (void)onPhoneUsageWhileDriving:(MAURLocation *)location;
+@end
+
+@interface MAURSensorFusionDetector : NSObject
+
+@property (nonatomic, weak)   id<MAURSensorFusionListener> listener;
+@property (nonatomic, assign) BOOL enabled;
+@property (nonatomic, assign) double crashImpactG;       // default 3.0
+@property (nonatomic, assign) NSTimeInterval crashCooldownMs;        // default 10000
+@property (nonatomic, assign) NSTimeInterval phoneUsageWindowMs;     // default 4000
+@property (nonatomic, assign) NSTimeInterval phoneUsageCooldownMs;   // default 60000
+
+@property (nonatomic, assign) BOOL tripActive;
+@property (nonatomic, strong) MAURLocation *lastLocation;
+
+- (instancetype)init;
+- (BOOL)isAvailable;
+- (void)start;
+- (void)stop;
+
+@end
+
+#endif /* MAURSensorFusionDetector_h */

package/ios/common/BackgroundGeolocation/MAURSensorFusionDetector.m

@@ -0,0 +1,137 @@
+//
+//  MAURSensorFusionDetector.m
+//  BackgroundGeolocation
+//
+//  v4.2 Phase 8 — sensor fusion detector implementation.
+//
+
+#import "MAURSensorFusionDetector.h"
+#import <CoreMotion/CoreMotion.h>
+#import <UIKit/UIKit.h>
+
+static const double kJitterGyroRadS  = 0.7;   // ~40 deg/s
+static const double kJitterAccelMps2 = 0.5;
+
+@interface MAURSensorFusionDetector ()
+@property (nonatomic, strong) CMMotionManager *motion;
+@property (nonatomic, strong) NSOperationQueue *queue;
+@property (nonatomic, assign) BOOL started;
+@property (nonatomic, assign) NSTimeInterval lastCrashAt;
+@property (nonatomic, assign) NSTimeInterval lastPhoneUsageAt;
+@property (nonatomic, assign) NSTimeInterval jitterAboveSince;
+@end
+
+@implementation MAURSensorFusionDetector
+
+- (instancetype)init {
+    if ((self = [super init])) {
+        _motion = [[CMMotionManager alloc] init];
+        _motion.deviceMotionUpdateInterval = 1.0 / 50.0; // 50 Hz
+        _queue = [[NSOperationQueue alloc] init];
+        _queue.name = @"MAURSensorFusionQueue";
+        _queue.maxConcurrentOperationCount = 1;
+        _enabled = NO;
+        _crashImpactG = 3.0;
+        _crashCooldownMs = 10000;
+        _phoneUsageWindowMs = 4000;
+        _phoneUsageCooldownMs = 60000;
+        _started = NO;
+        _lastCrashAt = 0;
+        _lastPhoneUsageAt = 0;
+        _jitterAboveSince = 0;
+    }
+    return self;
+}
+
+- (BOOL)isAvailable {
+    return self.motion.isDeviceMotionAvailable;
+}
+
+- (void)start {
+    @synchronized (self) {
+        if (self.started || !self.enabled) return;
+        if (![self.motion isDeviceMotionAvailable]) return;
+        __weak typeof(self) weakSelf = self;
+        [self.motion startDeviceMotionUpdatesToQueue:self.queue
+                                          withHandler:^(CMDeviceMotion * _Nullable motion, NSError * _Nullable error) {
+            if (!motion || error) return;
+            [weakSelf processMotion:motion];
+        }];
+        self.started = YES;
+    }
+}
+
+- (void)stop {
+    @synchronized (self) {
+        if (!self.started) return;
+        [self.motion stopDeviceMotionUpdates];
+        self.started = NO;
+        self.jitterAboveSince = 0;
+    }
+}
+
+- (void)processMotion:(CMDeviceMotion *)motion {
+    if (!self.enabled) return;
+    NSTimeInterval nowMs = [[NSDate date] timeIntervalSince1970] * 1000.0;
+
+    // userAcceleration is in g (gravity removed); convert magnitude to g and to m/s².
+    double ax = motion.userAcceleration.x;
+    double ay = motion.userAcceleration.y;
+    double az = motion.userAcceleration.z;
+    double accelMagG  = sqrt(ax*ax + ay*ay + az*az);            // g
+    double accelMagMs = accelMagG * 9.80665;                    // m/s²
+
+    double gx = motion.rotationRate.x;
+    double gy = motion.rotationRate.y;
+    double gz = motion.rotationRate.z;
+    double gyroMag = sqrt(gx*gx + gy*gy + gz*gz);               // rad/s
+
+    BOOL tripActiveNow = self.tripActive;
+    MAURLocation *loc = self.lastLocation;
+    id<MAURSensorFusionListener> l = self.listener;
+
+    // Crash detection
+    if (tripActiveNow && self.crashImpactG > 0 && accelMagG >= self.crashImpactG
+            && (nowMs - self.lastCrashAt) >= self.crashCooldownMs) {
+        self.lastCrashAt = nowMs;
+        if ([l respondsToSelector:@selector(onSensorCrashWithImpactG:location:)]) {
+            [l onSensorCrashWithImpactG:accelMagG location:loc];
+        }
+    }
+
+    // phoneUsageWhileDriving
+    if (!tripActiveNow) { self.jitterAboveSince = 0; return; }
+    BOOL screenOn = [self isScreenOnApprox];
+    if (!screenOn) { self.jitterAboveSince = 0; return; }
+
+    BOOL above = (accelMagMs >= kJitterAccelMps2) || (gyroMag >= kJitterGyroRadS);
+    if (above) {
+        if (self.jitterAboveSince == 0) self.jitterAboveSince = nowMs;
+        if ((nowMs - self.jitterAboveSince) >= self.phoneUsageWindowMs
+                && (nowMs - self.lastPhoneUsageAt) >= self.phoneUsageCooldownMs) {
+            self.lastPhoneUsageAt = nowMs;
+            self.jitterAboveSince = 0;
+            if ([l respondsToSelector:@selector(onPhoneUsageWhileDriving:)]) {
+                [l onPhoneUsageWhileDriving:loc];
+            }
+        }
+    } else {
+        self.jitterAboveSince = 0;
+    }
+}
+
+- (BOOL)isScreenOnApprox {
+    // Heuristic: app is foreground active => screen is on. Background sampling does
+    // not constitute phone usage while driving (passenger may have screen off too).
+    __block UIApplicationState state = UIApplicationStateBackground;
+    if ([NSThread isMainThread]) {
+        state = [UIApplication sharedApplication].applicationState;
+    } else {
+        dispatch_sync(dispatch_get_main_queue(), ^{
+            state = [UIApplication sharedApplication].applicationState;
+        });
+    }
+    return state == UIApplicationStateActive;
+}
+
+@end

package/ios/common/BackgroundGeolocation/MAURUrlTemplateResolver.h

@@ -0,0 +1,31 @@
+//
+//  MAURUrlTemplateResolver.h
+//  BackgroundGeolocation
+//
+//  Resolves placeholders like {lat}, {lon}, {timestamp_iso}, {device_id}, ...
+//  in a URL template using a single MAURLocation and an optional queryParams dictionary.
+//
+//  Placeholders not found in the location/queryParams are left as-is so partial templates
+//  (e.g. only static keys for batch mode) keep working.
+//
+
+#ifndef MAURUrlTemplateResolver_h
+#define MAURUrlTemplateResolver_h
+
+#import <Foundation/Foundation.h>
+
+@class MAURLocation;
+
+@interface MAURUrlTemplateResolver : NSObject
+
+/**
+ * Resolve placeholders in `template` using values from `location` and `queryParams`.
+ * Either may be nil. Returns the resolved URL (or the original template if no placeholders).
+ */
++ (NSString *)resolve:(NSString *)urlTemplate
+             location:(MAURLocation *)location
+          queryParams:(NSDictionary *)queryParams;
+
+@end
+
+#endif /* MAURUrlTemplateResolver_h */