Geofences


 

Geofencing combines awareness of the user’s current location with awareness of nearby features, defined as the user’s proximity to locations that may be of interest. To mark a location of interest, you specify its latitude and longitude. To adjust the proximity for the location, you add a radius. The latitude, longitude, and radius define a geofence. You can have multiple active geofences at one time.

Location Services treats a geofences as an area rather than as a points and proximity. This allows it to detect when the user enters or exits a geofence. For each geofence, you can ask Location Services to send you entrance events or exit events or both. You can also limit the duration of a geofence by specifying an expiration duration in milliseconds. After the geofence expires, Location Services automatically removes it.

Request Geofence Monitoring

The first step in requesting geofence monitoring is to request the necessary permission

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

Check for Google Play Services

GooglePlayServicesUtil.isGooglePlayServicesAvailable(), which returns one of the integer result codes listed in the API reference documentation. If you encounter an error, callGooglePlayServicesUtil.getErrorDialog() to retrieve localized dialog that prompts users to take the correct action, then display the dialog in a DialogFragment. The dialog may allow the user to correct the problem, in which case Google Play services may send a result back to your activity. To handle this result, override the method onActivityResult()

To use geofencing, start by defining the geofences you want to monitor. Although you usually store geofence data in a local database or download it from the network, you need to send a geofence to Location Services as an instance of Geofence, which you create with Geofence.Builder. Each Geofence object contains the following information:

Latitude, longitude, and radius

Define a circular area for the geofence. Use the latitude and longitude to mark a location of interest, and then use the radius to adjust how close the user needs to approach the location before the geofence is detected. The larger the radius, the more likely the user will trigger a geofence transition alert by approaching the geofence. For example, providing a large radius for a geofencing app that turns on lights in the user’s house as the user returns home might cause the lights to go on even if the user is simply passing by.

Expiration time

How long the geofence should remain active. Once the expiration time is reached, Location Services deletes the geofence. Most of the time, you should specify an expiration time, but you may want to keep permanent geofences for the user’s home or place of work.

Transition type

Location Services can detect when the user steps within the radius of the geofence (“entry”) and when the user steps outside the radius of the geofence (“exit”), or both.

Geofence ID

A string that is stored with the geofence. You should make this unique, so that you can use it to remove a geofence from Location Services tracking.

A geofencing app needs to read and write geofence data to persistent storage. You shouldn’t use Geofenceobjects to do this; instead, use storage techniques such as databases that can store groups of related data.

public class MainActivity extends FragmentActivity {
...
/**
* A single Geofence object, defined by its center and radius.
*/
public class SimpleGeofence {
// Instance variables
private final String mId;
private final double mLatitude;
private final double mLongitude;
private final float mRadius;
private long mExpirationDuration;
private int mTransitionType;
/**
* @param geofenceId The Geofence's request ID
* @param latitude Latitude of the Geofence's center.
* @param longitude Longitude of the Geofence's center.
* @param radius Radius of the geofence circle.
* @param expiration Geofence expiration duration
* @param transition Type of Geofence transition.
*/
public SimpleGeofence(
String geofenceId,
double latitude,
double longitude,
float radius,
long expiration,
int transition) {
// Set the instance fields from the constructor
this.mId = geofenceId;
this.mLatitude = latitude;
this.mLongitude = longitude;

Create Geofence objects

The following snippet uses the SimpleGeofence and SimpleGeofenceStore classes gets geofence data from the UI, stores it in SimpleGeofence objects, stores these objects in a SimpleGeofenceStore object, and then creates Geofence objects:

public class MainActivity extends FragmentActivity {
...
/*
* Use to set an expiration time for a geofence. After this amount
* of time Location Services will stop tracking the geofence.
*/
private static final long SECONDS_PER_HOUR = 60;
private static final long MILLISECONDS_PER_SECOND = 1000;
private static final long GEOFENCE_EXPIRATION_IN_HOURS = 12;
private static final long GEOFENCE_EXPIRATION_TIME =
GEOFENCE_EXPIRATION_IN_HOURS *
SECONDS_PER_HOUR *
MILLISECONDS_PER_SECOND;
...
/*
* Handles to UI views containing geofence data
*/
// Handle to geofence 1 latitude in the UI
private EditText mLatitude1;
// Handle to geofence 1 longitude in the UI
private EditText mLongitude1;
// Handle to geofence 1 radius in the UI
private EditText mRadius1;
// Handle to geofence 2 latitude in the UI
private EditText mLatitude2;
// Handle to geofence 2 longitude in the UI
private EditText mLongitude2;
// Handle to geofence 2 radius in the UI
private EditText mRadius2;

In addition to the List of Geofence objects you want to monitor, you need to provide Location Services with the Intent that it sends to your app when it detects geofence transitions.

Define a Intent for geofence transitions

The Intent sent from Location Services can trigger various actions in your app, but you should not have it start an activity or fragment, because components should only become visible in response to a user action. In many cases, an IntentService is a good way to handle the intent.

private PendingIntent getTransitionPendingIntent() {
// Create an explicit Intent
Intent intent = new Intent(this,
ReceiveTransitionsIntentService.class);
/*
* Return the PendingIntent
*/
return PendingIntent.getService(
this,
0,
intent,
PendingIntent.FLAG_UPDATE_CURRENT);
}

Send the monitoring request

Sending the monitoring request requires two asynchronous operations. The first operation gets a location client for the request, and the second makes the request using the client. In both cases, Location Services invokes a callback method when it finishes the operation.

public class MainActivity extends FragmentActivity implements
ConnectionCallbacks,
OnConnectionFailedListener,
OnAddGeofencesResultListener {
...
}

Start the request process

Next, define a method that starts the request process by connecting to Location Services. Mark this as a request to add a geofence by setting a global variable. This allows you to use the callbackConnectionCallbacks.onConnected() to add geofences and to remove them, as described in succeeding sections.

public void addGeofences() {
// Start a request to add geofences
mRequestType = ADD;/*
* Test for Google Play services after setting the request type.
* If Google Play services isn't present, the proper request
* can be restarted.
*/
if (!servicesConnected()) {
return;
}
/*
* Create a new location client object. Since the current
* activity class implements ConnectionCallbacks and
* OnConnectionFailedListener, pass the current activity object
* as the listener for both parameters
*/
mLocationClient = new LocationClient(this, this, this)
// If a request is not already underway
if (!mInProgress) {
// Indicate that a request is underway
mInProgress = true;
// Request a connection from the client to Location Services
mLocationClient.connect();
} else {
/*
* A request is already underway. You can handle
* this situation by disconnecting the client,
* re-setting the flag, and then re-trying the
* request.
*/
}
}

Send a request to add the geofences

In your implementation of ConnectionCallbacks.onConnected(), call LocationClient.addGeofences(). Notice that if the connection fails, onConnected() isn’t called, and the request stops.

@Override
private void onConnected(Bundle dataBundle) {
...
switch (mRequestType) {
case ADD :
// Get the PendingIntent for the request
mTransitionPendingIntent =
getTransitionPendingIntent();
// Send a request to add the current geofences
mLocationClient.addGeofences(
mCurrentGeofences, pendingIntent, this);
...
}
}

Check the result returned by Location Services

When Location Services invokes your implementation of the callback method onAddGeofencesResult(), indicating that the request is complete, examine the incoming status code.

@Override
public void onAddGeofencesResult(
int statusCode, String[] geofenceRequestIds) {
// If adding the geofences was successful
if (LocationStatusCodes.SUCCESS == statusCode) {
/*
* Handle successful addition of geofences here.
* You can send out a broadcast intent or update the UI.
* geofences into the Intent's extended data.
*/
} else {
// If adding the geofences failed
/*
* Report errors here.
* You can log the error using Log.e() or update
* the UI.
*/
}
// Turn off the in progress flag and disconnect the client
mInProgress = false;
mLocationClient.disconnect();
}

Handle disconnections

In some cases, Location Services may disconnect from the activity recognition client before you calldisconnect()

@Override
public void onDisconnected() {
// Turn off the request flag
mInProgress = false;
// Destroy the current location client
mLocationClient = null;
}

Handle Geofence Transitions

When Location Services detects that the user has entered or exited a geofence, it sends out the Intentcontained in the PendingIntent you included in the request to add geofences.

This Intent isDefine an IntentService

The following snippet shows how to define an IntentService that posts a notification when a geofence transition occurs. When the user clicks the notification, the app’s main activity appears:

public class ReceiveTransitionsIntentService extends IntentService {
...
/**
* Sets an identifier for the service
*/
public ReceiveTransitionsIntentService() {
super("ReceiveTransitionsIntentService");
}
/**
* Handles incoming intents
*@param intent The Intent sent by Location Services. This
* Intent is provided
* to Location Services (inside a PendingIntent) when you call
* addGeofences()
*/
@Override
protected void onHandleIntent(Intent intent) {
// First check for errors
if (LocationClient.hasError(intent)) {
// Get the error code with a static method
int errorCode = LocationClient.getErrorCode(intent);
// Log the error
Log.e("ReceiveTransitionsIntentService",
"Location Services error: " +
Integer.toString(errorCode));
/*
* You can also send the error code to an Activity or
* Fragment with a broadcast Intent
*/
/*
* If there's no error, get the transition type and the IDs
* of the geofence or geofences that triggered the transition
*/
} else {
// Get the type of transition (entry or exit)
int transitionType =
LocationClient.getGeofenceTransition(intent);
// Test that a valid transition was reported
if (
(transitionType == Geofence.GEOFENCE_TRANSITION_ENTER)
||
(transitionType == Geofence.GEOFENCE_TRANSITION_EXIT)
) {
List <Geofence> triggerList =
getTriggeringGeofences(intent);
String[] triggerIds = new String[geofenceList.size()];
for (int i = 0; i < triggerIds.length; i++) {
// Store the Id of each geofence
triggerIds[i] = triggerList.get(i).getRequestId();
}

Specify the IntentService in the manifest

To identify the IntentService to the system, add a element to the app manifest. For example:

<service
android:name="com.example.android.location.ReceiveTransitionsIntentService"
android:label="@string/app_name"
android:exported="false">
</service>

Stop Geofence Monitoring

To stop geofence monitoring, you remove the geofences themselves. You can remove a specific set of geofences or all the geofences associated with a PendingIntent. The procedure is similar to adding geofences. The first operation gets a location client for the removal request, and the second makes the request using the client. The callback methods that Location Services invokes when it has finished removing geofences are defined in the interface LocationClient.OnRemoveGeofencesResultListener. Declare this interface as part of your class definition, and then add definitions for its two methods:

onRemoveGeofencesByPendingIntentResult()

Callback invoked when Location Services finishes a request to remove all geofences
made by the methodremoveGeofences(PendingIntent,
LocationClient.OnRemoveGeofencesResultListener).

onRemoveGeofencesByRequestIdsResult(List,
LocationClient.OnRemoveGeofencesResultListener)

Callback invoked when Location Services finished a request to remove a set of
geofences, specified by their geofence IDs, by the
method removeGeofences(List,
LocationClient.OnRemoveGeofencesResultListener).

Examples of implementing these methods are shown in the next snippets.

Remove all geofences

Since removing geofences uses some of the methods you use to add geofences, start by defining another request type:

public class MainActivity extends FragmentActivity implements
ConnectionCallbacks,
OnConnectionFailedListener,
OnAddGeofencesResultListener {
...
// Enum type for controlling the type of removal requested
public enum REQUEST_TYPE = {ADD, REMOVE_INTENT}
...
}

Start the removal request by getting a connection to Location Services. If the connection fails,onConnected() isn’t called, and the request stops. The following snippet shows how to start the request:

public class MainActivity extends FragmentActivity implements
ConnectionCallbacks,
OnConnectionFailedListener,
OnAddGeofencesResultListener {
...
/**
* Start a request to remove geofences by calling
* LocationClient.connect()
*/
public void removeGeofences(PendingIntent requestIntent) {
// Record the type of removal request
mRequestType = REMOVE_INTENT;
/*
* Test for Google Play services after setting the request type.
* If Google Play services isn't present, the request can be
* restarted.
*/
if (!servicesConnected()) {
return;
}
// Store the PendingIntent
mGeofenceRequestIntent = requestIntent;
/*
* Create a new location client object. Since the current
* activity class implements ConnectionCallbacks and
* OnConnectionFailedListener, pass the current activity object
* as the listener for both parameters

When Location Services invokes the callback method indicating that the connection is open, make the request to remove all geofences. Disconnect the client after making the request. For example:

public class MainActivity extends FragmentActivity implements
ConnectionCallbacks,
OnConnectionFailedListener,
OnAddGeofencesResultListener {
...
/**
* Once the connection is available, send a request to remove the
* Geofences. The method signature used depends on which type of
* remove request was originally received.
*/
private void onConnected(Bundle dataBundle) {
/*
* Choose what to do based on the request type set in
* removeGeofences
*/
switch (mRequestType) {
...
case REMOVE_INTENT :
mLocationClient.removeGeofences(
mGeofenceRequestIntent, this);
break;
...
}
}
...
}

Although the call to removeGeofences(PendingIntent, LocationClient.OnRemoveGeofencesResultListener) Services calls returns immediately, the result of the removal request is indeterminate until Location Services callsonRemoveGeofencesByPendingIntentResult(). The following snippet shows how to define this method:

public class MainActivity extends FragmentActivity implements
ConnectionCallbacks,
OnConnectionFailedListener,
OnAddGeofencesResultListener {
...
/**
* When the request to remove geofences by PendingIntent returns,
* handle the result.
*
*@param statusCode the code returned by Location Services
*@param requestIntent The Intent used to request the removal.
*/
@Override
public void onRemoveGeofencesByPendingIntentResult(int statusCode,
PendingIntent requestIntent) {
// If removing the geofences was successful
if (statusCode == LocationStatusCodes.SUCCESS) {
/*
* Handle successful removal of geofences here.
* You can send out a broadcast intent or update the UI.
* geofences into the Intent's extended data.
*/
} else {
// If adding the geocodes failed
/*
* Report errors here.
* You can log the error using Log.e() or update
* the UI.
*/
}
/*
* Disconnect the location client regardless of the
* request status, and indicate that a request is no
* longer in progress
*/
mInProgress = false;
mLocationClient.disconnect();
}
...
}

Remove individual geofences

The procedure for removing an individual geofence or set of geofences is similar to the removal of all geofences. To specify the geofences you want remove, add their geofence ID values to a List of String objects. Pass this List to a different definition of removeGeofences with the appropriate signature. This method then starts the removal process.

Start by adding a request type for removing geofences by a list, and also add a global variable for storing the list of geofences:

...
// Enum type for controlling the type of removal requested

Next, define a list of geofences you want to remove. For example, this snippet removes the Geofence defined by the geofence ID “1”:

public class MainActivity extends FragmentActivity implements
ConnectionCallbacks,
OnConnectionFailedListener,
OnAddGeofencesResultListener {
...
List<String> listOfGeofences =
Collections.singletonList("1");
removeGeofences(listOfGeofences);
...
}

The following snippet defines the removeGeofences() method:

public class MainActivity extends FragmentActivity implements
ConnectionCallbacks,
OnConnectionFailedListener,
OnAddGeofencesResultListener {
...
/**
* Start a request to remove monitoring by
* calling LocationClient.connect()
*
*/
public void removeGeofences(List<String> geofenceIds) {
// If Google Play services is unavailable, exit
// Record the type of removal request
mRequestType = REMOVE_LIST;
/*
* Test for Google Play services after setting the request type.
* If Google Play services isn't present, the request can be
* restarted.
*/
if (!servicesConnected()) {
return;
}
// Store the list of geofences to remove
mGeofencesToRemove = geofenceIds;
/*
* Create a new location client object. Since the current
* activity class implements ConnectionCallbacks and
* OnConnectionFailedListener, pass the current activity object
* as the listener for both parameters
*/
mLocationClient = new LocationClient(this, this, this);
// If a request is not already underway
if (!mInProgress) {
// Indicate that a request is underway
mInProgress = true;// Request a connection from the client to Location Services
mLocationClient.connect();
} else {
/*
* A request is already underway. You can handle
* this situation by disconnecting the client,
* re-setting the flag, and then re-trying the
* request.
*/
}
}
...
}

When Location Services invokes the callback method indicating that the connection is open, make the request to remove the list of geofences. Disconnect the client after making the request. For example:

public class MainActivity extends FragmentActivity implements
ConnectionCallbacks,
OnConnectionFailedListener,
OnAddGeofencesResultListener {
...
private void onConnected(Bundle dataBundle) {
...
switch (mRequestType) {
...
// If removeGeofencesById was called
case REMOVE_LIST :
mLocationClient.removeGeofences(
mGeofencesToRemove, this);
break;
...
}
...
}
...
}

Define an implementation of onRemoveGeofencesByRequestIdsResult(). Location Services invokes this callback method to indicate that the request to remove a list of geofences is complete. In this method, examine the incoming status code and take the appropriate action:

public class MainActivity extends FragmentActivity implements
ConnectionCallbacks,
OnConnectionFailedListener,
OnAddGeofencesResultListener {
...
/**
* When the request to remove geofences by IDs returns, handle the
* result.
*
* @param statusCode The code returned by Location Services* @param geofenceRequestIds The IDs removed
*/
@Override
public void onRemoveGeofencesByRequestIdsResult(
int statusCode, String[] geofenceRequestIds) {
// If removing the geocodes was successful
if (LocationStatusCodes.SUCCESS == statusCode) {
/*
* Handle successful removal of geofences here.
* You can send out a broadcast intent or update the UI.
* geofences into the Intent's extended data.
*/
} else {
// If removing the geofences failed
/*
* Report errors here.
* You can log the error using Log.e() or update
* the UI.
*/
}
// Indicate that a request is no longer in progress
mInProgress = false;
// Disconnect the location client
mLocationClient.disconnect();
}
...
}

Posted in All Tutorials, Android Tutorials | Tagged | Comments Off on Geofences
Powered By: wpnova.com