Modules.Geofence

> Modules.Geofence

Provides a battery-efficient way to monitor a device's movement into or out of a geographic region.

This feature requires a Pro or Enterprise subscription!

You use the Geofence module to define and monitor geofences in your application. A geofence is a circular region defined by a point (a latitude/longitude pair) and a radius, and represented by the Region object. When a device moves into or out of a geofence being monitored, the module notifies your application of the event.

Enterprise customers can also define geofences on the server using the Appcelerator Cloud Services API. An application can query the server for any defined geofences and begin monitoring them. See the RegionMonitoring example in the module ZIP download.

Getting Started

Once you have installed the module, use require() to access it from JavaScript:

var Geofence = require('ti.geofence');

Location Permissions

Please ensure to request proper location permissions before attempting to use geofencing feautures. See Titanium.Geolocation.hasLocationPermissions(<type>) and Titanium.Geolocation.requestLocationPermissions(<type>, <callback>) for details. Example:

if (!Ti.Geolocation.hasLocationPermissions(Ti.Geolocation.AUTHORIZATION_ALWAYS)) {
    Ti.Geolocation.requestLocationPermissions(Ti.Geolocation.AUTHORIZATION_ALWAYS, function (e) {
        if (!e.success) {
            alert('Location permissions declined!');
            return;
        }
        
        alert('Location permissions ready');
        // Initialize monitoring here
    });
}

Creating and monitoring geofence regions

You use the Geofence.createRegion() method to define a Region object. A geofence is a circular area defined by a point (latitude and longitude) and a radius (in meters).

var newRegion = Geofence.createRegion({
    center: {
        latitude: 37.389601,
        longitude: -122.050169
    },
    radius: 500,
    identifier:'Appcelerator'
});

To start monitoring a region, call the Geofence.startMonitoringForRegions() method, passing it the region or regions you want to monitor.

Geofence.startMonitoringForRegions([region1, region2]);

To be notified when the device moves into or out of a geofence region, create an event listener for the enterregions or exitregions events, respectively. For example:

Geofence.addEventListener('enterregions', function(e) {
    e.regions.forEach(function (region) {
        // Display local notification
        showNotification({
            title: 'ENTER',
            body: 'enter - ' + region.identifier
        });
    });
});

The event object passed to the event handler contains a regions property that identifies the region(s) that were entered or exited. On iOS this property contains an array of Region objects; on Android, it contains an array of generic objects that each contain a property called identifier. The value of this property corresponds to the one assigned to the Region when it was created.

Testing Geofence monitoring

You have a few options for testing geofence monitoring in your application. One approach is field testing: travel (drive, walk, etc.) between monitored regions while the application is running. You can also pass mock location data to the application running on a device or Simulator.

Note: The timing and frequency of location events may vary from one environment to another (device, OS version, network availability).

Mock locations from the iOS Simulator

Once the application is running in the simulator, select Debug > Location in the Simulator and select a predefined location or route that you would like to be sent to the Simulator. You can also enter a custom location (latitude, longitude).

Mock locations using Xcode

This method will work on both the iOS Simulator and on device.

  1. Launch your application once, then go to the build folder of your project and open the Xcode project found in build/iphone/.
  2. Run your project using Xcode.
  3. Once app is running, in Xcode debug area, click the Simulate Location icon to display a list of mock locations that can be sent to your application.
  4. Select one of these locations to send it to your app. Alternately, click on Add GPX File to Project... and select a GPX file with mock locations. A GPX file is provided in the example/MockLocationData folder in module download. The route starts at North De Anza Blvd and I-280 in Cupertino, CA and travels north on I-280.
  5. After adding a GPX file, go back and click on the mock locations arrow. The GPX file should now be in the list. Select the mock location to start using it.

Mock locations on Android

Add the following to your tiapp.xml.

<uses-permission android:name="android.permission.ACCESS_MOCK_LOCATION" />

For more information, see Provide Mock Location Data

Sample applications

The module ZIP file contains two Geofence sample applications (examples/Basic and examples/RegionMonitoring) and a GPX file (examples/MockLocationData) for mocking location data in Xcode.

  • 3.1.3
  • 3.1.3
  • 3.1.3
Defined By

Properties

Modules.Geofence
LOCATION_STATUS_ERROR : Numberreadonly

Possible value of the errorcode property in the error event object indicating an unspecified error occurred.

Possible value of the errorcode property in the error event object indicating an unspecified error occurred.

  • 3.1.3
Modules.Geofence
LOCATION_STATUS_GEOFENCE_NOT_AVAILABLE : Numberreadonly

Possible value of the errorcode property in the error event object indicating the geofence service is not available now.

Possible value of the errorcode property in the error event object indicating the geofence service is not available now.

  • 3.1.3
Modules.Geofence
: Numberreadonly
Possible value of the errorcode property in the error event object indicating your application has registered more th...

Possible value of the errorcode property in the error event object indicating your application has registered more than 100 geofences.

  • 3.1.3
Modules.Geofence
LOCATION_STATUS_GEOFENCE_TOO_MANY_PENDING_INTENTS : Numberreadonly

Possible value of the errorcode property in the error event object.

Possible value of the errorcode property in the error event object.

  • 3.1.3
Modules.Geofence
: Numberreadonly
Possible value of the state property in the regionstate event object. ...

Possible value of the state property in the regionstate event object.

The location is inside the given region.

  • 7.1.0
  • 7.1.0
Modules.Geofence
: Numberreadonly
Possible value of the state property in the regionstate event object. ...

Possible value of the state property in the regionstate event object.

The location is outside of the given region.

  • 7.1.0
  • 7.1.0
Modules.Geofence
: Numberreadonly
Possible value of the state property in the regionstate event object. ...

Possible value of the state property in the regionstate event object.

It is unknown whether the location is inside or outside of the region.

  • 7.1.0
  • 7.1.0
: Stringreadonly
The name of the API that this proxy corresponds to. ...

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Button returns Ti.UI.Button.

  • 3.2.0
  • 3.2.0
  • 3.2.0
  • 4.1.0
Indicates if the proxy will bubble an event to its parent. ...

Indicates if the proxy will bubble an event to its parent.

Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.

Default: true

  • 3.0.0
  • 3.0.0
  • 3.0.0
  • 4.1.0
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy. ...

The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.

If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.

  • 3.6.0
  • 4.1.0
Modules.Geofence
: Modules.Geofence.Region[]readonly
An array of the regions currently being monitored for the current application. ...

An array of the regions currently being monitored for the current application.

Example:

var regions = Geofence.monitoredRegions;
  • 3.1.3
  • 3.1.3
Defined By

Methods

Adds the specified callback as an event listener for the named event. ...

Adds the specified callback as an event listener for the named event.

Parameters

  • name : String

    Name of the event.

  • callback : Callback<Object>

    Callback function to invoke when the event is fired.

Returns

  • void
Applies the properties to the proxy. ...

Applies the properties to the proxy.

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.

  • 3.0.0
  • 3.0.0
  • 3.0.0
  • 4.1.0

Parameters

  • props : Dictionary

    A dictionary of properties to apply.

Returns

  • void
Modules.Geofence
( object ) : Modules.Geofence.Region
Creates a geofence Region. ...

Creates a geofence Region.

Example:

var region = Geofence.createRegion({
    center: {
        latitude:37.38960100,
        longitude:-122.05016900
    },
    radius:30,
    identifier:'Appcelerator'
});

Parameters

Returns

Fires a synthesized event to any registered listeners. ...

Fires a synthesized event to any registered listeners.

Parameters

  • name : String

    Name of the event.

  • event : Dictionary

    A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

Returns

  • void
( ) : Stringdeprecated
Gets the value of the Titanium.Proxy.apiName property. ...

Gets the value of the Titanium.Proxy.apiName property.

deprecated since 8.0.0

Access <Titanium.Proxy.apiName> instead.

  • 3.2.0
  • 3.2.0
  • 3.2.0
  • 4.1.0

Returns

  • String
( ) : Booleandeprecated
Gets the value of the Titanium.Proxy.bubbleParent property. ...

Gets the value of the Titanium.Proxy.bubbleParent property.

deprecated since 8.0.0

Access <Titanium.Proxy.bubbleParent> instead.

  • 3.0.0
  • 3.0.0
  • 3.0.0
  • 4.1.0

Returns

  • Boolean
Gets the value of the Titanium.Proxy.lifecycleContainer property. ...

Gets the value of the Titanium.Proxy.lifecycleContainer property.

deprecated since 8.0.0

Access <Titanium.Proxy.lifecycleContainer> instead.

  • 3.6.0
  • 4.1.0

Returns

Modules.Geofence
( ) : Modules.Geofence.Region[]deprecated
Gets the value of the Modules.Geofence.monitoredRegions property. ...

Gets the value of the Modules.Geofence.monitoredRegions property.

deprecated since 8.0.0

Access <Modules.Geofence.monitoredRegions> instead.

  • 3.1.3
  • 3.1.3

Returns

Modules.Geofence
( ) : Booleanremoved
Returns a number value indicating the availability of Google Play Services which are required to monitor regions. ...

Returns a number value indicating the availability of Google Play Services which are required to monitor regions.

Possible values include SUCCESS, SERVICE_MISSING, SERVICE_VERSION_UPDATE_REQUIRED, SERVICE_DISABLED, and SERVICE_INVALID. Example:

var Playservices = require('ti.playservices');
var hasGooglePlayServices = Playservices.isGooglePlayServicesAvailable();

This method has been removed since 3.0.0

Use Modules.PlayServices.isGooglePlayServicesAvailable in Titanium SDK 7.0.0 and later.

  • 3.1.3

Returns

  • Boolean
Modules.Geofence
( ) : Boolean
Returns a boolean that indicates if region monitoring is supported on the current device. ...

Returns a boolean that indicates if region monitoring is supported on the current device.

Example:

var canMonitor = Geofence.regionMonitoringAvailable();
  • 3.1.3
  • 3.1.3

Returns

  • Boolean
Removes the specified callback as an event listener for the named event. ...

Removes the specified callback as an event listener for the named event.

Multiple listeners can be registered for the same event, so the callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);

Parameters

  • name : String

    Name of the event.

  • callback : Callback<Object>

    Callback function to remove. Must be the same function passed to addEventListener.

Returns

  • void
Modules.Geofence
( )
Asynchronously retrieve the cached state of the specified region. ...

Asynchronously retrieve the cached state of the specified region.

The state is returned to the delegate via the regionstate event.

  • 7.1.0
  • 7.1.0

Returns

  • void
( bubbleParent )deprecated
Sets the value of the Titanium.Proxy.bubbleParent property. ...

Sets the value of the Titanium.Proxy.bubbleParent property.

deprecated since 8.0.0

Set the value using <Titanium.Proxy.bubbleParent> instead.

  • 3.0.0
  • 3.0.0
  • 3.0.0
  • 4.1.0

Parameters

  • bubbleParent : Boolean

    New value for the property.

Returns

  • void
( lifecycleContainer )deprecated
Sets the value of the Titanium.Proxy.lifecycleContainer property. ...

Sets the value of the Titanium.Proxy.lifecycleContainer property.

deprecated since 8.0.0

Set the value using <Titanium.Proxy.lifecycleContainer> instead.

  • 3.6.0
  • 4.1.0

Parameters

Returns

  • void
Modules.Geofence
( Region )
Starts monitoring the Region(s) passed as a parameter. ...

Starts monitoring the Region(s) passed as a parameter.

Takes either an array of Region objects or a single Region object as an argument.

On Android, if the device is located in a Region that has just started being monitored, an enterregions event is generated. On iOS, this scenario will not generate an enterregions event; instead, call the containsCoordinate() method on the newly Region object to check if the device is located within it.

Each platform limits the number of regions that can be monitored at one time. On iOS this limit is 20 regions, and 100 regions on Android. The following example creates a new Region object and then starts monitoring it.

var region1 = Geofence.createRegion({
    center: {
        latitude:37.389601,
        longitude:-122.050169
    },
    radius:500,
    identifier:'Appcelerator'
});
Geofence.startMonitoringForRegions(region1);

Parameters

Returns

  • void
Modules.Geofence
( )
Stops monitoring all of the regions that are currently being monitored. ...

Stops monitoring all of the regions that are currently being monitored.

This method is asynchronous on Android. The removeregions event will fire on completion.

Example:

Geofence.stopMonitoringAllRegions();

Returns

  • void
Modules.Geofence
( Region )
Stops monitoring the specified region or regions. ...

Stops monitoring the specified region or regions.

Takes either an array of Region objects or a single Region object as an argument.

This method is asynchronous on Android. The removeregions event will fire on completion.

Geofence.stopMonitoringForRegions([region, region1]);

Parameters

Returns

  • void
Defined By

Events

Modules.Geofence
Fired when the device enters a monitored region. ...

Fired when the device enters a monitored region.

Properties

  • regions : Array<Dictionary>/Array<Modules.Geofence.Region>

    The region(s) that were entered. On iOS, this property contains an array of Region objects representing the regions that were entered. On Android, this property contains an array of generic objects, each of which has an identifier property that corresponds to the region(s) that were entered.

  • bubbles : Boolean

    True if the event will try to bubble up if possible.

  • cancelBubble : Boolean

    Set to true to stop the event from bubbling.

  • source : Object

    Source object that fired the event.

  • type : String

    Name of the event fired.

Modules.Geofence
Fired when there is an error, or monitoring failed for a region. ...

Fired when there is an error, or monitoring failed for a region.

Properties

Modules.Geofence
Fired when the device exits a monitored region. ...

Fired when the device exits a monitored region.

Properties

  • regions : Array<Dictionary>/Array<Modules.Geofence.Region>

    The region(s) that were exited. On iOS, this property contains an array of Region objects representing the regions that were exited. On Android, this property contains an array of generic objects, each of which has an identifier property that corresponds to the region(s) that were exited.

  • bubbles : Boolean

    True if the event will try to bubble up if possible.

  • cancelBubble : Boolean

    Set to true to stop the event from bubbling.

  • source : Object

    Source object that fired the event.

  • type : String

    Name of the event fired.

Modules.Geofence
Fired when startMonitoringForRegions() and monitoring has successfully started for those regions. ...

Fired when startMonitoringForRegions() and monitoring has successfully started for those regions.

Properties

  • regions : Array<Dictionary>/Array<Modules.Geofence.Region>

    The region(s) for which monitoring has started. On iOS, this property contains an array of Region objects representing the regions for which monitoring has started. On Android, there is no property for you to check.

  • bubbles : Boolean

    True if the event will try to bubble up if possible.

  • cancelBubble : Boolean

    Set to true to stop the event from bubbling.

  • source : Object

    Source object that fired the event.

  • type : String

    Name of the event fired.

Modules.Geofence
Fired when requestStateForRegion() requested a state or there is a state transition for a monitored region. ...

Fired when requestStateForRegion() requested a state or there is a state transition for a monitored region.

Properties

  • region : Modules.Geofence.Region

    The region that triggered the state change.

  • state : Number

    The updated region state. One of REGION_STATE_*.

    This API can be assigned the following constants:

  • bubbles : Boolean

    True if the event will try to bubble up if possible.

  • cancelBubble : Boolean

    Set to true to stop the event from bubbling.

  • source : Object

    Source object that fired the event.

  • type : String

    Name of the event fired.

Modules.Geofence
Fired on Android when regions are removed using stopMonitoringForRegions or stopMonitoringAllRegions and monitoring h...

Fired on Android when regions are removed using stopMonitoringForRegions or stopMonitoringAllRegions and monitoring has successfully stopped for those regions.

  • 3.1.3

Properties

  • regions : Array<Dictionary>/Array<Modules.Geofence.Region>

    The region(s) for which monitoring has stopped. On iOS, this property contains an array of Region objects representing the regions for which monitoring has stopped. On Android, this property contains an array of generic objects, each of which has an identifier property that corresponds to the region(s) for which monitoring has stopped.

  • bubbles : Boolean

    True if the event will try to bubble up if possible.

  • cancelBubble : Boolean

    Set to true to stop the event from bubbling.

  • source : Object

    Source object that fired the event.

  • type : String

    Name of the event fired.