{"id":13800834,"url":"https://github.com/transistorsoft/capacitor-background-geolocation","last_synced_at":"2025-05-13T10:30:43.436Z","repository":{"id":37472830,"uuid":"190391218","full_name":"transistorsoft/capacitor-background-geolocation","owner":"transistorsoft","description":"The most sophisticated background location-tracking \u0026 geofencing module with battery-conscious motion-detection intelligence for iOS and Android.","archived":false,"fork":false,"pushed_at":"2025-03-31T14:32:42.000Z","size":393109,"stargazers_count":105,"open_issues_count":12,"forks_count":18,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-05-08T12:44:31.879Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/transistorsoft.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2019-06-05T12:34:07.000Z","updated_at":"2025-04-15T23:17:19.000Z","dependencies_parsed_at":"2023-02-18T13:01:09.944Z","dependency_job_id":"6fa1acea-ae9d-4705-90a5-11635a4aa97d","html_url":"https://github.com/transistorsoft/capacitor-background-geolocation","commit_stats":{"total_commits":168,"total_committers":2,"mean_commits":84.0,"dds":"0.45238095238095233","last_synced_commit":"b26d04e61b5d9c3e2df59941c2d8fe8c99185b44"},"previous_names":[],"tags_count":61,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transistorsoft%2Fcapacitor-background-geolocation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transistorsoft%2Fcapacitor-background-geolocation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transistorsoft%2Fcapacitor-background-geolocation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transistorsoft%2Fcapacitor-background-geolocation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/transistorsoft","download_url":"https://codeload.github.com/transistorsoft/capacitor-background-geolocation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253922790,"owners_count":21984780,"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-04T00:01:16.751Z","updated_at":"2025-05-13T10:30:39.070Z","avatar_url":"https://github.com/transistorsoft.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","JavaScript","[Transistor Software plugins](https://www.transistorsoft.com//)"],"sub_categories":["Specialized Hardware"],"readme":"Background Geolocation for Capacitor \u0026middot; [![npm](https://img.shields.io/npm/dm/@transistorsoft/capacitor-background-geolocation.svg)]() [![npm](https://img.shields.io/npm/v/@transistorsoft/capacitor-background-geolocation.svg)]()\n============================================================================\n\n[![](https://dl.dropboxusercontent.com/s/nm4s5ltlug63vv8/logo-150-print.png?dl=1)](https://www.transistorsoft.com)\n\n-------------------------------------------------------------------------------\n\nThe *most* sophisticated background **location-tracking \u0026 geofencing** module with battery-conscious motion-detection intelligence for **iOS** and **Android**.\n\nThe plugin's [Philosophy of Operation](../../wiki/Philosophy-of-Operation) is to use **motion-detection** APIs (using accelerometer, gyroscope and magnetometer) to detect when the device is *moving* and *stationary*.\n\n- When the device is detected to be **moving**, the plugin will *automatically* start recording a location according to the configured `distanceFilter` (meters).\n\n- When the device is detected be **stationary**, the plugin will automatically turn off location-services to conserve energy.\n\nAlso available for [Flutter](https://github.com/transistorsoft/flutter_background_geolocation), [Cordova](https://github.com/transistorsoft/cordova-background-geolocation-lt), and [React Native](https://github.com/transistorsoft/capacitor-background-geolocation).\n\n----------------------------------------------------------------------------\n\nThe **[Android module](http://www.transistorsoft.com/shop/products/capacitor-background-geolocation)** requires [purchasing a license](http://www.transistorsoft.com/shop/products/capacitor-background-geolocation).  However, it *will* work for **DEBUG** builds.  It will **not** work with **RELEASE** builds [without purchasing a license](http://www.transistorsoft.com/shop/products/capacitor-background-geolocation).\n\n(2018) This plugin is supported **full-time** and field-tested **daily** since 2013.\n\n----------------------------------------------------------------------------\n\n[![Google Play](https://dl.dropboxusercontent.com/s/80rf906x0fheb26/google-play-icon.png?dl=1)](https://play.google.com/store/apps/details?id=com.transistorsoft.backgroundgeolocation.react)\n\n![Home](https://dl.dropboxusercontent.com/s/wa43w1n3xhkjn0i/home-framed-350.png?dl=1)\n![Settings](https://dl.dropboxusercontent.com/s/8oad228siog49kt/settings-framed-350.png?dl=1)\n\n\u003e ### :rotating_light: This plugin requires Capacitor 5 :rotating_light:\n\u003e\n\u003e For Capacitor 4, use the 4.x version of the plugin.\n\n# Contents\n- ### 😫 [Help!](../../wiki/Help)\n- ### :books: [API Documentation](https://transistorsoft.github.io/capacitor-background-geolocation)\n- ### [Installing the Plugin](#large_blue_diamond-installing-the-plugin)\n- ### [Setup Guides](#large_blue_diamond-setup-guides)\n- ### [Configure your License](#large_blue_diamond-configure-your-license)\n- ### [Using the plugin](#large_blue_diamond-using-the-plugin)\n- ### [Example](#large_blue_diamond-example)\n- ### [Debugging](../../wiki/Debugging)\n- ### [Demo Application](#large_blue_diamond-demo-application)\n- ### [Testing Server](#large_blue_diamond-simple-testing-server)\n- ### [Privacy Policy](help/PRIVACY_POLICY.md)\n\n## :large_blue_diamond: Installing the Plugin\n\n:warning: Capacitor 3+ required.\n\n### With `yarn`\n\n```bash\n$ yarn add @transistorsoft/capacitor-background-geolocation\n$ yarn add @transistorsoft/capacitor-background-fetch\n$ npx cap sync\n```\n\n### With `npm`\n```console\n$ npm install @transistorsoft/capacitor-background-geolocation --save\n$ npm install @transistorsoft/capacitor-background-fetch --save\n$ npx cap sync\n```\n\n## :large_blue_diamond: Setup Guides\n\n### iOS\n- [Required iOS Setup](help/INSTALL-IOS.md)\n\n### Android\n- [Required Android Setup](help/INSTALL-ANDROID.md)\n\n\n## :large_blue_diamond: Configure your license\n\n1. Login to Customer Dashboard to generate an application key:\n[www.transistorsoft.com/shop/customers](http://www.transistorsoft.com/shop/customers)\n![](https://gallery.mailchimp.com/e932ea68a1cb31b9ce2608656/images/b2696718-a77e-4f50-96a8-0b61d8019bac.png)\n\n2. Add your license-key to `android/app/src/main/AndroidManifest.xml`:\n\n```diff\n\u003cmanifest xmlns:android=\"http://schemas.android.com/apk/res/android\"\n    package=\"com.transistorsoft.backgroundgeolocation.react\"\u003e\n\n  \u003capplication\n    android:name=\".MainApplication\"\n    android:allowBackup=\"true\"\n    android:label=\"@string/app_name\"\n    android:icon=\"@mipmap/ic_launcher\"\n    android:theme=\"@style/AppTheme\"\u003e\n\n    \u003c!-- capacitor-background-geolocation licence --\u003e\n+     \u003cmeta-data android:name=\"com.transistorsoft.locationmanager.license\" android:value=\"YOUR_LICENCE_KEY_HERE\" /\u003e\n    .\n    .\n    .\n  \u003c/application\u003e\n\u003c/manifest\u003e\n```\n\n## :large_blue_diamond: Using the plugin ##\n\n```javascript\nimport BackgroundGeolocation from \"@transistorsoft/capacitor-background-geolocation\";\n```\n\n## :large_blue_diamond: Example\n\nThere are three main steps to using `BackgroundGeolocation`\n1. Wire up event-listeners.\n2. `#ready` the plugin.\n3. `#start` the plugin.\n\n:warning: Do not execute *any* API method which will require accessing location-services until the callback to **`#ready`** executes (eg: `#getCurrentPosition`, `#watchPosition`, `#start`).\n\n\n```javascript\n// NO!  .ready() has not resolved.\nBackgroundGeolocation.getCurrentPosition(options);\nBackgroundGeolocation.start();\n\nBackgroundGeolocation.ready(config).then((state) =\u003e {\n  // YES -- .ready() has now resolved.\n  BackgroundGeolocation.getCurrentPosition(options);\n  BackgroundGeolocation.start();  \n});\n\n// NO!  .ready() has not resolved.\nBackgroundGeolocation.getCurrentPosition(options);\nBackgroundGeolocation.start();\n```\n---------------------------------------------------------------------------------------------\n\n### Example 1. \u0026mdash; *React*\n\n\u003cimg alt=\"alt_text\" width=\"50px\" src=\"https://hackr.io/tutorials/react/logo-react.svg?ver=1610114789\" /\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eView Source\u003c/summary\u003e\n\n```typescript\nimport {\n  IonContent,\n  IonHeader,\n  IonPage,\n  IonTitle,\n  IonToolbar,\n  IonButtons,\n  IonToggle,\n  IonItemDivider,\n  IonLabel\n} from '@ionic/react';\n\nimport React from \"react\";\n\nimport BackgroundGeolocation, {\n  Subscription\n} from \"@transistorsoft/capacitor-background-geolocation\";\n\nconst HelloWorld: React.FC = () =\u003e {\n  const [ready, setReady] = React.useState(false);\n  const [enabled, setEnabled] = React.useState(false);\n  const [events, setEvents] = React.useState\u003cany[]\u003e([]);\n\n  const addEvent = (name: string, event:any) =\u003e {\n    setEvents(previous =\u003e [...previous, {\n      name: name,\n      json: JSON.stringify(event, null, 2)\n    }]);\n  }\n\n  React.useEffect(() =\u003e {\n    /// 1.  Subscribe to events.\n    const onLocation:Subscription = BackgroundGeolocation.onLocation((location) =\u003e {\n      addEvent('onLocation', location);\n    })\n\n    const onMotionChange:Subscription = BackgroundGeolocation.onMotionChange((event) =\u003e {\n      addEvent('onMotionChange', event);\n    });\n\n    const onActivityChange:Subscription = BackgroundGeolocation.onActivityChange((event) =\u003e {\n      addEvent('onActivityChange', event);\n    })\n\n    const onProviderChange:Subscription = BackgroundGeolocation.onProviderChange((event) =\u003e {\n      addEvent('onProviderChange', event);\n    })\n\n    /// 2. ready the plugin.\n    BackgroundGeolocation.ready({\n      // Geolocation Config\n      desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH,\n      distanceFilter: 10,\n      // Activity Recognition\n      stopTimeout: 5,\n      // Application config\n      debug: true, // \u003c-- enable this hear sounds for background-geolocation life-cycle.\n      logLevel: BackgroundGeolocation.LOG_LEVEL_VERBOSE,\n      stopOnTerminate: false,   // \u003c-- Allow the background-service to continue tracking when user closes the app.\n      startOnBoot: true,        // \u003c-- Auto start tracking when device is powered-up.\n    }).then((state) =\u003e {\n      setReady(true);\n      setEnabled(state.enabled)\n      addEvent('State', state);\n    });\n\n    return () =\u003e {\n      // Remove BackgroundGeolocation event-subscribers when the View is removed or refreshed\n      // during development live-reload.  Without this, event-listeners will accumulate with\n      // each refresh during live-reload.\n      onLocation.remove();\n      onMotionChange.remove();\n      onActivityChange.remove();\n      onProviderChange.remove();\n    }\n  }, []);\n\n  /// 3. start / stop BackgroundGeolocation\n  React.useEffect(() =\u003e {\n    if (!ready) { return }\n\n    if (enabled) {\n      BackgroundGeolocation.start();\n    } else {\n      BackgroundGeolocation.stop();\n      setEvents([]);\n    }\n  }, [enabled]);\n\n  return (\n    \u003cIonPage\u003e\n      \u003cIonHeader\u003e\n        \u003cIonToolbar\u003e\n          \u003cIonButtons slot=\"end\"\u003e\n            \u003cIonLabel\u003eToggle to \u003ccode\u003e{(enabled ? 'stop()' : 'start()')}\u003c/code\u003e \u0026mdash;\u0026gt;\u003c/IonLabel\u003e\n            \u003cIonToggle checked={enabled} onIonChange={e =\u003e setEnabled(e.detail.checked)}/\u003e\n          \u003c/IonButtons\u003e\n        \u003c/IonToolbar\u003e\n      \u003c/IonHeader\u003e\n      \u003cIonContent fullscreen\u003e\n        \u003cdiv style={{padding:10}}\u003e\n        { events.slice().reverse().map((event, i) =\u003e (\n          \u003cdiv key={i}\u003e\n            \u003cp\u003e\u003cstrong\u003e{event.name}\u003c/strong\u003e\u003c/p\u003e\n            \u003csmall\u003e\u003cpre\u003e\u003ccode\u003e{event.json}\u003c/code\u003e\u003c/pre\u003e\u003c/small\u003e\n            \u003cIonItemDivider /\u003e\n          \u003c/div\u003e\n        ))}\n        \u003c/div\u003e\n      \u003c/IonContent\u003e\n    \u003c/IonPage\u003e\n  )\n}\n```\n\n\u003c/details\u003e\n\n---------------------------------------------------------------------------------------------\n\n### Example 2. \u0026mdash; *Angular*\n\n\u003cimg alt=\"alt_text\" width=\"55px\" src=\"https://dl.dropbox.com/s/w4hw88clxqmlis2/angular-logo.svg?dl=1\" /\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eView Source\u003c/summary\u003e\n\n```typescript\nimport {\n  Component, \n  NgZone,\n  OnDestroy\n} from '@angular/core'\n\nimport BackgroundGeolocation, {\n  Location,\n  Subscription\n} from \"@transistorsoft/capacitor-background-geolocation\";\n\n@Component({\n  selector: 'hello-world',\n  template: `\n    \u003cion-header\u003e\n      \u003cion-toolbar\u003e\n        \u003cion-buttons slot=\"end\"\u003e\n          \u003cion-label\u003eToggle to \u003ccode\u003e{{(enabled ? 'stop()' : 'start()')}}\u003c/code\u003e \u0026mdash;\u0026gt;\u003c/ion-label\u003e\n          \u003cion-toggle [(ngModel)]=\"enabled\" (ionChange)=\"onToggleEnabled()\" style=\"display:block;\"\u003e\u003c/ion-toggle\u003e\n        \u003c/ion-buttons\u003e\n      \u003c/ion-toolbar\u003e\n    \u003c/ion-header\u003e\n    \u003cion-content fullscreen\u003e\n      \u003cdiv *ngFor=\"let event of events.slice().reverse()\" style=\"padding:10px\"\u003e\n        \u003cdiv\u003e\n          \u003cp\u003e\u003cstrong\u003e{{event.name}}\u003c/strong\u003e\u003c/p\u003e\n          \u003csmall\u003e\u003cpre\u003e\u003ccode\u003e{{event.json}}\u003c/code\u003e\u003c/pre\u003e\u003c/small\u003e\n          \u003cion-item-divider\u003e\u003c/ion-item-divider\u003e\n        \u003c/div\u003e\n      \u003c/div\u003e\n    \u003c/ion-content\u003e\n  `,\n  styles: []\n})\n\nexport class HelloWorldPage implements OnDestroy {\n  ready:boolean = false;\n  enabled:boolean = false;\n  events:any = [];\n  subscriptions:Subscription[] = [];\n\n  constructor(private zone:NgZone) {}\n\n  /// WARNING:  DO NOT Use ionViewWillEnter to configure the SDK -- use ngAfterContentInit.  \n  /// ionViewWillEnter only executes when the app is brought to the foreground.  \n  /// It will NOT execute when the app is launched in the background, as the SDK will often do.\n  /// \n  ngAfterContentInit() {\n    /// Step 1:  Subscribe to BackgroundGeolocation events.\n    this.subscriptions.push(BackgroundGeolocation.onLocation((location) =\u003e {\n      this.addEvent('onLocation', location);\n    }))\n\n    this.subscriptions.push(BackgroundGeolocation.onMotionChange((event) =\u003e {\n      this.addEvent('onMotionChange', event);\n    }))\n\n    this.subscriptions.push(BackgroundGeolocation.onActivityChange((event) =\u003e {\n      this.addEvent('onActivityChange', event);\n    }))\n\n    this.subscriptions.push(BackgroundGeolocation.onProviderChange((event) =\u003e {\n      this.addEvent('onProviderChange', event);\n    }))\n\n    /// Step 2:  Ready the plugin.\n    BackgroundGeolocation.ready({\n      // Geolocation Config\n      desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH,\n      distanceFilter: 10,\n      // Activity Recognition\n      stopTimeout: 5,\n      // Application config\n      debug: true, // \u003c-- enable this hear sounds for background-geolocation life-cycle.\n      logLevel: BackgroundGeolocation.LOG_LEVEL_VERBOSE,\n      stopOnTerminate: false,   // \u003c-- Allow the background-service to continue tracking when user closes the app.\n      startOnBoot: true,        // \u003c-- Auto start tracking when device is powered-up.\n    }).then((state) =\u003e {\n      // BackgroundGeolocation is now ready to use.\n      this.ready = true;\n      this.enabled = state.enabled;\n      this.addEvent('State', state);\n    });\n  }\n\n  /// When view is destroyed, be sure to .remove() all BackgroundGeolocation\n  /// event-subscriptions.\n  ngOnDestroy() {\n    this.subscriptions.forEach((subscription:Subscription) =\u003e {\n      subscription.remove();\n    })\n  }\n\n  /// Add an event to the view.\n  addEvent(name:string, event:any) {\n    this.zone.run(() =\u003e {\n      this.events.push({\n        name: name, \n        json: JSON.stringify(event, null, 2)\n      })  \n    })    \n  }\n\n  /// Toggle the plugin on/off.\n  onToggleEnabled() {\n    if (!this.ready) { return }\n\n    this.events = [];\n    if (this.enabled) {\n      BackgroundGeolocation.start().then((state) =\u003e {\n        this.addEvent('State', state);\n      })\n    } else {\n      BackgroundGeolocation.stop().then((state) =\u003e {\n        this.addEvent('State', state);\n      })\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n---------------------------------------------------------------------------------------------\n\n### Promise API\n\nThe `BackgroundGeolocation` Javascript API supports [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) for *nearly* every method (the exceptions are **`#watchPosition`** and adding event-listeners via **`onXXX`** methods (eg: `onLocation`, `onProviderChange`).  For more information, see the [API Documentation](https://transistorsoft.github.io/capacitor-background-geolocation)\n\n\n## :large_blue_diamond: [Demo Application](./example)\n\nA fully-featured [Demo App](./example) is available in this repo, for both *React* and *Angular*.  After first cloning this repo, follow the installation instructions in the [README](./example/README.md) there.  This demo-app includes an advanced settings-screen allowing you to quickly experiment with all the different settings available for each platform.\n\n![Home](https://dl.dropboxusercontent.com/s/wa43w1n3xhkjn0i/home-framed-350.png?dl=1)\n![Settings](https://dl.dropboxusercontent.com/s/8oad228siog49kt/settings-framed-350.png?dl=1)\n\n\n## :large_blue_diamond: [Simple Testing Server](https://github.com/transistorsoft/background-geolocation-console)\n\nA simple Node-based [web-application](https://github.com/transistorsoft/background-geolocation-console) with SQLite database is available for field-testing and performance analysis.  If you're familiar with Node, you can have this server up-and-running in about **one minute**.\n\n![](https://dl.dropboxusercontent.com/s/px5rzz7wybkv8fs/background-geolocation-console-map.png?dl=1)\n\n![](https://dl.dropboxusercontent.com/s/tiy5b2oivt0np2y/background-geolocation-console-grid.png?dl=1)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftransistorsoft%2Fcapacitor-background-geolocation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftransistorsoft%2Fcapacitor-background-geolocation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftransistorsoft%2Fcapacitor-background-geolocation/lists"}