@nitra/geolocation 7.1.6 → 8.2.0

package/NitraGeolocation.podspec

@@ -9,10 +9,10 @@ Pod::Spec.new do |s|
   s.license = package['license']
   s.homepage = package['repository']['url']
   s.author = package['author']
-  s.source = { :git => package['repository']['url'], :tag => s.version.to_s }
+  s.source = { :git => package['repository']['url'], :tag => "v#{s.version}" }
   s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
-  s.ios.deployment_target = '14.0'
+  s.ios.deployment_target = '15.0'
   s.dependency 'Capacitor'
-  s.dependency 'IONGeolocationLib', spec='~> 1.0'
+  s.dependency 'IONGeolocationLib', '>= 2.1.0'
   s.swift_version = '5.1'
 end

package/Package.swift

@@ -2,28 +2,24 @@
 import PackageDescription
 
 let package = Package(
-    name: "GeolocationCapacitor",
-    platforms: [.iOS(.v13)],
+    name: "CapacitorGeolocation",
+    platforms: [.iOS(.v15)],
     products: [
         .library(
-            name: "GeolocationCapacitor",
+            name: "CapacitorGeolocation",
             targets: ["GeolocationPlugin"])
     ],
     dependencies: [
-        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "7.0.0")
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0"),
+        .package(url: "https://github.com/ionic-team/ion-ios-geolocation.git", from: "2.1.0")
     ],
     targets: [
-        .binaryTarget(
-            name: "IONGeolocationLib",
-            url: "https://github.com/ionic-team/ion-ios-geolocation/releases/download/1.0.0/IONGeolocationLib.zip",
-            checksum: "b117d3681a947f5d367e79abdb3bfc9abf7ab070ea5279d7da634ddd2d54ffdb" // sha-256
-        ),
         .target(
             name: "GeolocationPlugin",
             dependencies: [
                 .product(name: "Capacitor", package: "capacitor-swift-pm"),
                 .product(name: "Cordova", package: "capacitor-swift-pm"),
-                "IONGeolocationLib"
+                .product(name: "IONGeolocationLib", package: "ion-ios-geolocation")
             ],
             path: "ios/Sources/GeolocationPlugin"),
         .testTarget(

package/README.md

@@ -16,6 +16,17 @@ Apple requires privacy descriptions to be specified in `Info.plist` for location
 - `NSLocationAlwaysAndWhenInUseUsageDescription` (`Privacy - Location Always and When In Use Usage Description`)
 - `NSLocationWhenInUseUsageDescription` (`Privacy - Location When In Use Usage Description`)
 
+:::info[Background Location Usage Strings]
+
+This Capacitor plugin does not support background geolocation directly. However, it relies on
+[`ion-ios-geolocation`](https://github.com/ionic-team/ion-ios-geolocation), which can report
+location in the background. As a result, Apple requires you to include a
+`NSLocationAlwaysAndWhenInUseUsageDescription` entry in your `Info.plist`. Since this permission
+prompt won’t appear to users, you can safely use the same description string as for
+`NSLocationWhenInUseUsageDescription`.
+
+:::info
+
 Read about [Configuring `Info.plist`](https://capacitorjs.com/docs/ios/configuration#configuring-infoplist) in the [iOS Guide](https://capacitorjs.com/docs/ios) for more information on setting iOS permissions in Xcode
 
 ## Android
@@ -31,9 +42,85 @@ This plugin requires the following permissions be added to your `AndroidManifest
 
 The first two permissions ask for location data, both fine and coarse, and the last line is optional but necessary if your app _requires_ GPS to function. You may leave it out, though keep in mind that this may mean your app is installed on devices lacking GPS hardware.
 
+:::note
+
+If you only require approximate location (variable accuracy but usually around 2 kilometers), you may just declare `ACCESS_COARSE_LOCATION` and `<uses-feature`, and use `enableHighAccuracy=false` when requesting location
+
+:::note
+
 Read about [Setting Permissions](https://capacitorjs.com/docs/android/configuration#setting-permissions) in the [Android Guide](https://capacitorjs.com/docs/android) for more information on setting Android permissions.
 
 
+## Running the Example App
+
+The `example-app` directory contains a Capacitor app for testing the plugin locally. It references the plugin via `file:../`, so any changes you build are immediately reflected.
+
+### 1. Build the plugin
+
+From the repo root:
+
+```bash
+npm install
+npm run build
+```
+
+### 2. Install example app dependencies
+
+```bash
+cd example-app
+npm install
+npm run build
+```
+
+### 3. Android
+
+```bash
+npx cap sync android
+npx cap run android
+```
+
+Or open in Android Studio:
+
+```bash
+npx cap open android
+```
+
+### 4. iOS
+
+The iOS plugin depends on [`ion-ios-geolocation`](https://github.com/nitra/ion-ios-geolocation). Clone it as `ios-lib` inside the repo root:
+
+```bash
+git clone https://github.com/nitra/ion-ios-geolocation ios-lib
+```
+
+Since `IONGeolocationLib` is not yet published to the public CocoaPods registry, uncomment the local pod path in `example-app/ios/App/Podfile` for local development:
+
+```ruby
+pod 'IONGeolocationLib', :path => '../../../ios-lib'
+```
+
+> **Note:** `ios-lib` is not committed — clone it manually. Do not commit the uncommented line.
+
+Sync and open in Xcode:
+
+```bash
+npx cap sync ios
+npx cap open ios
+```
+
+In Xcode, select your **Team** under **Signing & Capabilities** for the `App` target, then run on a device or simulator.
+
+### After plugin changes
+
+Every time you modify the plugin source, rebuild and re-sync before running:
+
+```bash
+# from repo root:
+npm run build
+# from example-app:
+npx cap sync android   # or ios
+```
+
 ## API
 
 <docgen-index>
@@ -151,20 +238,22 @@ Not available on web.
 
 #### Position
 
-| Prop            | Type                                                                                                                                                                                | Description                                             | Since |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ----- |
-| **`timestamp`** | <code>number</code>                                                                                                                                                                 | Creation timestamp for coords                           | 1.0.0 |
-| **`coords`**    | <code>{ latitude: number; longitude: number; accuracy: number; altitudeAccuracy: number \| null; altitude: number \| null; speed: number \| null; heading: number \| null; }</code> | The GPS coordinates along with the accuracy of the data | 1.0.0 |
+| Prop            | Type                                                                                                                                                                                                                                                                                                                                            | Description                                                                                                                                                                                     | Since |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| **`timestamp`** | <code>number \| null</code>                                                                                                                                                                                                                                                                                                                     | 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`. | 1.0.0 |
+| **`coords`**    | <code>{ latitude: number; longitude: number; accuracy: number; altitudeAccuracy: number \| null; altitude: number \| null; speed: number \| null; heading: number \| null; magneticHeading: number \| null; trueHeading: number \| null; headingAccuracy: number \| null; course: number \| null; isMock?: boolean; provider?: string; }</code> | The GPS coordinates along with the accuracy of the data                                                                                                                                         | 1.0.0 |
 
 
 #### PositionOptions
 
-| Prop                        | Type                 | Description                                                                                                                                                                                                                                                                                                     | Default            | Since |
-| --------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- |
-| **`enableHighAccuracy`**    | <code>boolean</code> | High accuracy mode (such as GPS, if available) On Android 12+ devices it will be ignored if users didn't grant ACCESS_FINE_LOCATION permissions (can be checked with location alias).                                                                                                                           | <code>false</code> | 1.0.0 |
-| **`timeout`**               | <code>number</code>  | 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`.                                                                                                                   | <code>10000</code> | 1.0.0 |
-| **`maximumAge`**            | <code>number</code>  | The maximum age in milliseconds of a possible cached position that is acceptable to return                                                                                                                                                                                                                      | <code>0</code>     | 1.0.0 |
-| **`minimumUpdateInterval`** | <code>number</code>  | The minumum update interval for location updates. 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. This parameter is only available for Android. It has no effect on iOS or Web platforms. | <code>5000</code>  | 6.1.0 |
+| Prop                         | Type                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Default                | Since |
+| ---------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ----- |
+| **`enableHighAccuracy`**     | <code>boolean</code> | High accuracy mode (such as GPS, if available) On Android 12+ devices it will be ignored if users didn't grant ACCESS_FINE_LOCATION permissions (can be checked with location alias).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | <code>false</code>     | 1.0.0 |
+| **`timeout`**                | <code>number</code>  | The maximum wait time in milliseconds for location updates.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | <code>10000</code>     | 1.0.0 |
+| **`maximumAge`**             | <code>number</code>  | The maximum age in milliseconds of a possible cached position that is acceptable to return                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | <code>0</code>         | 1.0.0 |
+| **`minimumUpdateInterval`**  | <code>number</code>  | 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. This parameter is only available for Android. It has no effect on iOS or Web platforms.                                                                                                                                                                                                                                                                                                                                                                                                  | <code>5000</code>      | 6.1.0 |
+| **`interval`**               | <code>number</code>  | 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.                                                                                                                               | <code>`timeout`</code> | 8.0.0 |
+| **`enableLocationFallback`** | <code>boolean</code> | 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. | <code>true</code>      | 8.0.0 |
 
 
 #### ClearWatchOptions
@@ -229,10 +318,12 @@ The following table list all the plugin errors:
 | OS-PLUG-GLOC-0007 | Android, iOS | Location services are not enabled. |
 | OS-PLUG-GLOC-0008 | iOS          | Application's use of location services was restricted. |
 | OS-PLUG-GLOC-0009 | Android      | Request to enable location was denied. |
-| OS-PLUG-GLOC-0010 | Android      | Could not obtain location in time. Try with a higher timeout. |
+| OS-PLUG-GLOC-0010 | Android, iOS | Could not obtain location in time. Try with a higher timeout. |
 | OS-PLUG-GLOC-0011 | Android      | Timeout needs to be a positive value. |
 | OS-PLUG-GLOC-0012 | Android      | WatchId not found. |
 | OS-PLUG-GLOC-0013 | Android      | WatchId needs to be provided. |
 | OS-PLUG-GLOC-0014 | Android      | Google Play Services error user resolvable. |
 | OS-PLUG-GLOC-0015 | Android      | Google Play Services error. |
 | OS-PLUG-GLOC-0016 | Android      | Location settings error. |
+| OS-PLUG-GLOC-0017 | Android      | Unable to retrieve location because device has both Network and Location turned off. |
+| OS-PLUG-GLOC-0018 | Android      | Location permissions are not declared in manifest. Make sure at least ACCESS_COARSE_LOCATION is declared in AndroidManifest.xml, and optionally ACCESS_FINE_LOCATION if you require precise location access. |

package/android/build.gradle

@@ -1,32 +1,54 @@
-ext {
-    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
-    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.0'
-    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.2.1'
-    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.6.1'
-    playServicesLocationVersion = project.hasProperty('playServicesLocationVersion') ? rootProject.ext.playServicesLocationVersion : '21.3.0'
-}
-
 buildscript {
-    ext.kotlin_version = project.hasProperty("kotlin_version") ? rootProject.ext.kotlin_version : '1.9.24'
+    ext.kotlin_version = project.hasProperty("kotlin_version") ? rootProject.ext.kotlin_version : '2.2.20'
     repositories {
         google()
         mavenCentral()
+        maven {
+            url = "https://plugins.gradle.org/m2/"
+        }
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:8.7.1'
+        classpath 'com.android.tools.build:gradle:8.13.0'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+        if (System.getenv("CAP_PLUGIN_PUBLISH") == "true") {
+            classpath 'io.github.gradle-nexus:publish-plugin:1.3.0'
+        }
     }
 }
 
 apply plugin: 'com.android.library'
-apply plugin: 'kotlin-android'
+
+// AGP 9 (used by host apps such as the example app) bundles Kotlin and already
+// registers the `kotlin` extension when the Android plugin is applied. Older AGP
+// (8.13, used for the standalone Maven publish build) does not, so apply the
+// Kotlin plugin only when it is missing — applying it twice fails with
+// "extension with name 'kotlin' already registered".
+if (project.extensions.findByName('kotlin') == null) {
+    apply plugin: 'kotlin-android'
+}
+
+ext {
+    capacitorVersion = System.getenv('CAPACITOR_VERSION')
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
+    playServicesLocationVersion = project.hasProperty('playServicesLocationVersion') ? rootProject.ext.playServicesLocationVersion : '21.3.0'
+    kotlinxCoroutinesVersion = project.hasProperty('kotlinxCoroutinesVersion') ? rootProject.ext.kotlinxCoroutinesVersion : '1.10.2'
+}
+
+if (System.getenv("CAP_PLUGIN_PUBLISH") == "true") {
+    apply plugin: 'io.github.gradle-nexus.publish-plugin'
+    apply from: file('../scripts/android/publish-root.gradle')
+    apply from: file('../scripts/android/publish-module.gradle')
+}
 
 android {
-    namespace "com.capacitorjs.plugins.geolocation"
-    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 35
+    namespace = "com.capacitorjs.plugins.geolocation"
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
     defaultConfig {
-        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
-        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 35
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 28
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
         versionCode 1
         versionName "1.0"
         testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
@@ -34,16 +56,19 @@ android {
     buildTypes {
         release {
             minifyEnabled false
-            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
         }
     }
     lintOptions {
-        abortOnError false
+        abortOnError = false
     }
     compileOptions {
         sourceCompatibility JavaVersion.VERSION_21
         targetCompatibility JavaVersion.VERSION_21
     }
+    publishing {
+        singleVariant("release")
+    }
 }
 
 kotlin {
@@ -59,13 +84,17 @@ repositories {
 
 dependencies {
     implementation fileTree(dir: 'libs', include: ['*.jar'])
-	implementation 'com.github.nitra:ion-android-geolocation:fake-SNAPSHOT'    
-    
-    implementation project(':capacitor-android')
+    implementation 'com.github.nitra:ion-android-geolocation:fake-SNAPSHOT'
+
+    if (System.getenv("CAP_PLUGIN_PUBLISH") == "true") {
+        implementation "com.capacitorjs:core:$capacitorVersion"
+    } else {
+        implementation project(':capacitor-android')
+    }
     implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
 
-    implementation 'com.google.code.gson:gson:2.10.1'
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-play-services:1.6.4")
+    implementation 'com.google.code.gson:gson:2.13.2'
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-play-services:$kotlinxCoroutinesVersion")
     implementation "com.google.android.gms:play-services-location:$playServicesLocationVersion"
 
     testImplementation "junit:junit:$junitVersion"

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

@@ -68,4 +68,14 @@ object GeolocationErrors {
         code = formatErrorCode(16),
         message = "Location settings error."
     )
+
+    val NETWORK_LOCATION_DISABLED_ERROR = ErrorInfo(
+        code = formatErrorCode(17),
+        message = "Unable to retrieve location because device has both Network and Location turned off."
+    )
+
+    val LOCATION_MANIFEST_PERMISSIONS_MISSING = ErrorInfo(
+        code = formatErrorCode(18),
+        message = "Location permissions are not declared in manifest. Make sure at least ACCESS_COARSE_LOCATION is declared in AndroidManifest.xml, and optionally ACCESS_FINE_LOCATION if you require precise location access."
+    )
 }