@azatek/background-geolocation 1.0.0

package/definitions.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Location accuracy levels for power management.
+ * Higher accuracy = more battery consumption.
+ */
+export enum LocationAccuracy {
+    /**
+     * Highest accuracy (GPS) - High battery consumption
+     * Android: PRIORITY_HIGH_ACCURACY
+     * iOS: kCLLocationAccuracyBest
+     */
+    HIGH = 100,
+
+    /**
+     * Balanced accuracy (GPS + Network) - Medium battery consumption
+     * Android: PRIORITY_BALANCED_POWER_ACCURACY
+     * iOS: kCLLocationAccuracyNearestTenMeters
+     */
+    BALANCED = 102,
+
+    /**
+     * Low accuracy (Network) - Low battery consumption
+     * Android: PRIORITY_LOW_POWER
+     * iOS: kCLLocationAccuracyHundredMeters
+     */
+    LOW = 104,
+
+    /**
+     * Passive updates - Minimal battery consumption
+     * Android: PRIORITY_PASSIVE
+     * iOS: kCLLocationAccuracyThreeKilometers
+     */
+    PASSIVE = 105
+}
+
+/**
+ * The options for configuring a watcher that listens for location updates.
+ */
+export interface WatcherOptions {
+    /**
+     * If the "backgroundMessage" option is defined, the watcher will
+     * provide location updates whether the app is in the background or the
+     * foreground. If it is not defined, location updates are only
+     * guaranteed in the foreground. This is true on both platforms.
+     *
+     * On Android, a notification must be shown to continue receiving
+     * location updates in the background. This option specifies the text of
+     * that notification.
+     */
+    backgroundMessage?: string;
+    /**
+     * The title of the notification mentioned above.
+     * @default "Using your location"
+     */
+    backgroundTitle?: string;
+    /**
+     * Whether permissions should be requested from the user automatically,
+     * if they are not already granted.
+     * @default true
+     */
+    requestPermissions?: boolean;
+    /**
+     * If "true", stale locations may be delivered while the device
+     * obtains a GPS fix. You are responsible for checking the "time"
+     * property. If "false", locations are guaranteed to be up to date.
+     * @default false
+     */
+    stale?: boolean;
+    /**
+     * The distance in meters that the device must move before a new location update is triggered.
+     * This is used to filter out small movements and reduce the number of updates.
+     * @default 0
+     */
+    distanceFilter?: number;
+    /**
+     * The desired accuracy level for location updates.
+     * Higher accuracy levels consume more battery power.
+     * @default LocationAccuracy.BALANCED
+     */
+    accuracy?: LocationAccuracy;
+}
+
+/**
+ * Represents a geographical location with various attributes.
+ */
+export interface Location {
+    /**
+     * Longitude in degrees.
+     */
+    latitude: number;
+    /**
+     * Latitude in degrees.
+     */
+    longitude: number;
+    /**
+     * Radius of horizontal uncertainty in metres, with 68% confidence.
+     */
+    accuracy: number;
+    /**
+     * Metres above sea level (or null).
+     */
+    altitude: number | null;
+    /**
+     * Vertical uncertainty in metres, with 68% confidence (or null).
+     */
+    altitudeAccuracy: number | null;
+    /**
+     * `true` if the location was simulated by software, rather than GPS.
+     */
+    simulated: boolean;
+    /**
+     * Deviation from true north in degrees (or null).
+     */
+    bearing: number | null;
+    /**
+     * Speed in metres per second (or null).
+     */
+    speed: number | null;
+    /**
+     * Time the location was produced, in milliseconds since the unix epoch.
+     */
+    time: number | null;
+}
+
+export interface CallbackError extends Error {
+    code?: string;
+}
+
+export interface BackgroundGeolocationPlugin {
+    /**
+     * Adds a watcher for location updates.
+     * The watcher will be invoked with the latest location whenever it is available.
+     * If an error occurs, the callback will be invoked with the error.
+     *
+     * @param options the watcher options
+     * @param callback the callback to be invoked when a new location is available or an error occurs
+     * @returns a promise that resolves to a unique identifier for the watcher ID
+     */
+    addWatcher(
+        options: WatcherOptions,
+        callback: (
+            position?: Location,
+            error?: CallbackError
+        ) => void
+    ): Promise<string>;
+    /**
+     * Removes a watcher by its unique identifier.
+     * @param options the options for removing the watcher
+     * @returns a promise that resolves when the watcher is successfully removed
+     */
+    removeWatcher(options: {
+        id: string
+    }): Promise<void>;
+    /**
+     * Opens the settings page of the app.
+     */
+    openSettings(): Promise<void>;
+}

package/ios/Plugin/Info.plist

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>$(DEVELOPMENT_LANGUAGE)</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>$(PRODUCT_NAME)</string>
+	<key>CFBundlePackageType</key>
+	<string>FMWK</string>
+	<key>CFBundleShortVersionString</key>
+	<string>1.0</string>
+	<key>CFBundleVersion</key>
+	<string>$(CURRENT_PROJECT_VERSION)</string>
+	<key>NSPrincipalClass</key>
+	<string></string>
+</dict>
+</plist>

package/ios/Plugin/Plugin.h

@@ -0,0 +1,10 @@
+#import <UIKit/UIKit.h>
+
+//! Project version number for Plugin.
+FOUNDATION_EXPORT double PluginVersionNumber;
+
+//! Project version string for Plugin.
+FOUNDATION_EXPORT const unsigned char PluginVersionString[];
+
+// In this header, you should import all the public headers of your framework using statements like #import <Plugin/PublicHeader.h>
+

package/ios/Plugin/Plugin.m

@@ -0,0 +1,8 @@
+#import <Foundation/Foundation.h>
+#import <Capacitor/Capacitor.h>
+
+CAP_PLUGIN(BackgroundGeolocation, "BackgroundGeolocation",
+    CAP_PLUGIN_METHOD(addWatcher, CAPPluginReturnCallback);
+    CAP_PLUGIN_METHOD(removeWatcher, CAPPluginReturnPromise);
+    CAP_PLUGIN_METHOD(openSettings, CAPPluginReturnPromise);
+)

package/ios/Plugin/Swift/Plugin.swift

@@ -0,0 +1,263 @@
+import Capacitor
+import Foundation
+import UIKit
+import CoreLocation
+
+// Avoids a bewildering type warning.
+let null = Optional<Double>.none as Any
+
+func formatLocation(_ location: CLLocation) -> PluginCallResultData {
+    var simulated = false;
+    if #available(iOS 15, *) {
+        // Prior to iOS 15, it was not possible to detect simulated locations.
+        // But in general, it is very difficult to simulate locations on iOS in
+        // production.
+        if location.sourceInformation != nil {
+            simulated = location.sourceInformation!.isSimulatedBySoftware;
+        }
+    }
+    return [
+        "latitude": location.coordinate.latitude,
+        "longitude": location.coordinate.longitude,
+        "accuracy": location.horizontalAccuracy,
+        "altitude": location.altitude,
+        "altitudeAccuracy": location.verticalAccuracy,
+        "simulated": simulated,
+        "speed": location.speed < 0 ? null : location.speed,
+        "bearing": location.course < 0 ? null : location.course,
+        "time": NSNumber(
+            value: Int(
+                location.timestamp.timeIntervalSince1970 * 1000
+            )
+        ),
+    ]
+}
+
+class Watcher {
+    let callbackId: String
+    let locationManager: CLLocationManager = CLLocationManager()
+    private let created = Date()
+    private let allowStale: Bool
+    private var isUpdatingLocation: Bool = false
+    init(_ id: String, stale: Bool) {
+        callbackId = id
+        allowStale = stale
+    }
+    func start() {
+        // Avoid unnecessary calls to startUpdatingLocation, which can
+        // result in extraneous invocations of didFailWithError.
+        if !isUpdatingLocation {
+            locationManager.startUpdatingLocation()
+            isUpdatingLocation = true
+        }
+    }
+    func stop() {
+        if isUpdatingLocation {
+            locationManager.stopUpdatingLocation()
+            isUpdatingLocation = false
+        }
+    }
+    func isLocationValid(_ location: CLLocation) -> Bool {
+        return (
+            allowStale ||
+            location.timestamp >= created
+        )
+    }
+}
+
+@objc(BackgroundGeolocation)
+public class BackgroundGeolocation: CAPPlugin,
+                                    CAPBridgedPlugin,
+                                    CLLocationManagerDelegate {
+    private var watchers = [Watcher]()
+    public let identifier = "BackgroundGeolocation"
+    public let jsName = "BackgroundGeolocation"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "addWatcher", returnType: CAPPluginReturnCallback),
+        CAPPluginMethod(name: "removeWatcher", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "openSettings", returnType: CAPPluginReturnPromise)
+    ]
+
+    @objc public override func load() {
+        UIDevice.current.isBatteryMonitoringEnabled = true
+    }
+
+    @objc func addWatcher(_ call: CAPPluginCall) {
+        call.keepAlive = true
+
+        // CLLocationManager requires main thread
+        DispatchQueue.main.async {
+            let background = call.getString("backgroundMessage") != nil
+            let watcher = Watcher(
+                call.callbackId,
+                stale: call.getBool("stale") ?? false
+            )
+            let manager = watcher.locationManager
+            manager.delegate = self
+
+            // Configure accuracy based on parameter (default: BALANCED = 102)
+            let accuracy = call.getInt("accuracy") ?? 102
+
+            switch accuracy {
+            case 100: // HIGH
+                 let isCharging = [
+                    .charging,
+                    .full
+                 ].contains(UIDevice.current.batteryState)
+
+                if isCharging {
+                    manager.desiredAccuracy = kCLLocationAccuracyBestForNavigation
+                } else {
+                    manager.desiredAccuracy = kCLLocationAccuracyBest
+                }
+                manager.activityType = .otherNavigation
+            case 102: // BALANCED (Default)
+                manager.desiredAccuracy = kCLLocationAccuracyNearestTenMeters
+                manager.activityType = .other
+            case 104: // LOW
+                manager.desiredAccuracy = kCLLocationAccuracyHundredMeters
+                manager.activityType = .other
+            case 105: // PASSIVE
+                manager.desiredAccuracy = kCLLocationAccuracyThreeKilometers
+                manager.activityType = .other
+            default:
+                manager.desiredAccuracy = kCLLocationAccuracyNearestTenMeters
+                manager.activityType = .other
+            }
+            var distanceFilter = call.getDouble("distanceFilter")
+            // It appears that setting manager.distanceFilter to 0 can prevent
+            // subsequent location updates. See issue #88.
+            if distanceFilter == nil || distanceFilter == 0 {
+                distanceFilter = kCLDistanceFilterNone
+            }
+            manager.distanceFilter = distanceFilter!
+            manager.allowsBackgroundLocationUpdates = background
+            manager.showsBackgroundLocationIndicator = background
+            manager.pausesLocationUpdatesAutomatically = false
+            self.watchers.append(watcher)
+            if call.getBool("requestPermissions") != false {
+                let status = CLLocationManager.authorizationStatus()
+                if [
+                    .notDetermined,
+                    .denied,
+                    .restricted,
+                ].contains(status) {
+                    return (
+                        background
+                        ? manager.requestAlwaysAuthorization()
+                        : manager.requestWhenInUseAuthorization()
+                    )
+                }
+                if (
+                    background && status == .authorizedWhenInUse
+                ) {
+                    // Attempt to escalate.
+                    manager.requestAlwaysAuthorization()
+                }
+            }
+            return watcher.start()
+        }
+    }
+
+    @objc func removeWatcher(_ call: CAPPluginCall) {
+        // CLLocationManager requires main thread
+        DispatchQueue.main.async {
+            if let callbackId = call.getString("id") {
+                if let index = self.watchers.firstIndex(
+                    where: { $0.callbackId == callbackId }
+                ) {
+                    self.watchers[index].locationManager.stopUpdatingLocation()
+                    self.watchers.remove(at: index)
+                }
+                if let savedCall = self.bridge?.savedCall(withID: callbackId) {
+                    self.bridge?.releaseCall(savedCall)
+                }
+                return call.resolve()
+            }
+            return call.reject("No callback ID")
+        }
+    }
+
+    @objc func openSettings(_ call: CAPPluginCall) {
+        DispatchQueue.main.async {
+            guard let settingsUrl = URL(
+                string: UIApplication.openSettingsURLString
+            ) else {
+                return call.reject("No link to settings available")
+            }
+
+            if UIApplication.shared.canOpenURL(settingsUrl) {
+                UIApplication.shared.open(settingsUrl, completionHandler: {
+                    (success) in
+                    if (success) {
+                        return call.resolve()
+                    } else {
+                        return call.reject("Failed to open settings")
+                    }
+                })
+            } else {
+                return call.reject("Cannot open settings")
+            }
+        }
+    }
+
+    public func locationManager(
+        _ manager: CLLocationManager,
+        didFailWithError error: Error
+    ) {
+        if let watcher = self.watchers.first(
+            where: { $0.locationManager == manager }
+        ) {
+            if let call = self.bridge?.savedCall(withID: watcher.callbackId) {
+                if let clErr = error as? CLError {
+                    if clErr.code == .locationUnknown {
+                        // This error is sometimes sent by the manager if
+                        // it cannot get a fix immediately.
+                        return
+                    } else if (clErr.code == .denied) {
+                        watcher.stop()
+                        return call.reject(
+                            "Permission denied.",
+                            "NOT_AUTHORIZED"
+                        )
+                    }
+                }
+                return call.reject(error.localizedDescription, nil, error)
+            }
+        }
+    }
+
+    public func locationManager(
+        _ manager: CLLocationManager,
+        didUpdateLocations locations: [CLLocation]
+    ) {
+        if let location = locations.last {
+            if let watcher = self.watchers.first(
+                where: { $0.locationManager == manager }
+            ) {
+                if watcher.isLocationValid(location) {
+                    if let call = self.bridge?.savedCall(withID: watcher.callbackId) {
+                        return call.resolve(formatLocation(location))
+                    }
+                }
+            }
+        }
+    }
+
+    public func locationManager(
+        _ manager: CLLocationManager,
+        didChangeAuthorization status: CLAuthorizationStatus
+    ) {
+        // If this method is called before the user decides on a permission, as
+        // it is on iOS 14 when the permissions dialog is presented, we ignore
+        // it.
+        if status != .notDetermined {
+            if let watcher = self.watchers.first(
+                where: { $0.locationManager == manager }
+            ) {
+                return watcher.start()
+            }
+        }
+    }
+}
+

package/ios/Podfile

@@ -0,0 +1,16 @@
+platform :ios, '12.0'
+
+def capacitor_pods
+  # Comment the next line if you're not using Swift and don't want to use dynamic frameworks
+  use_frameworks!
+  pod 'Capacitor', :path => '../node_modules/@capacitor/ios'
+  pod 'CapacitorCordova', :path => '../node_modules/@capacitor/ios'
+end
+
+target 'Plugin' do
+  capacitor_pods
+end
+
+target 'PluginTests' do
+  capacitor_pods
+end

package/package.json

@@ -0,0 +1,56 @@
+{
+    "name": "@azatek/background-geolocation",
+    "version": "1.0.0",
+    "description": "Capacitor plugin for background geolocation tracking with configurable GPS accuracy modes (HIGH/BALANCED/LOW/PASSIVE) for battery optimization. Fork of @capacitor-community/background-geolocation with enhanced accuracy control.",
+    "keywords": [
+        "capacitor",
+        "plugin",
+        "geolocation",
+        "background",
+        "gps",
+        "location",
+        "tracking",
+        "accuracy",
+        "battery-optimization",
+        "android",
+        "ios"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/AzaTek61/background-geolocation.git"
+    },
+    "author": "AzaTek",
+    "license": "MIT",
+    "types": "definitions.d.ts",
+    "files": [
+        "CapacitorCommunityBackgroundGeolocation.podspec",
+        "Package.swift",
+        "android/build.gradle",
+        "android/gradle.properties",
+        "android/gradle/wrapper/gradle-wrapper.properties",
+        "android/proguard-rules.pro",
+        "android/settings.gradle",
+        "android/src/main/",
+        "definitions.d.ts",
+        "ios/Plugin/Info.plist",
+        "ios/Plugin/Plugin.*",
+        "ios/Plugin/Swift/Plugin.swift",
+        "ios/Podfile*"
+    ],
+    "devDependencies": {
+        "@capacitor/android": "^7.0.0",
+        "@capacitor/core": "^7.0.0",
+        "@capacitor/ios": "^7.0.0"
+    },
+    "peerDependencies": {
+        "@capacitor/core": ">=3.0.0"
+    },
+    "capacitor": {
+        "ios": {
+            "src": "ios"
+        },
+        "android": {
+            "src": "android"
+        }
+    }
+}