@nitra/geolocation 7.1.5 → 8.2.0

package/android/src/main/kotlin/com/capacitorjs/plugins/geolocation/GeolocationPlugin.kt

@@ -1,7 +1,14 @@
 package com.capacitorjs.plugins.geolocation
 
 import android.Manifest
+import android.content.Context
+import android.location.Location
+import android.location.LocationListener
+import android.location.LocationManager
+import android.location.OnNmeaMessageListener
 import android.os.Build
+import android.os.Handler
+import android.os.Looper
 import androidx.activity.result.contract.ActivityResultContracts
 import com.getcapacitor.JSObject
 import com.getcapacitor.PermissionState
@@ -11,15 +18,22 @@ import com.getcapacitor.PluginMethod
 import com.getcapacitor.annotation.CapacitorPlugin
 import com.getcapacitor.annotation.Permission
 import com.getcapacitor.annotation.PermissionCallback
-import com.google.android.gms.location.LocationServices
 import io.ionic.libs.iongeolocationlib.controller.IONGLOCController
 import io.ionic.libs.iongeolocationlib.model.IONGLOCException
 import io.ionic.libs.iongeolocationlib.model.IONGLOCLocationOptions
 import io.ionic.libs.iongeolocationlib.model.IONGLOCLocationResult
+import kotlinx.coroutines.async
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.cancel
 import kotlinx.coroutines.launch
+import kotlinx.coroutines.suspendCancellableCoroutine
+import kotlinx.coroutines.withTimeout
+import java.util.Calendar
+import java.util.Locale
+import java.util.TimeZone
+import kotlin.coroutines.resume
+import org.json.JSONObject
 
 @CapacitorPlugin(
     name = "Geolocation",
@@ -37,9 +51,16 @@ class GeolocationPlugin : Plugin() {
     private lateinit var coroutineScope: CoroutineScope
     private val watchingCalls: MutableMap<String, PluginCall> = mutableMapOf()
 
+    private data class GnssTimeResult(
+        val timestamp: Long,
+        val status: String?,
+        val nmea: String
+    )
+
     companion object {
         const val LOCATION_ALIAS: String = "location"
         const val COARSE_LOCATION_ALIAS: String = "coarseLocation"
+        const val WATCH_SATELLITE_TIME_TIMEOUT_MS: Long = 1000
     }
 
     override fun load() {
@@ -54,11 +75,7 @@ class GeolocationPlugin : Plugin() {
             }
         }
 
-        this.controller = IONGLOCController(
-            LocationServices.getFusedLocationProviderClient(context),
-            activityLauncher
-        )
-
+        this.controller = IONGLOCController(context, activityLauncher)
     }
 
     override fun handleOnDestroy() {
@@ -82,7 +99,7 @@ class GeolocationPlugin : Plugin() {
      * @param onLocationEnabled lambda function to use in case location services are enabled
      */
     private fun checkLocationState(call: PluginCall, onLocationEnabled: () -> Unit) {
-        if (controller.areLocationServicesEnabled(context)) {
+        if (controller.areLocationServicesEnabled()) {
             onLocationEnabled()
         } else {
             call.sendError(GeolocationErrors.LOCATION_DISABLED)
@@ -120,7 +137,10 @@ class GeolocationPlugin : Plugin() {
         callbackName: String,
         onPermissionGranted: () -> Unit
     ) {
-        val alias = getAlias(call)
+        val alias = getAlias(call) ?: run {
+            call.sendError(GeolocationErrors.LOCATION_MANIFEST_PERMISSIONS_MISSING)
+            return
+        }
         if (getPermissionState(alias) != PermissionState.GRANTED) {
             requestPermissionForAlias(alias, call, callbackName)
         } else {
@@ -161,6 +181,37 @@ class GeolocationPlugin : Plugin() {
         }
     }
 
+    /**
+     * Requests precise location permission. GNSS NMEA data should not be exposed through coarse permission.
+     * @param call the PluginCall to use in case we want to send an error
+     * @param callbackName a string identifying the callback to call once the permission prompt is answered
+     * @param onPermissionGranted lambda function to use in case the permission is enabled
+     */
+    private fun handlePrecisePermissionRequest(
+        call: PluginCall,
+        callbackName: String,
+        onPermissionGranted: () -> Unit
+    ) {
+        if (getPermissionState(LOCATION_ALIAS) != PermissionState.GRANTED) {
+            requestPermissionForAlias(LOCATION_ALIAS, call, callbackName)
+        } else {
+            onPermissionGranted()
+        }
+    }
+
+    /**
+     * Handles precise location permission results.
+     * @param call the PluginCall to use in case we want to send an error
+     * @param onPermissionGranted lambda function to use in case the permission was granted
+     */
+    private fun handlePrecisePermissionResult(call: PluginCall, onPermissionGranted: () -> Unit) {
+        if (getPermissionState(LOCATION_ALIAS) == PermissionState.GRANTED) {
+            onPermissionGranted()
+        } else {
+            call.sendError(GeolocationErrors.LOCATION_PERMISSIONS_DENIED)
+        }
+    }
+
     /**
      * Clears the watch, removing location updates.
      * @param call the plugin call
@@ -182,19 +233,20 @@ class GeolocationPlugin : Plugin() {
     }
 
     /**
-     * Gets the appropriate permission alias
+     * Gets the appropriate permission alias, based on the Android version, 
+     *  the permissions declared in the manifest 
+     *  and the enableHighAccuracy option provided by the caller.
      * @param call the plugin call
-     * @return String with correct alias
+     * @return String with correct alias or null if no permissions can be requested
      */
-    private fun getAlias(call: PluginCall): String {
-        var alias = LOCATION_ALIAS
-        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
-            val enableHighAccuracy = call.getBoolean("enableHighAccuracy") ?: false
-            if (!enableHighAccuracy) {
-                alias = COARSE_LOCATION_ALIAS
-            }
-        }
-        return alias
+    private fun getAlias(call: PluginCall): String? {
+        val hasFine = isPermissionDeclared(LOCATION_ALIAS)
+        val hasCoarse = isPermissionDeclared(COARSE_LOCATION_ALIAS)
+        if (!hasFine && !hasCoarse) return null
+        val enableHighAccuracy = call.getBoolean("enableHighAccuracy") ?: false
+        val shouldRequestFine =
+            hasFine && (Build.VERSION.SDK_INT < Build.VERSION_CODES.S || enableHighAccuracy)
+        return if (shouldRequestFine) LOCATION_ALIAS else COARSE_LOCATION_ALIAS
     }
 
     /**
@@ -204,20 +256,152 @@ class GeolocationPlugin : Plugin() {
     private fun getPosition(call: PluginCall) {
         coroutineScope.launch {
             val locationOptions = createOptions(call)
+            val gnssTime = async {
+                getGnssTimeOrNull(locationOptions.timeout)
+            }
 
             // call getCurrentPosition method from controller
             val locationResult = controller.getCurrentPosition(activity, locationOptions)
 
             locationResult
                 .onSuccess { location ->
-                    call.sendSuccess(getJSObjectForLocation(location))
+                    call.sendSuccess(getJSObjectForLocation(location, gnssTime.await()))
                 }
                 .onFailure { exception ->
+                    gnssTime.cancel()
                     onLocationError(exception, call)
                 }
         }
     }
 
+    /**
+     * Waits until the GNSS receiver emits an RMC NMEA sentence containing date and UTC time.
+     * @return satellite time parsed from NMEA
+     */
+    private suspend fun awaitSatelliteTime(): GnssTimeResult {
+        val locationManager = context.getSystemService(Context.LOCATION_SERVICE) as LocationManager
+
+        if (!locationManager.isProviderEnabled(LocationManager.GPS_PROVIDER)) {
+            throw IllegalStateException("GPS provider is disabled.")
+        }
+
+        return suspendCancellableCoroutine { continuation ->
+            lateinit var listener: OnNmeaMessageListener
+            val locationListener = object : LocationListener {
+                override fun onLocationChanged(location: Location) = Unit
+            }
+
+            fun cleanup() {
+                locationManager.removeNmeaListener(listener)
+                locationManager.removeUpdates(locationListener)
+            }
+
+            listener = OnNmeaMessageListener { message, _ ->
+                val gnssTime = parseSatelliteTime(message)
+                if (gnssTime != null && continuation.isActive) {
+                    cleanup()
+                    continuation.resume(gnssTime)
+                }
+            }
+
+            val registered = locationManager.addNmeaListener(listener, Handler(Looper.getMainLooper()))
+            if (!registered && continuation.isActive) {
+                continuation.cancel(IllegalStateException("Unable to register NMEA listener."))
+                return@suspendCancellableCoroutine
+            }
+
+            try {
+                locationManager.requestLocationUpdates(LocationManager.GPS_PROVIDER, 1000L, 0f, locationListener)
+            } catch (exception: Throwable) {
+                cleanup()
+                continuation.cancel(exception)
+                return@suspendCancellableCoroutine
+            }
+
+            continuation.invokeOnCancellation {
+                cleanup()
+            }
+        }
+    }
+
+    /**
+     * Returns satellite time if GNSS RMC NMEA data is available within the timeout.
+     * Position responses use null instead of failing when GNSS time is unavailable.
+     * @param timeout maximum wait time in milliseconds
+     * @return satellite time parsed from NMEA or null
+     */
+    private suspend fun getGnssTimeOrNull(timeout: Long): GnssTimeResult? {
+        if (timeout <= 0) {
+            return null
+        }
+
+        return try {
+            withTimeout(timeout) {
+                awaitSatelliteTime()
+            }
+        } catch (_: Throwable) {
+            null
+        }
+    }
+
+    /**
+     * Parses UTC date/time from RMC NMEA sentences such as GPRMC, GNRMC, or GARMC.
+     * @param message raw NMEA sentence
+     * @return satellite time parsed from NMEA, or null if the sentence does not contain time
+     */
+    private fun parseSatelliteTime(message: String): GnssTimeResult? {
+        val sentence = message.trim()
+        val withoutChecksum = sentence.substringBefore("*")
+        val fields = withoutChecksum.split(",")
+        if (fields.size <= 9 || !fields[0].endsWith("RMC")) {
+            return null
+        }
+
+        val time = fields[1]
+        val status = fields[2].ifBlank { null }
+        val date = fields[9]
+
+        if (status != "A") {
+            return null
+        }
+
+        if (time.length < 6 || date.length != 6) {
+            return null
+        }
+
+        val hour = time.substring(0, 2).toIntOrNull() ?: return null
+        val minute = time.substring(2, 4).toIntOrNull() ?: return null
+        val second = time.substring(4, 6).toIntOrNull() ?: return null
+        val millisecond = time.substringAfter(".", "").take(3).padEnd(3, '0').toIntOrNull() ?: 0
+        val day = date.substring(0, 2).toIntOrNull() ?: return null
+        val month = date.substring(2, 4).toIntOrNull() ?: return null
+        val yearSuffix = date.substring(4, 6).toIntOrNull() ?: return null
+        val year = if (yearSuffix >= 80) 1900 + yearSuffix else 2000 + yearSuffix
+
+        val calendar = Calendar.getInstance(TimeZone.getTimeZone("UTC"), Locale.US).apply {
+            clear()
+            isLenient = false
+            set(Calendar.YEAR, year)
+            set(Calendar.MONTH, month - 1)
+            set(Calendar.DAY_OF_MONTH, day)
+            set(Calendar.HOUR_OF_DAY, hour)
+            set(Calendar.MINUTE, minute)
+            set(Calendar.SECOND, second)
+            set(Calendar.MILLISECOND, millisecond)
+        }
+
+        val timestamp = try {
+            calendar.timeInMillis
+        } catch (_: IllegalArgumentException) {
+            return null
+        }
+        return GnssTimeResult(
+            timestamp = timestamp,
+            status = status,
+            nmea = sentence
+        )
+    }
+
     /**
      * Starts watching the device's location by requesting location updates
      * @param call the plugin call
@@ -232,8 +416,9 @@ class GeolocationPlugin : Plugin() {
             controller.addWatch(activity, locationOptions, watchId).collect { result ->
                 result.onSuccess { locationList ->
                     locationList.forEach { locationResult ->
+                        val gnssTime = getGnssTimeOrNull(WATCH_SATELLITE_TIME_TIMEOUT_MS)
                         call.sendSuccess(
-                            result = getJSObjectForLocation(locationResult),
+                            result = getJSObjectForLocation(locationResult, gnssTime),
                             keepCallback = true)
                     }
                 }
@@ -250,7 +435,10 @@ class GeolocationPlugin : Plugin() {
      * @param locationResult IONGLOCLocationResult object with the location to convert
      * @return JSObject with converted JSON object
      */
-    private fun getJSObjectForLocation(locationResult: IONGLOCLocationResult): JSObject {
+    private fun getJSObjectForLocation(
+        locationResult: IONGLOCLocationResult,
+        gnssTime: GnssTimeResult?
+    ): JSObject {
         val coords = JSObject().apply {
             put("latitude", locationResult.latitude)
             put("longitude", locationResult.longitude)
@@ -258,12 +446,12 @@ class GeolocationPlugin : Plugin() {
             put("altitude", locationResult.altitude)
             locationResult.altitudeAccuracy?.let { put("altitudeAccuracy", it) }
             put("speed", locationResult.speed)
-            put("heading", locationResult.heading)
+            put("heading", if (locationResult.heading != -1f) locationResult.heading else null)
             put("isMock", locationResult.isMock)
             put("provider", locationResult.provider)
         }
         return JSObject().apply {
-            put("timestamp", locationResult.timestamp)
+            put("timestamp", gnssTime?.timestamp ?: JSONObject.NULL)
             put("coords", coords)
         }
     }
@@ -294,6 +482,9 @@ class GeolocationPlugin : Plugin() {
             is IONGLOCException.IONGLOCLocationRetrievalTimeoutException -> {
                 call.sendError(GeolocationErrors.GET_LOCATION_TIMEOUT)
             }
+            is IONGLOCException.IONGLOCLocationAndNetworkDisabledException -> {
+                call.sendError(GeolocationErrors.NETWORK_LOCATION_DISABLED_ERROR)
+            }
             else -> {
                 call.sendError(GeolocationErrors.POSITION_UNAVAILABLE)
             }
@@ -315,7 +506,7 @@ class GeolocationPlugin : Plugin() {
     }
 
     /**
-     * Extension function to return a unsuccessful plugin result
+     * Extension function to return an unsuccessful plugin result
      * @param error error class representing the error to return, containing a code and message
      */
     private fun PluginCall.sendError(error: GeolocationErrors.ErrorInfo) {
@@ -328,13 +519,26 @@ class GeolocationPlugin : Plugin() {
      * @return IONGLOCLocationOptions object
      */
     private fun createOptions(call: PluginCall): IONGLOCLocationOptions {
-        val timeout = call.getLong("timeout", 10000) ?: 10000
-        val maximumAge = call.getLong("maximumAge", 0) ?: 0
+        val timeout = call.getNumber("timeout", 10000)
+        val maximumAge = call.getNumber("maximumAge", 0)
         val enableHighAccuracy = call.getBoolean("enableHighAccuracy", false) ?: false
-        val minimumUpdateInterval = call.getLong("minimumUpdateInterval", 5000) ?: 5000
-
-        val locationOptions = IONGLOCLocationOptions(timeout, maximumAge, enableHighAccuracy, minimumUpdateInterval)
+        val minimumUpdateInterval = call.getNumber("minimumUpdateInterval", 5000)
+        val enableLocationFallback = call.getBoolean("enableLocationFallback", true) ?: true
+        val interval = call.getNumber("interval", -1).let {
+            // using "< 0" and not "<= 0" because 0 is a valid value for interval
+            if (it < 0) timeout else it
+        }
 
-        return locationOptions
+        return IONGLOCLocationOptions(
+            timeout = timeout,
+            maximumAge = maximumAge,
+            enableHighAccuracy = enableHighAccuracy,
+            enableLocationManagerFallback = enableLocationFallback,
+            interval = interval,
+            minUpdateInterval = minimumUpdateInterval
+        )
     }
-}
+
+    private fun PluginCall.getNumber(name: String, defaultValue: Long): Long =
+        getLong(name) ?: getInt(name)?.toLong() ?: defaultValue
+}

package/dist/docs.json

@@ -142,9 +142,9 @@
               "name": "since"
             }
           ],
-          "docs": "Creation timestamp for coords",
+          "docs": "GNSS satellite timestamp for coords, in milliseconds since the Unix epoch.\n\nOn Android, this is populated only when a GNSS RMC NMEA message is available.\nOn iOS and web, this is always `null`.",
           "complexTypes": [],
-          "type": "number"
+          "type": "number | null"
         },
         {
           "name": "coords",
@@ -156,7 +156,7 @@
           ],
           "docs": "The GPS coordinates along with the accuracy of the data",
           "complexTypes": [],
-          "type": "{ latitude: number; longitude: number; accuracy: number; altitudeAccuracy: number | null | undefined; altitude: number | null; speed: number | null; heading: number | null; }"
+          "type": "{ latitude: number; longitude: number; accuracy: number; altitudeAccuracy: number | null | undefined; altitude: number | null; speed: number | null; heading: number | null; magneticHeading: number | null | undefined; trueHeading: number | null | undefined; headingAccuracy: number | null | undefined; course: number | null | undefined; isMock?: boolean | undefined; provider?: string | undefined; }"
         }
       ]
     },
@@ -195,7 +195,7 @@
               "name": "since"
             }
           ],
-          "docs": "The maximum wait time in milliseconds for location updates.\n\nIn Android, since version 7.1.0 of the plugin, it is also used to determine the\ninterval of location updates for `watchPosition`.",
+          "docs": "The maximum wait time in milliseconds for location updates.",
           "complexTypes": [],
           "type": "number | undefined"
         },
@@ -227,9 +227,41 @@
               "name": "since"
             }
           ],
-          "docs": "The minumum update interval for location updates.\n\nIf location updates are available faster than this interval then an update\nwill only occur if the minimum update interval has expired since the last location update.\n\nThis parameter is only available for Android. It has no effect on iOS or Web platforms.",
+          "docs": "The minimum update interval for `watchPosition`. Not to be confused with `interval`.\n\nIf location updates are available faster than this interval then an update\nwill only occur if the minimum update interval has expired since the last location update.\n\nThis parameter is only available for Android. It has no effect on iOS or Web platforms.",
           "complexTypes": [],
           "type": "number | undefined"
+        },
+        {
+          "name": "interval",
+          "tags": [
+            {
+              "text": "`timeout`",
+              "name": "default"
+            },
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Desired interval in milliseconds to receive location updates in `watchPosition`.\n\nFor very low values of `interval` (a couple seconds or less),\nthe platform may not guarantee timely location updates - they may take longer than specified.\nThe platform may also be able to provide location updates faster than `interval`.\nYou may use `minimumUpdateInterval` to control that behavior.\n\nFor backwards compatibility with version 7.1.x, if no value is passed,\nthe default value of this parameter is that of `timeout`.\n\nThis parameter is only available for Android. It has no effect on iOS or Web platforms.",
+          "complexTypes": [],
+          "type": "number | undefined"
+        },
+        {
+          "name": "enableLocationFallback",
+          "tags": [
+            {
+              "text": "true",
+              "name": "default"
+            },
+            {
+              "text": "8.0.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Whether to fall back to the Android framework's `LocationManager` in case Google Play Service's location settings checks fail.\nThis can happen for multiple reasons - e.g. device has no Play Services or device has no network connection (Airplane Mode)\nIf set to `false`, failures are propagated to the caller.\nNote that `LocationManager` may not be as effective as Google Play Services implementation.\nIf the device's in airplane mode, only the GPS provider is used, which may take longer to return a location, depending on GPS signal.\nThis means that to receive location in such circumstances, you may need to provide a higher timeout.\n\nThis parameter is only available for Android. It has no effect on iOS or Web platforms.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
         }
       ]
     },

package/dist/esm/definitions.d.ts

@@ -71,11 +71,14 @@ export interface ClearWatchOptions {
 }
 export interface Position {
     /**
-     * Creation timestamp for coords
+     * GNSS satellite timestamp for coords, in milliseconds since the Unix epoch.
+     *
+     * On Android, this is populated only when a GNSS RMC NMEA message is available.
+     * On iOS and web, this is always `null`.
      *
      * @since 1.0.0
      */
-    timestamp: number;
+    timestamp: number | null;
     /**
      * The GPS coordinates along with the accuracy of the data
      *
@@ -121,11 +124,60 @@ export interface Position {
          */
         speed: number | null;
         /**
-         * The heading the user is facing (if available)
+         * The heading the user is facing (if available).
+         *
+         * Historically, this field returned the direction of travel (course) on iOS and Android.
+         * It now prioritizes the compass heading (true or magnetic) if available, falling back
+         * to the direction of travel (course).
          *
          * @since 1.0.0
          */
         heading: number | null;
+        /**
+         * The heading (measured in degrees) relative to magnetic north.
+         *
+         * Only available when using `watchPosition`.
+         *
+         * @since 8.2.0
+         */
+        magneticHeading: number | null | undefined;
+        /**
+         * The heading (measured in degrees) relative to true north.
+         *
+         * Only available when using `watchPosition`.
+         *
+         * @since 8.2.0
+         */
+        trueHeading: number | null | undefined;
+        /**
+         * The maximum deviation (measured in degrees) between the reported heading and the true geomagnetic heading.
+         *
+         * Only available when using `watchPosition`.
+         *
+         * @since 8.2.0
+         */
+        headingAccuracy: number | null | undefined;
+        /**
+         * The direction in which the device is travelling, measured in degrees and relative to due north.
+         *
+         * Only available when using `watchPosition`.
+         *
+         * @since 8.2.0
+         */
+        course: number | null | undefined;
+        /**
+         * Whether the location was generated by a mock provider (e.g. a fake GPS app).
+         *
+         * On Android, available on API 31+ (uses `isMock()`), falls back to `isFromMockProvider()` on older versions.
+         * On iOS, detected via `CLLocationSourceInformation` on iOS 15+.
+         */
+        isMock?: boolean;
+        /**
+         * The location provider that generated this location (Android only).
+         *
+         * Common values: `"gps"`, `"network"`, `"fused"`.
+         */
+        provider?: string;
     };
 }
 export interface PositionOptions {
@@ -142,9 +194,6 @@ export interface PositionOptions {
     /**
      * The maximum wait time in milliseconds for location updates.
      *
-     * In Android, since version 7.1.0 of the plugin, it is also used to determine the
-     * interval of location updates for `watchPosition`.
-     *
      * @default 10000
      * @since 1.0.0
      */
@@ -157,7 +206,7 @@ export interface PositionOptions {
      */
     maximumAge?: number;
     /**
-     * The minumum update interval for location updates.
+     * The minimum update interval for `watchPosition`. Not to be confused with `interval`.
      *
      * If location updates are available faster than this interval then an update
      * will only occur if the minimum update interval has expired since the last location update.
@@ -168,6 +217,37 @@ export interface PositionOptions {
      * @since 6.1.0
      */
     minimumUpdateInterval?: number;
+    /**
+     * Desired interval in milliseconds to receive location updates in `watchPosition`.
+     *
+     * For very low values of `interval` (a couple seconds or less),
+     * the platform may not guarantee timely location updates - they may take longer than specified.
+     * The platform may also be able to provide location updates faster than `interval`.
+     * You may use `minimumUpdateInterval` to control that behavior.
+     *
+     * For backwards compatibility with version 7.1.x, if no value is passed,
+     * the default value of this parameter is that of `timeout`.
+     *
+     * This parameter is only available for Android. It has no effect on iOS or Web platforms.
+     *
+     * @default `timeout`
+     * @since 8.0.0
+     */
+    interval?: number;
+    /**
+     * Whether to fall back to the Android framework's `LocationManager` in case Google Play Service's location settings checks fail.
+     * This can happen for multiple reasons - e.g. device has no Play Services or device has no network connection (Airplane Mode)
+     * If set to `false`, failures are propagated to the caller.
+     * Note that `LocationManager` may not be as effective as Google Play Services implementation.
+     * If the device's in airplane mode, only the GPS provider is used, which may take longer to return a location, depending on GPS signal.
+     * This means that to receive location in such circumstances, you may need to provide a higher timeout.
+     *
+     * This parameter is only available for Android. It has no effect on iOS or Web platforms.
+     *
+     * @default true
+     * @since 8.0.0
+     */
+    enableLocationFallback?: boolean;
 }
 export type WatchPositionCallback = (position: Position | null, err?: any) => void;
 /**

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PermissionState } from '@capacitor/core';\n\nexport type CallbackID = string;\n\nexport interface PermissionStatus {\n  /**\n   * Permission state for location alias.\n   *\n   * On Android it requests/checks both ACCESS_COARSE_LOCATION and\n   * ACCESS_FINE_LOCATION permissions.\n   *\n   * On iOS and web it requests/checks location permission.\n   *\n   * @since 1.0.0\n   */\n  location: PermissionState;\n\n  /**\n   * Permission state for coarseLocation alias.\n   *\n   * On Android it requests/checks ACCESS_COARSE_LOCATION.\n   *\n   * On Android 12+, users can choose between Approximate location (ACCESS_COARSE_LOCATION) or\n   * Precise location (ACCESS_FINE_LOCATION), so this alias can be used if the app doesn't\n   * need high accuracy.\n   *\n   * On iOS and web it will have the same value as location alias.\n   *\n   * @since 1.2.0\n   */\n  coarseLocation: PermissionState;\n}\n\nexport type GeolocationPermissionType = 'location' | 'coarseLocation';\n\nexport interface GeolocationPluginPermissions {\n  permissions: GeolocationPermissionType[];\n}\n\nexport interface GeolocationPlugin {\n  /**\n   * Get the current GPS location of the device\n   *\n   * @since 1.0.0\n   */\n  getCurrentPosition(options?: PositionOptions): Promise<Position>;\n\n  /**\n   * Set up a watch for location changes. Note that watching for location changes\n   * can consume a large amount of energy. Be smart about listening only when you need to.\n   *\n   * @since 1.0.0\n   */\n  watchPosition(options: PositionOptions, callback: WatchPositionCallback): Promise<CallbackID>;\n\n  /**\n   * Clear a given watch\n   *\n   * @since 1.0.0\n   */\n  clearWatch(options: ClearWatchOptions): Promise<void>;\n\n  /**\n   * Check location permissions.  Will throw if system location services are disabled.\n   *\n   * @since 1.0.0\n   */\n  checkPermissions(): Promise<PermissionStatus>;\n\n  /**\n   * Request location permissions.  Will throw if system location services are disabled.\n   *\n   * Not available on web.\n   *\n   * @since 1.0.0\n   */\n  requestPermissions(permissions?: GeolocationPluginPermissions): Promise<PermissionStatus>;\n}\n\nexport interface ClearWatchOptions {\n  id: CallbackID;\n}\n\nexport interface Position {\n  /**\n   * Creation timestamp for coords\n   *\n   * @since 1.0.0\n   */\n  timestamp: number;\n\n  /**\n   * The GPS coordinates along with the accuracy of the data\n   *\n   * @since 1.0.0\n   */\n  coords: {\n    /**\n     * Latitude in decimal degrees\n     *\n     * @since 1.0.0\n     */\n    latitude: number;\n\n    /**\n     * longitude in decimal degrees\n     *\n     * @since 1.0.0\n     */\n    longitude: number;\n\n    /**\n     * Accuracy level of the latitude and longitude coordinates in meters\n     *\n     * @since 1.0.0\n     */\n    accuracy: number;\n\n    /**\n     * Accuracy level of the altitude coordinate in meters, if available.\n     *\n     * Available on all iOS versions and on Android 8.0+.\n     *\n     * @since 1.0.0\n     */\n    altitudeAccuracy: number | null | undefined;\n\n    /**\n     * The altitude the user is at (if available)\n     *\n     * @since 1.0.0\n     */\n    altitude: number | null;\n\n    /**\n     * The speed the user is traveling (if available)\n     *\n     * @since 1.0.0\n     */\n    speed: number | null;\n\n    /**\n     * The heading the user is facing (if available)\n     *\n     * @since 1.0.0\n     */\n    heading: number | null;\n  };\n}\n\nexport interface PositionOptions {\n  /**\n   * High accuracy mode (such as GPS, if available)\n   *\n   * On Android 12+ devices it will be ignored if users didn't grant\n   * ACCESS_FINE_LOCATION permissions (can be checked with location alias).\n   *\n   * @default false\n   * @since 1.0.0\n   */\n  enableHighAccuracy?: boolean;\n\n  /**\n   * The maximum wait time in milliseconds for location updates.\n   *\n   * In Android, since version 7.1.0 of the plugin, it is also used to determine the\n   * interval of location updates for `watchPosition`.\n   *\n   * @default 10000\n   * @since 1.0.0\n   */\n  timeout?: number;\n\n  /**\n   * The maximum age in milliseconds of a possible cached position that is acceptable to return\n   *\n   * @default 0\n   * @since 1.0.0\n   */\n  maximumAge?: number;\n\n  /**\n   * The minumum update interval for location updates.\n   *\n   * If location updates are available faster than this interval then an update\n   * will only occur if the minimum update interval has expired since the last location update.\n   *\n   * This parameter is only available for Android. It has no effect on iOS or Web platforms.\n   *\n   * @default 5000\n   * @since 6.1.0\n   */\n  minimumUpdateInterval?: number;\n}\n\nexport type WatchPositionCallback = (position: Position | null, err?: any) => void;\n\n/**\n * @deprecated Use `PositionOptions`.\n * @since 1.0.0\n */\nexport type GeolocationOptions = PositionOptions;\n\n/**\n * @deprecated Use `WatchPositionCallback`.\n * @since 1.0.0\n */\nexport type GeolocationWatchCallback = WatchPositionCallback;\n\n/**\n * @deprecated Use `Position`.\n * @since 1.0.0\n */\nexport type GeolocationPosition = Position;\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PermissionState } from '@capacitor/core';\n\nexport type CallbackID = string;\n\nexport interface PermissionStatus {\n  /**\n   * Permission state for location alias.\n   *\n   * On Android it requests/checks both ACCESS_COARSE_LOCATION and\n   * ACCESS_FINE_LOCATION permissions.\n   *\n   * On iOS and web it requests/checks location permission.\n   *\n   * @since 1.0.0\n   */\n  location: PermissionState;\n\n  /**\n   * Permission state for coarseLocation alias.\n   *\n   * On Android it requests/checks ACCESS_COARSE_LOCATION.\n   *\n   * On Android 12+, users can choose between Approximate location (ACCESS_COARSE_LOCATION) or\n   * Precise location (ACCESS_FINE_LOCATION), so this alias can be used if the app doesn't\n   * need high accuracy.\n   *\n   * On iOS and web it will have the same value as location alias.\n   *\n   * @since 1.2.0\n   */\n  coarseLocation: PermissionState;\n}\n\nexport type GeolocationPermissionType = 'location' | 'coarseLocation';\n\nexport interface GeolocationPluginPermissions {\n  permissions: GeolocationPermissionType[];\n}\n\nexport interface GeolocationPlugin {\n  /**\n   * Get the current GPS location of the device\n   *\n   * @since 1.0.0\n   */\n  getCurrentPosition(options?: PositionOptions): Promise<Position>;\n\n  /**\n   * Set up a watch for location changes. Note that watching for location changes\n   * can consume a large amount of energy. Be smart about listening only when you need to.\n   *\n   * @since 1.0.0\n   */\n  watchPosition(options: PositionOptions, callback: WatchPositionCallback): Promise<CallbackID>;\n\n  /**\n   * Clear a given watch\n   *\n   * @since 1.0.0\n   */\n  clearWatch(options: ClearWatchOptions): Promise<void>;\n\n  /**\n   * Check location permissions.  Will throw if system location services are disabled.\n   *\n   * @since 1.0.0\n   */\n  checkPermissions(): Promise<PermissionStatus>;\n\n  /**\n   * Request location permissions.  Will throw if system location services are disabled.\n   *\n   * Not available on web.\n   *\n   * @since 1.0.0\n   */\n  requestPermissions(permissions?: GeolocationPluginPermissions): Promise<PermissionStatus>;\n}\n\nexport interface ClearWatchOptions {\n  id: CallbackID;\n}\n\nexport interface Position {\n  /**\n   * GNSS satellite timestamp for coords, in milliseconds since the Unix epoch.\n   *\n   * On Android, this is populated only when a GNSS RMC NMEA message is available.\n   * On iOS and web, this is always `null`.\n   *\n   * @since 1.0.0\n   */\n  timestamp: number | null;\n\n  /**\n   * The GPS coordinates along with the accuracy of the data\n   *\n   * @since 1.0.0\n   */\n  coords: {\n    /**\n     * Latitude in decimal degrees\n     *\n     * @since 1.0.0\n     */\n    latitude: number;\n\n    /**\n     * longitude in decimal degrees\n     *\n     * @since 1.0.0\n     */\n    longitude: number;\n\n    /**\n     * Accuracy level of the latitude and longitude coordinates in meters\n     *\n     * @since 1.0.0\n     */\n    accuracy: number;\n\n    /**\n     * Accuracy level of the altitude coordinate in meters, if available.\n     *\n     * Available on all iOS versions and on Android 8.0+.\n     *\n     * @since 1.0.0\n     */\n    altitudeAccuracy: number | null | undefined;\n\n    /**\n     * The altitude the user is at (if available)\n     *\n     * @since 1.0.0\n     */\n    altitude: number | null;\n\n    /**\n     * The speed the user is traveling (if available)\n     *\n     * @since 1.0.0\n     */\n    speed: number | null;\n\n    /**\n     * The heading the user is facing (if available).\n     *\n     * Historically, this field returned the direction of travel (course) on iOS and Android.\n     * It now prioritizes the compass heading (true or magnetic) if available, falling back\n     * to the direction of travel (course).\n     *\n     * @since 1.0.0\n     */\n    heading: number | null;\n\n    /**\n     * The heading (measured in degrees) relative to magnetic north.\n     *\n     * Only available when using `watchPosition`.\n     *\n     * @since 8.2.0\n     */\n    magneticHeading: number | null | undefined;\n\n    /**\n     * The heading (measured in degrees) relative to true north.\n     *\n     * Only available when using `watchPosition`.\n     *\n     * @since 8.2.0\n     */\n    trueHeading: number | null | undefined;\n\n    /**\n     * The maximum deviation (measured in degrees) between the reported heading and the true geomagnetic heading.\n     *\n     * Only available when using `watchPosition`.\n     *\n     * @since 8.2.0\n     */\n    headingAccuracy: number | null | undefined;\n\n    /**\n     * The direction in which the device is travelling, measured in degrees and relative to due north.\n     *\n     * Only available when using `watchPosition`.\n     *\n     * @since 8.2.0\n     */\n    course: number | null | undefined;\n\n    /**\n     * Whether the location was generated by a mock provider (e.g. a fake GPS app).\n     *\n     * On Android, available on API 31+ (uses `isMock()`), falls back to `isFromMockProvider()` on older versions.\n     * On iOS, detected via `CLLocationSourceInformation` on iOS 15+.\n     */\n    isMock?: boolean;\n\n    /**\n     * The location provider that generated this location (Android only).\n     *\n     * Common values: `\"gps\"`, `\"network\"`, `\"fused\"`.\n     */\n    provider?: string;\n  };\n}\n\nexport interface PositionOptions {\n  /**\n   * High accuracy mode (such as GPS, if available)\n   *\n   * On Android 12+ devices it will be ignored if users didn't grant\n   * ACCESS_FINE_LOCATION permissions (can be checked with location alias).\n   *\n   * @default false\n   * @since 1.0.0\n   */\n  enableHighAccuracy?: boolean;\n\n  /**\n   * The maximum wait time in milliseconds for location updates.\n   *\n   * @default 10000\n   * @since 1.0.0\n   */\n  timeout?: number;\n\n  /**\n   * The maximum age in milliseconds of a possible cached position that is acceptable to return\n   *\n   * @default 0\n   * @since 1.0.0\n   */\n  maximumAge?: number;\n\n  /**\n   * The minimum update interval for `watchPosition`. Not to be confused with `interval`.\n   *\n   * If location updates are available faster than this interval then an update\n   * will only occur if the minimum update interval has expired since the last location update.\n   *\n   * This parameter is only available for Android. It has no effect on iOS or Web platforms.\n   *\n   * @default 5000\n   * @since 6.1.0\n   */\n  minimumUpdateInterval?: number;\n\n  /**\n   * Desired interval in milliseconds to receive location updates in `watchPosition`.\n   *\n   * For very low values of `interval` (a couple seconds or less),\n   * the platform may not guarantee timely location updates - they may take longer than specified.\n   * The platform may also be able to provide location updates faster than `interval`.\n   * You may use `minimumUpdateInterval` to control that behavior.\n   *\n   * For backwards compatibility with version 7.1.x, if no value is passed,\n   * the default value of this parameter is that of `timeout`.\n   *\n   * This parameter is only available for Android. It has no effect on iOS or Web platforms.\n   *\n   * @default `timeout`\n   * @since 8.0.0\n   */\n  interval?: number;\n\n  /**\n   * Whether to fall back to the Android framework's `LocationManager` in case Google Play Service's location settings checks fail.\n   * This can happen for multiple reasons - e.g. device has no Play Services or device has no network connection (Airplane Mode)\n   * If set to `false`, failures are propagated to the caller.\n   * Note that `LocationManager` may not be as effective as Google Play Services implementation.\n   * If the device's in airplane mode, only the GPS provider is used, which may take longer to return a location, depending on GPS signal.\n   * This means that to receive location in such circumstances, you may need to provide a higher timeout.\n   *\n   * This parameter is only available for Android. It has no effect on iOS or Web platforms.\n   *\n   * @default true\n   * @since 8.0.0\n   */\n  enableLocationFallback?: boolean;\n}\n\nexport type WatchPositionCallback = (position: Position | null, err?: any) => void;\n\n/**\n * @deprecated Use `PositionOptions`.\n * @since 1.0.0\n */\nexport type GeolocationOptions = PositionOptions;\n\n/**\n * @deprecated Use `WatchPositionCallback`.\n * @since 1.0.0\n */\nexport type GeolocationWatchCallback = WatchPositionCallback;\n\n/**\n * @deprecated Use `Position`.\n * @since 1.0.0\n */\nexport type GeolocationPosition = Position;\n"]}

package/dist/esm/web.d.ts

@@ -1,6 +1,10 @@
 import { WebPlugin } from '@capacitor/core';
 import type { CallbackID, GeolocationPlugin, PermissionStatus, Position, PositionOptions, WatchPositionCallback } from './definitions';
 export declare class GeolocationWeb extends WebPlugin implements GeolocationPlugin {
+    private latestOrientation;
+    constructor();
+    private updateOrientation;
+    private augmentPosition;
     getCurrentPosition(options?: PositionOptions): Promise<Position>;
     watchPosition(options: PositionOptions, callback: WatchPositionCallback): Promise<CallbackID>;
     clearWatch(options: {