Would you like to tell us how we are doing?

You bet No thanks

Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Receiving proximity alerts with geofencing

You can use the net.rim.device.api.location.Geofence class to define a perimeter around an area that you want your app to monitor. Your app receives an alert whenever a BlackBerry device user enters or leaves a geofenced area. 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 app invokes the Geofence.monitorPerimeter() method, the Geofencing server sends proximity alerts to the app 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 app from broadcasting notifications repeatedly when a device user repeatedly leaves and reenters the area.

GFListener gfListener = new GFListener();
Geofence geofence = new Geofence();

// Start monitoring the area defined by the coordinate and a radius.
geofence.monitorPerimeter(gfListener, "RIM 12", coords, 500, 50, -1);

// Start 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 app 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 are unavailable (OUT_OF_SERVICE error), the app stops receiving notifications.

Stopping your app from monitoring an area

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