{"id":14988471,"url":"https://github.com/cowbell/cordova-plugin-geofence","last_synced_at":"2025-10-04T10:49:18.394Z","repository":{"id":20810472,"uuid":"24096005","full_name":"cowbell/cordova-plugin-geofence","owner":"cowbell","description":"Geofencing plugin for cordova","archived":false,"fork":false,"pushed_at":"2022-05-19T06:36:18.000Z","size":3592,"stargazers_count":267,"open_issues_count":141,"forks_count":313,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-04-03T15:12:00.900Z","etag":null,"topics":["android","cordova","cordova-plugin","geofences","ios","java","swift"],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cowbell.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}},"created_at":"2014-09-16T10:55:39.000Z","updated_at":"2025-03-09T01:50:05.000Z","dependencies_parsed_at":"2022-08-30T11:32:32.657Z","dependency_job_id":null,"html_url":"https://github.com/cowbell/cordova-plugin-geofence","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowbell%2Fcordova-plugin-geofence","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowbell%2Fcordova-plugin-geofence/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowbell%2Fcordova-plugin-geofence/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowbell%2Fcordova-plugin-geofence/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cowbell","download_url":"https://codeload.github.com/cowbell/cordova-plugin-geofence/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248599297,"owners_count":21131257,"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":["android","cordova","cordova-plugin","geofences","ios","java","swift"],"created_at":"2024-09-24T14:16:46.737Z","updated_at":"2025-10-04T10:49:13.347Z","avatar_url":"https://github.com/cowbell.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cordova Geofence Plugin\n\n[![version](https://badge.fury.io/js/cordova-plugin-geofence.png)](https://badge.fury.io/js/cordova-plugin-geofence)\n\nPlugin to monitor circular geofences using mobile devices. The purpose is to notify user if crossing the boundary of the monitored geofence.\n\n*Geofences persist after device reboot. You do not have to open your app first to monitor added geofences*\n\n## Example applications\n\nCheck out our example applications:\n\n* https://github.com/cowbell/ionic-geofence built with [Ionic](http://ionic.io/) framework\n* https://github.com/tsubik/ionic2-geofence built with [Ionic 2](http://ionic.io/2) framework\n* https://github.com/cowbell/ember-geofence built with [Ember.js](http://emberjs.com/), [Cordova](https://cordova.apache.org/), [Material Design](https://www.google.com/design/spec/material-design/introduction.html)\n\n## Installation\n\nFrom master\n```\ncordova plugin add https://github.com/cowbell/cordova-plugin-geofence\n```\n\nLatest stable version\n\n```\ncordova plugin add cordova-plugin-geofence\n```\n\n## Removing the Plugin from project\n\nUsing cordova CLI\n\n```\ncordova plugin rm cordova-plugin-geofence\n```\n\n## Supported Platforms\n\n- Android\n- iOS \u003e=7.0\n- Windows Phone 8.1\n    - using Universal App (cordova windows platform)\n    - using Silverlight App (cordova wp8 platform retargeted to WP 8.1)\n\n## Known Limitations\n\n**This plugin is a wrapper on devices' native APIs** which mean it comes with **limitations of those APIs**.\n\n### Geofence Limit\n\nThere are certain limits of geofences that you can set in your application depends on the platform of use.\n\n- iOS - 20 geofences\n- Android - 100 geofences\n\n### Javascript background execution\n\nThis is known limitation. When in background your app may/will be suspended to not use system resources.\nTherefore, **any javascript code won't run**, only background services can run in the background. Local\nnotification when user crosses a geofence region will still work, but any custom javascript code won't.\nIf you want to perform a custom action on geofence crossing, [try to write it in native code](#listening-for-geofence-transitions-in-native-code).\n\n# Platform specifics\n\n## Android\n\nThis plugin uses Google Play Services so you need to have it installed on your device.\n\n## iOS\n\nPlugin is written in Swift. All xcode project options to enable swift support are set up automatically after plugin is installed thanks to\n[cordova-plugin-add-swift-support](https://github.com/akofman/cordova-plugin-add-swift-support).\n\n:warning: Swift 3 is not supported at the moment, the following preference has to be added in your project :\n\nFor Cordova projects\n\n`\u003cpreference name=\"UseLegacySwiftLanguageVersion\" value=\"true\" /\u003e`\n\nFor PhoneGap projects\n\n`\u003cpreference name=\"swift-version\" value=\"2.3\" /\u003e`\n\n### iOS Quirks\n\nSince iOS 10 it's mandatory to add a `NSLocationAlwaysUsageDescription` and `NSLocationWhenInUseUsageDescription` entries in the info.plist.\n\n`NSLocationWhenInUseUsageDescription` describes the reason that the app accesses the user's location.\n`NSLocationAlwaysUsageDescription` describes the reason that the app accesses the user's location when not in use (in the background).\n\nWhen the system prompts the user to allow access, this string is displayed as part of the dialog box. To add this entry you can pass the variable `GEOFENCE_IN_USE_USAGE_DESCRIPTION` and `GEOFENCE_ALWAYS_USAGE_DESCRIPTION` on plugin install.\n\nExample:\n`cordova plugin add cordova-plugin-geofence --variable GEOFENCE_IN_USE_USAGE_DESCRIPTION=\"your usage message\" --variable GEOFENCE_ALWAYS_USAGE_DESCRIPTION=\"your usage message\"`\n\nIf you don't pass the variable, the plugin will add a default string as value.\n\n## Windows phone 8.1\n\nPlugin can be used with both windows phone 8.1 type projects Univeral App, Silverlight App.\n\nIn order to use toast notifications you have to enable this feature in appxmanifest file either using UI in Visual Studio or edit file setting attribute **ToastCapable=\"true\"** in **m3:VisualElements** node under Package/Applications/Application.\n\nIf you are retargeting WP 8.0 to WP 8.1 you need to register background task to perform geofence notifications. Register it via UI in Visual Studio or add following code under Package/Applications/Application/Extensions\n\n```xml\n\u003cExtension Category=\"windows.backgroundTasks\" EntryPoint=\"GeofenceComponent.GeofenceTrigger\"\u003e\n    \u003cBackgroundTasks\u003e\n        \u003cm2:Task Type=\"location\" /\u003e\n    \u003c/BackgroundTasks\u003e\n\u003c/Extension\u003e\n```\n\n# Using the plugin\n\nCordova initialize plugin to `window.geofence` object.\n\n## Methods\n\nAll methods returning promises, but you can also use standard callback functions.\n\n- `window.geofence.initialize(onSuccess, onError)`\n- `window.geofence.addOrUpdate(geofences, onSuccess, onError)`\n- `window.geofence.remove(geofenceId, onSuccess, onError)`\n- `window.geofence.removeAll(onSuccess, onError)`\n- `window.geofence.getWatched(onSuccess, onError)`\n\nFor listening of geofence transistion you can override onTransitionReceived method\n- `window.geofence.onTransitionReceived(geofences)`\n\n## Constants\n\n- `TransitionType.ENTER` = 1\n- `TransitionType.EXIT` = 2\n- `TransitionType.BOTH` = 3\n\n## Error Codes\n\nBoth `onError` function handler and promise rejection take `error` object as an argument.\n\n```\nerror: {\n    code: String,\n    message: String\n}\n```\n\nError codes:\n\n- `UNKNOWN`\n- `PERMISSION_DENIED`\n- `GEOFENCE_NOT_AVAILABLE`\n- `GEOFENCE_LIMIT_EXCEEDED`\n\n## Plugin initialization\n\nThe plugin is not available until `deviceready` event is fired.\n\n```javascript\ndocument.addEventListener('deviceready', function () {\n    // window.geofence is now available\n    window.geofence.initialize().then(function () {\n        console.log(\"Successful initialization\");\n    }, function (error) {\n        console.log(\"Error\", error);\n    });\n}, false);\n```\n\nInitialization process is responsible for requesting neccessary permissions.\nIf required permissions are not granted then initialization fails with error message.\n\n## Adding new geofence to monitor\n\n```javascript\nwindow.geofence.addOrUpdate({\n    id:             String, //A unique identifier of geofence\n    latitude:       Number, //Geo latitude of geofence\n    longitude:      Number, //Geo longitude of geofence\n    radius:         Number, //Radius of geofence in meters\n    transitionType: Number, //Type of transition 1 - Enter, 2 - Exit, 3 - Both\n    notification: {         //Notification object\n        id:             Number, //optional should be integer, id of notification\n        title:          String, //Title of notification\n        text:           String, //Text of notification\n        smallIcon:      String, //Small icon showed in notification area, only res URI\n        icon:           String, //icon showed in notification drawer\n        openAppOnClick: Boolean,//is main app activity should be opened after clicking on notification\n        vibration:      [Integer], //Optional vibration pattern - see description\n        data:           Object  //Custom object associated with notification\n    }\n}).then(function () {\n    console.log('Geofence successfully added');\n}, function (error) {\n    console.log('Adding geofence failed', error);\n});\n```\nAdding more geofences at once\n```javascript\nwindow.geofence.addOrUpdate([geofence1, geofence2, geofence3]);\n```\n\nGeofence overrides the previously one with the same `id`.\n\n*All geofences are stored on the device and restored to monitor after device reboot.*\n\nNotification overrides the previously one with the same `notification.id`.\n\n## Notification vibrations\n\nYou can set vibration pattern for the notification or disable default vibrations.\n\nTo change vibration pattern set `vibrate` property of `notification` object in geofence.\n\n### Examples\n\n```\n//disable vibrations\nnotification: {\n    vibrate: [0]\n}\n```\n\n```\n//Vibrate for 1 sec\n//Wait for 0.5 sec\n//Vibrate for 2 sec\nnotification: {\n    vibrate: [1000, 500, 2000]\n}\n```\n\n### Platform quirks\n\nFully working only on Android.\n\nOn iOS vibration pattern doesn't work. Plugin only allow to vibrate with default system pattern.\n\nWindows Phone - current status is TODO\n\n## Notification icons\n\nTo set notification icons use `icon` and `smallIcon` property in `notification` object.\n\nAs a value you can enter:\n- name of native resource or your application resource e.g. `res://ic_menu_mylocation`, `res://icon`, `res://ic_menu_call`\n- relative path to file in `www` directory e.g. `file://img/ionic.png`\n\n`smallIcon` - supports only resources URI\n\n### Examples\n\n```\nnotification: {\n    smallIcon: 'res://my_location_icon',\n    icon: 'file://img/geofence.png'\n}\n```\n\n### Platform quirks\n\nWorks only on Android platform so far.\n\n## Removing\n\nRemoving single geofence\n```javascript\nwindow.geofence.remove(geofenceId)\n    .then(function () {\n        console.log('Geofence sucessfully removed');\n    }\n    , function (error){\n        console.log('Removing geofence failed', error);\n    });\n```\nRemoving more than one geofence at once.\n```javascript\nwindow.geofence.remove([geofenceId1, geofenceId2, geofenceId3]);\n```\n\n## Removing all geofences\n\n```javascript\nwindow.geofence.removeAll()\n    .then(function () {\n        console.log('All geofences successfully removed.');\n    }\n    , function (error) {\n        console.log('Removing geofences failed', error);\n    });\n```\n\n## Getting watched geofences from device\n\n```javascript\nwindow.geofence.getWatched().then(function (geofencesJson) {\n    var geofences = JSON.parse(geofencesJson);\n});\n```\n\n## Listening for geofence transitions\n\n```javascript\nwindow.geofence.onTransitionReceived = function (geofences) {\n    geofences.forEach(function (geo) {\n        console.log('Geofence transition detected', geo);\n    });\n};\n```\n\n## Listening for geofence transitions in native code\n\n### Android\n\nFor android plugin broadcasting intent `com.cowbell.cordova.geofence.TRANSITION`. You can implement your own `BroadcastReceiver` and start listening for this intent.\n\nRegister receiver in `AndroidManifest.xml`\n\n```xml\n\u003creceiver android:name=\"YOUR_APP_PACKAGE_NAME.TransitionReceiver\"\u003e\n    \u003cintent-filter\u003e\n        \u003caction android:name=\"com.cowbell.cordova.geofence.TRANSITION\" /\u003e\n    \u003c/intent-filter\u003e\n\u003c/receiver\u003e\n```\n\nExample `TransitionReceiver.java` code\n\n```java\n......\nimport com.cowbell.cordova.geofence.Gson;\nimport com.cowbell.cordova.geofence.GeoNotification;\n\npublic class TransitionReceiver extends BroadcastReceiver {\n\n    @Override\n    public void onReceive(Context context, Intent intent) {\n        String error = intent.getStringExtra(\"error\");\n\n        if (error != null) {\n            //handle error\n            Log.println(Log.ERROR, \"YourAppTAG\", error);\n        } else {\n            String geofencesJson = intent.getStringExtra(\"transitionData\");\n            GeoNotification[] geoNotifications = Gson.get().fromJson(geofencesJson, GeoNotification[].class);\n            //handle geoNotifications objects\n        }\n    }\n}\n```\n\n## When the app is opened via Notification click\n\nAndroid, iOS only\n\n```javascript\nwindow.geofence.onNotificationClicked = function (notificationData) {\n    console.log('App opened from Geo Notification!', notificationData);\n};\n```\n\n# Example usage\n\nAdding geofence to monitor entering Gliwice city center area of radius 3km\n\n```javascript\nwindow.geofence.addOrUpdate({\n    id:             \"69ca1b88-6fbe-4e80-a4d4-ff4d3748acdb\",\n    latitude:       50.2980049,\n    longitude:      18.6593152,\n    radius:         3000,\n    transitionType: TransitionType.ENTER,\n    notification: {\n        id:             1,\n        title:          \"Welcome in Gliwice\",\n        text:           \"You just arrived to Gliwice city center.\",\n        openAppOnClick: true\n    }\n}).then(function () {\n    console.log('Geofence successfully added');\n}, function (reason) {\n    console.log('Adding geofence failed', reason);\n})\n```\n\n# Development\n\n## Installation\n\n- git clone https://github.com/cowbell/cordova-plugin-geofence\n- change into the new directory\n- `npm install`\n\n## Running tests\n\n- Start emulator\n- `cordova-paramedic --platform android --plugin .`\n\n### Testing on iOS\n\nBefore you run `cordova-paramedic` install `npm install -g ios-sim`\n\n### Troubleshooting\n\nAdd `--verbose` at the end of `cordova-paramedic` command.\n\n## License\n\nThis software is released under the [Apache 2.0 License](http://opensource.org/licenses/Apache-2.0).\n\n© 2014-2017 Cowbell-labs. All rights reserved\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcowbell%2Fcordova-plugin-geofence","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcowbell%2Fcordova-plugin-geofence","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcowbell%2Fcordova-plugin-geofence/lists"}