{"id":13514852,"url":"https://github.com/capacitor-community/background-geolocation","last_synced_at":"2025-04-04T21:06:14.617Z","repository":{"id":40447038,"uuid":"311601369","full_name":"capacitor-community/background-geolocation","owner":"capacitor-community","description":"A Capacitor plugin that sends you geolocation updates, even while the app is in the background.","archived":false,"fork":false,"pushed_at":"2024-03-05T23:48:31.000Z","size":671,"stargazers_count":168,"open_issues_count":11,"forks_count":51,"subscribers_count":23,"default_branch":"master","last_synced_at":"2024-04-27T07:24:20.333Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/capacitor-community.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-10T09:00:57.000Z","updated_at":"2024-06-19T03:03:01.942Z","dependencies_parsed_at":"2024-01-02T23:09:21.215Z","dependency_job_id":"5e9b9be2-20cd-4a0c-88c1-9fc2ebaf840c","html_url":"https://github.com/capacitor-community/background-geolocation","commit_stats":{"total_commits":110,"total_committers":2,"mean_commits":55.0,"dds":0.009090909090909038,"last_synced_commit":"04a9caeab47027e2f384133d629b002713dcc606"},"previous_names":["diachedelic/capacitor-background-geolocation"],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capacitor-community%2Fbackground-geolocation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capacitor-community%2Fbackground-geolocation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capacitor-community%2Fbackground-geolocation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/capacitor-community%2Fbackground-geolocation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/capacitor-community","download_url":"https://codeload.github.com/capacitor-community/background-geolocation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247249524,"owners_count":20908212,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T05:01:02.712Z","updated_at":"2025-04-04T21:06:14.593Z","avatar_url":"https://github.com/capacitor-community.png","language":"Java","funding_links":[],"categories":["Java","Plugins","Community plugins"],"sub_categories":["Community Plugins"],"readme":"# Background Geolocation\nA Capacitor plugin that lets you receive geolocation updates even while the app is backgrounded. Only iOS and Android platforms are supported.\n\n## Usage\n\n```javascript\nimport {registerPlugin} from \"@capacitor/core\";\nconst BackgroundGeolocation = registerPlugin(\"BackgroundGeolocation\");\n\n// To start listening for changes in the device's location, add a new watcher.\n// You do this by calling 'addWatcher' with an options object and a callback. A\n// Promise is returned, which resolves to the callback ID used to remove the\n// watcher in the future. The callback will be called every time a new location\n// is available. Watchers can not be paused, only removed. Multiple watchers may\n// exist simultaneously.\nBackgroundGeolocation.addWatcher(\n    {\n        // If the \"backgroundMessage\" option is defined, the watcher will\n        // provide location updates whether the app is in the background or the\n        // foreground. If it is not defined, location updates are only\n        // guaranteed in the foreground. This is true on both platforms.\n\n        // On Android, a notification must be shown to continue receiving\n        // location updates in the background. This option specifies the text of\n        // that notification.\n        backgroundMessage: \"Cancel to prevent battery drain.\",\n\n        // The title of the notification mentioned above. Defaults to \"Using\n        // your location\".\n        backgroundTitle: \"Tracking You.\",\n        \n        // Whether permissions should be requested from the user automatically,\n        // if they are not already granted. Defaults to \"true\".\n        requestPermissions: true,\n\n        // If \"true\", stale locations may be delivered while the device\n        // obtains a GPS fix. You are responsible for checking the \"time\"\n        // property. If \"false\", locations are guaranteed to be up to date.\n        // Defaults to \"false\".\n        stale: false,\n\n        // The minimum number of metres between subsequent locations. Defaults\n        // to 0.\n        distanceFilter: 50\n    },\n    function callback(location, error) {\n        if (error) {\n            if (error.code === \"NOT_AUTHORIZED\") {\n                if (window.confirm(\n                    \"This app needs your location, \" +\n                    \"but does not have permission.\\n\\n\" +\n                    \"Open settings now?\"\n                )) {\n                    // It can be useful to direct the user to their device's\n                    // settings when location permissions have been denied. The\n                    // plugin provides the 'openSettings' method to do exactly\n                    // this.\n                    BackgroundGeolocation.openSettings();\n                }\n            }\n            return console.error(error);\n        }\n\n        return console.log(location);\n    }\n).then(function after_the_watcher_has_been_added(watcher_id) {\n    // When a watcher is no longer needed, it should be removed by calling\n    // 'removeWatcher' with an object containing its ID.\n    BackgroundGeolocation.removeWatcher({\n        id: watcher_id\n    });\n});\n\n// The location object.\n{\n    // Longitude in degrees.\n    longitude: 131.723423719132,\n    // Latitude in degrees.\n    latitude: -22.40106297456,\n    // Radius of horizontal uncertainty in metres, with 68% confidence.\n    accuracy: 11,\n    // Metres above sea level (or null).\n    altitude: 65,\n    // Vertical uncertainty in metres, with 68% confidence (or null).\n    altitudeAccuracy: 4,\n    // Deviation from true north in degrees (or null).\n    bearing: 159.60000610351562,\n    // True if the location was simulated by software, rather than GPS.\n    simulated: false,\n    // Speed in metres per second (or null).\n    speed: 23.51068878173828,\n    // Time the location was produced, in milliseconds since the unix epoch.\n    time: 1562731602000\n}\n\n// If you just want the current location, try something like this. The longer\n// the timeout, the more accurate the guess will be. I wouldn't go below about\n// 100ms.\nfunction guess_location(callback, timeout) {\n    let last_location;\n    BackgroundGeolocation.addWatcher(\n        {\n            requestPermissions: false,\n            stale: true\n        },\n        function (location) {\n            last_location = location || undefined;\n        }\n    ).then(function (id) {\n        setTimeout(function () {\n            callback(last_location);\n            Plugins.BackgroundGeolocation.removeWatcher({id});\n        }, timeout);\n    });\n}\n```\n\n### Typescript support\n\n```typescript\nimport {BackgroundGeolocationPlugin} from \"@capacitor-community/background-geolocation\";\nconst BackgroundGeolocation = registerPlugin\u003cBackgroundGeolocationPlugin\u003e(\"BackgroundGeolocation\");\n```\n\n## Installation\n\nDifferent versions of the plugin support different versions of Capacitor:\n\n| Capacitor  | Plugin |\n|------------|--------|\n| v2         | v0.3   |\n| v3         | v1     |\n| v4         | v1     |\n| v5         | v1     |\n| v6         | v1     |\n| v7         | v1     |\n\nRead the documentation for v0.3 [here](https://github.com/capacitor-community/background-geolocation/tree/0.3.x).\n\n```sh\nnpm install @capacitor-community/background-geolocation\nnpx cap update\n```\n\n### iOS\nAdd the following keys to `Info.plist.`:\n\n```xml\n\u003cdict\u003e\n  ...\n  \u003ckey\u003eNSLocationWhenInUseUsageDescription\u003c/key\u003e\n  \u003cstring\u003eWe need to track your location\u003c/string\u003e\n  \u003ckey\u003eNSLocationAlwaysAndWhenInUseUsageDescription\u003c/key\u003e\n  \u003cstring\u003eWe need to track your location while your device is locked.\u003c/string\u003e\n  \u003ckey\u003eUIBackgroundModes\u003c/key\u003e\n  \u003carray\u003e\n    \u003cstring\u003elocation\u003c/string\u003e\n  \u003c/array\u003e\n  ...\n\u003c/dict\u003e\n```\n\n### Android\n\nSet the the `android.useLegacyBridge` option to `true` in your Capacitor configuration. This prevents location updates halting after 5 minutes in the background. See https://capacitorjs.com/docs/config and https://github.com/capacitor-community/background-geolocation/issues/89.\n\nOn Android 13+, the app needs the `POST_NOTIFICATIONS` runtime permission to show the persistent notification informing the user that their location is being used in the background. You may need to [request this permission](https://developer.android.com/develop/ui/views/notifications/notification-permission) from the user, this can be accomplished [using the `@capacitor/local-notifications` plugin](https://capacitorjs.com/docs/apis/local-notifications#checkpermissions).\n\nIf your app forwards location updates to a server in real time, be aware that after 5 minutes in the background Android will throttle HTTP requests initiated from the WebView. The solution is to use a native HTTP plugin such as [CapacitorHttp](https://capacitorjs.com/docs/apis/http). See https://github.com/capacitor-community/background-geolocation/issues/14.\n\nConfigration specific to Android can be made in `strings.xml`:\n```xml\n\u003cresources\u003e\n    \u003c!--\n        The channel name for the background notification. This will be visible\n        when the user presses \u0026 holds the notification. It defaults to\n        \"Background Tracking\".\n    --\u003e\n    \u003cstring name=\"capacitor_background_geolocation_notification_channel_name\"\u003e\n        Background Tracking\n    \u003c/string\u003e\n\n    \u003c!--\n        The icon to use for the background notification. Note the absence of a\n        leading \"@\". It defaults to \"mipmap/ic_launcher\", the app's launch icon.\n\n        If a raster image is used to generate the icon (as opposed to a vector\n        image), it must have a transparent background. To make sure your image\n        is compatible, select \"Notification Icons\" as the Icon Type when\n        creating the image asset in Android Studio.\n    --\u003e\n    \u003cstring name=\"capacitor_background_geolocation_notification_icon\"\u003e\n        drawable/ic_tracking\n    \u003c/string\u003e\n\n    \u003c!--\n        The color of the notification as a string parseable by\n        android.graphics.Color.parseColor. Optional.\n    --\u003e\n    \u003cstring name=\"capacitor_background_geolocation_notification_color\"\u003e\n        yellow\n    \u003c/string\u003e\n\u003c/resources\u003e\n\n```\n\n## Changelog\n\n### v1.2.22\n- Avoid interfering with safe area insets on Android\n\n### v1.2.21\n- Customize the notification color on Android.\n\n### v1.2.19\n- Fix a bug preventing the foreground service starting on Android.\n\n### v1.2.18\n- Always show the notification when a background watcher exists, improving the reliability of location updates on Android.\n\n### v1.2.17\n- Adds support for Capacitor v6.\n\n### v1.2.16\n- Fixes background location updates for Android 14.\n\n### v1.2.14\n- Adds support for Capacitor v5.\n\n### v1.2.3\n- Adds support for Capacitor v4.\n\n### v1.2.2\n- Prevents location updates from halting on iOS due to extended inactivity.\n\n### v1.2.1\n- Fixes background location updates for some devices running Android 12.\n\n### v1.2.0\n- On iOS, the status bar now turns blue whilst the location is being watched in the background. This provides the user a straightforward way to return to the app.\n\n### v1.0.4\n- Adds the `ACCESS_COARSE_LOCATION` permission. This is required for apps that target Android 12 (API level 31). A preceeding example shows how to add this permission to your app's manifest.\n\n### v1.0.0\n- BREAKING: `addWatcher` now returns a Promise that resolves to the callback ID, rather than the callback ID itself.\n- BREAKING: The plugin is imported via Capacitor's `registerPlugin` function, rather than from the `Plugins` object.\n- BREAKING: Drops support for iOS v11 and Capacitor v2.\n- Adds support for Capacitor v3.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapacitor-community%2Fbackground-geolocation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcapacitor-community%2Fbackground-geolocation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcapacitor-community%2Fbackground-geolocation/lists"}