Receiving proximity alerts by using geofencing

You can use the net.rim.device.api.location.Geofence class to define a perimeter around an area that you want your application to monitor. Your application receives an alert whenever a BlackBerry device user enters or leaves a geofenced area. By using geofencing, you can alert your users when they enter an area of interest, or you could send users information specific to their locations.

When an application invokes the Geofence.monitorPerimeter() method, the Geofencing server sends proximity alerts to the application whenever the device enters or exits the geofenced area. Each Geofence object can monitor up to 20 areas simultaneously.

Defining an area to monitor

You can define an area to monitor by specifying the geographic coordinates of a location and a radius around that location, or you can specify a set of coordinates representing a polygon. When you specify a set of coordinates representing a polygon, you must ensure that none of the lines intersect, or else the geofenced area might not trigger events correctly. Each coordinate in the array is joined to the coordinate that follows it with a straight line. The last coordinate in the array is joined to the first.
// Single Coordinates object, to be used along with a radius

Coordinates coords = new Coordinates(43.2750, -80.3318, 0);

// Array of three Coordinates objects, representing a three-sided polygon

Coordinates[] coords2 = new Coordinates[3];
coords2[0] = new Coordinates(43.2851, -80.3229, 0);
coords2[1] = new Coordinates(43.2945, -80.3220, 0);
coords2[2] = new Coordinates(43.2852, -80.3199, 0);
When you invoke monitorPerimeter(), you must pass in a reference to the class that implements GeofenceListener as an argument. You must also specify a tag for the area, a buffer around the area, and the length of time that you want to monitor that area. Use the tag to provide a unique description of the area. Use the buffer to define a distance around the perimeter where geofencing notifications can't occur, which can help prevent the application from broadcasting notifications repeatedly when a device user repeatedly leaves and reenters the area.
GFListener gfListener = new GFListener();
Geofence geofence = new Geofence();

// Starts monitoring the area defined by the coordinate and a radius

geofence.monitorPerimeter(gfListener, "RIM 12", coords, 500, 50, -1);

// Starts monitoring the area defined by the set of coordinates

geofence.monitorPerimeter(gfListener, "RIM campus", coords2, 50, -1);

Listening for geofencing events

To receive proximity alerts, implement the GeofenceListener interface, which contains three methods: errorOccurred(), perimeterEntered(), and perimeterExited(). When an area is being monitored, the application invokes one of these methods when the appropriate event occurs. The perimeterEntered() and perimeterExited() methods receive as parameters the tag for the location and a BlackBerryLocation object that represents where the user enters or leaves. You can use this information to describe the area that is being entered, or to center a map on the location.
private class GFListener implements GeofenceListener
    public void perimeterEntered(String tag, BlackBerryLocation location)
        // Code that runs when a user enters the perimeter      

    public void errorOccurred(int errorCode)
        // Code that runs when an error occurs

    public void perimeterExited(String tag, BlackBerryLocation location)
        // Code that runs when a user leaves the perimeter     

If errorOccured() is invoked because of a low battery, or if location services is unavailable (OUT_OF_SERVICE error), the application stops receiving notifications.

Stopping your application from monitoring an area

If you need to stop your application from monitoring an area, you can call Geofence.removePerimeter(String tag).

Was this information helpful? Send us your comments.