Nimoy Prospers Mystically

    TypeScript icon, indicating that this package has built-in type declarations

    1.0.1 • Public • Published

    Cordova Geofence Plugin

    Plugin to monitor circular geofences using mobile devices. The purpose is to notify user if crossing the boundary of the monitored geofence.

    Geofences persist after device reboot. You do not have to open your app first to monitor added geofences


    Latest stable version

    cordova plugin add cordova-plugin-neugeofence

    Removing the Plugin from project

    Using cordova CLI

    cordova plugin rm cordova-plugin-neugeofence

    Supported Platforms

    • Android
    • iOS >=7.0

    Known Limitations

    This plugin is a wrapper on devices' native APIs which mean it comes with limitations of those APIs.

    Geofence Limit

    There are certain limits of geofences that you can set in your application depends on the platform of use.

    • iOS - 20 geofences
    • Android - 100 geofences

    Javascript background execution

    This is known limitation. When in background your app may/will be suspended to not use system resources. Therefore, any javascript code won't run, only background services can run in the background. Local notification when user crosses a geofence region will still work, but any custom javascript code won't. If you want to perform a custom action on geofence crossing, try to write it in native code.

    Platform specifics


    This plugin uses Google Play Services so you need to have it installed on your device.


    Plugin is written in Swift. All xcode project options to enable swift support are set up automatically after plugin is installed thanks to cordova-plugin-add-swift-support.

    iOS Quirks

    Since iOS 10 it's mandatory to add a NSLocationAlwaysUsageDescription and NSLocationWhenInUseUsageDescription entries in the info.plist.

    NSLocationWhenInUseUsageDescription describes the reason that the app accesses the user's location. NSLocationAlwaysUsageDescription describes the reason that the app accesses the user's location when not in use (in the background).

    When 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.

    Example: cordova plugin add cordova-plugin-geofence --variable GEOFENCE_IN_USE_USAGE_DESCRIPTION="your usage message" --variable GEOFENCE_ALWAYS_USAGE_DESCRIPTION="your usage message"

    If you don't pass the variable, the plugin will add a default string as value.

    Using the plugin

    Cordova initialize plugin to window.geofence object.


    All methods returning promises, but you can also use standard callback functions.

    • window.geofence.initialize(onSuccess, onError)
    • window.geofence.addOrUpdate(geofences, onSuccess, onError)
    • window.geofence.remove(geofenceId, onSuccess, onError)
    • window.geofence.removeAll(onSuccess, onError)
    • window.geofence.getWatched(onSuccess, onError)

    For listening of geofence transistion you can override onTransitionReceived method

    • window.geofence.onTransitionReceived(geofences)


    • TransitionType.ENTER = 1
    • TransitionType.EXIT = 2
    • TransitionType.BOTH = 3

    Error Codes

    Both onError function handler and promise rejection take error object as an argument.

    error: {
        code: String,
        message: String

    Error codes:


    Plugin initialization

    The plugin is not available until deviceready event is fired.

    document.addEventListener('deviceready', function () {
        // window.geofence is now available
        window.geofence.initialize().then(function () {
            console.log("Successful initialization");
        }, function (error) {
            console.log("Error", error);
    }, false);

    Initialization process is responsible for requesting neccessary permissions. If required permissions are not granted then initialization fails with error message.

    Adding new geofence to monitor

        id:             String, //A unique identifier of geofence
        latitude:       Number, //Geo latitude of geofence
        longitude:      Number, //Geo longitude of geofence
        radius:         Number, //Radius of geofence in meters
        transitionType: Number, //Type of transition 1 - Enter, 2 - Exit, 3 - Both
        notification: {         //Notification object
            id:             Number, //optional should be integer, id of notification
            title:          String, //Title of notification
            text:           String, //Text of notification
            smallIcon:      String, //Small icon showed in notification area, only res URI
            icon:           String, //icon showed in notification drawer
            openAppOnClick: Boolean,//is main app activity should be opened after clicking on notification
            vibration:      [Integer], //Optional vibration pattern - see description
            data:           Object  //Custom object associated with notification
    }).then(function () {
        console.log('Geofence successfully added');
    }, function (error) {
        console.log('Adding geofence failed', error);

    Adding more geofences at once

    window.geofence.addOrUpdate([geofence1, geofence2, geofence3]);

    Geofence overrides the previously one with the same id.

    All geofences are stored on the device and restored to monitor after device reboot.

    Notification overrides the previously one with the same

    Notification vibrations

    You can set vibration pattern for the notification or disable default vibrations.

    To change vibration pattern set vibrate property of notification object in geofence.


    //disable vibrations
    notification: {
        vibrate: [0]
    //Vibrate for 1 sec
    //Wait for 0.5 sec
    //Vibrate for 2 sec
    notification: {
        vibrate: [1000, 500, 2000]

    Platform quirks

    Fully working only on Android.

    On iOS vibration pattern doesn't work. Plugin only allow to vibrate with default system pattern.

    Windows Phone - current status is TODO

    Notification icons

    To set notification icons use icon and smallIcon property in notification object.

    As a value you can enter:

    • name of native resource or your application resource e.g. res://ic_menu_mylocation, res://icon, res://ic_menu_call
    • relative path to file in www directory e.g. file://img/ionic.png

    smallIcon - supports only resources URI


    notification: {
        smallIcon: 'res://my_location_icon',
        icon: 'file://img/geofence.png'

    Platform quirks

    Works only on Android platform so far.


    Removing single geofence

        .then(function () {
            console.log('Geofence sucessfully removed');
        , function (error){
            console.log('Removing geofence failed', error);

    Removing more than one geofence at once.

    window.geofence.remove([geofenceId1, geofenceId2, geofenceId3]);

    Removing all geofences

        .then(function () {
            console.log('All geofences successfully removed.');
        , function (error) {
            console.log('Removing geofences failed', error);

    Getting watched geofences from device

    window.geofence.getWatched().then(function (geofencesJson) {
        var geofences = JSON.parse(geofencesJson);

    Listening for geofence transitions

    window.geofence.onTransitionReceived = function (geofences) {
        geofences.forEach(function (geo) {
            console.log('Geofence transition detected', geo);

    Listening for geofence transitions in native code


    For android plugin broadcasting intent com.cowbell.cordova.geofence.TRANSITION. You can implement your own BroadcastReceiver and start listening for this intent.

    Register receiver in AndroidManifest.xml

    <receiver android:name="YOUR_APP_PACKAGE_NAME.TransitionReceiver">
            <action android:name="com.cowbell.cordova.geofence.TRANSITION" />

    Example code

    import com.cowbell.cordova.geofence.Gson;
    import com.cowbell.cordova.geofence.GeoNotification;
    public class TransitionReceiver extends BroadcastReceiver {
        public void onReceive(Context contextIntent intent) {
            String error = intent.getStringExtra("error");
            if (error != null) {
                //handle error 
                Log.println(Log.ERROR, "YourAppTAG", error);
            } else {
                String geofencesJson = intent.getStringExtra("transitionData");
                GeoNotification[] geoNotifications = Gson.get().fromJson(geofencesJson, GeoNotification[].class);
                //handle geoNotifications objects 

    When the app is opened via Notification click

    Android, iOS only

    window.geofence.onNotificationClicked = function (notificationData) {
        console.log('App opened from Geo Notification!', notificationData);

    Example usage

    Adding geofence to monitor entering Gliwice city center area of radius 3km

        id:             "69ca1b88-6fbe-4e80-a4d4-ff4d3748acdb",
        latitude:       50.2980049,
        longitude:      18.6593152,
        radius:         3000,
        transitionType: TransitionType.ENTER,
        notification: {
            id:             1,
            title:          "Welcome in Gliwice",
            text:           "You just arrived to Gliwice city center.",
            openAppOnClick: true
    }).then(function () {
        console.log('Geofence successfully added');
    }, function (reason) {
        console.log('Adding geofence failed', reason);


    npm i cordova-plugin-neugeofence

    DownloadsWeekly Downloads






    Unpacked Size

    487 kB

    Total Files


    Last publish


    • jatahworx