{"id":353,"date":"2011-01-10T23:07:00","date_gmt":"2011-01-10T23:07:00","guid":{"rendered":"http:\/\/www.javacodegeeks.com\/2012\/10\/android-proximity-alerts-tutorial.html"},"modified":"2012-10-21T19:33:45","modified_gmt":"2012-10-21T19:33:45","slug":"android-proximity-alerts-tutorial","status":"publish","type":"post","link":"https:\/\/www.javacodegeeks.com\/2011\/01\/android-proximity-alerts-tutorial.html","title":{"rendered":"Android Proximity Alerts Tutorial"},"content":{"rendered":"

Smart-phones are taking over the mobile world, this is a fact. Since GPS devices are usually found embedded in those phones, there is already a notable rise in applications that take advantage of the offered geographical positioning functionality. A type of those applications is the one of Location Based Services<\/a>, where the service exploits knowledge about where the mobile user is globally positioned at. Pretty common are also the applications that use geocoding<\/a> (finding associated geographic coordinates from geographic data, such as a street address) and reverse geocoding<\/a> (providing information based on given coordinates). One other aspect of that type of applications is the creation of proximity alerts. As their name suggests, these are alerts that get generated when the user is physically located near a specific Point Of Interest (POI)<\/a>. Proximity alert are going to be a \u201chot\u201d thing the following years, since a lot of applications are going to make use of them, with the most prominent example being targeted advertising. In this tutorial I am going to show you how to take advantage of Android’s built-in proximity alert capabilities.<\/p>\n

Before we begin, it would be helpful to have read introductory articles about location based application and\/or geocoding. You might want to take a look at some previous tutorials of mine, such as \u201cAndroid Location Based Services Application \u2013 GPS location\u201d<\/a> and \u201cAndroid Reverse Geocoding with Yahoo API \u2013 PlaceFinder\u201d<\/a>. One other thing to note is that this tutorial was inspired by a very cool tutorial named \u201cDeveloping Proximity Alerts for Mobile Applications using the Android Platform\u201d<\/a>. This is a four part tutorial, which gets a little complicated at some points and might intimidate a beginner. For that reason, I decided to provided a shorter and more straightforward tutorial.<\/p>\n

What we will build is a simple application that stores the user’s coordinates for a point that interests him and then provide a notification when the user is near that point. The coordinates are retrieved on demand when the user is located at that point.<\/p>\n

We begin by creating a new Eclipse project, named \u201cAndroidProximityAlertProject\u201d in our case. We also create a main activity for our application under the name \u201cProxAlertActivity\u201d. Here is what the application’s main page will look like:<\/p>\n

\"\"<\/a><\/p>\n

Here is the declaration file for the main UI layout, named \u201cmain.xml\u201d:<\/p>\n

<?xml version=\"1.0\" encoding=\"utf-8\"?>\r\n\r\n<LinearLayout xmlns:android=\"http:\/\/schemas.android.com\/apk\/res\/android\"\r\n    android:orientation=\"vertical\"\r\n    android:layout_width=\"fill_parent\"\r\n    android:layout_height=\"fill_parent\"\r\n>\r\n\r\n    <EditText \r\n        android:id=\"@+id\/point_latitude\" \r\n        android:layout_width=\"fill_parent\" \r\n        android:layout_height=\"wrap_content\"\r\n        android:layout_marginLeft=\"25dip\"\r\n        android:layout_marginRight=\"25dip\"\r\n    \/>\r\n    \r\n    <EditText \r\n        android:id=\"@+id\/point_longitude\" \r\n        android:layout_width=\"fill_parent\" \r\n        android:layout_height=\"wrap_content\"\r\n        android:layout_marginLeft=\"25dip\"\r\n        android:layout_marginRight=\"25dip\"\r\n    \/>\r\n        \r\n    <Button \r\n        android:id=\"@+id\/find_coordinates_button\" \r\n        android:text=\"Find Coordinates\"\r\n        android:layout_width=\"wrap_content\" \r\n        android:layout_height=\"wrap_content\" \r\n    \/>\r\n    \r\n    <Button \r\n        android:id=\"@+id\/save_point_button\" \r\n        android:text=\"Save Point\"\r\n        android:layout_width=\"wrap_content\" \r\n        android:layout_height=\"wrap_content\" \r\n    \/>\r\n    \r\n<\/LinearLayout>\r\n<\/pre>\n
Let’s now get started with the interesting stuff. First of all, we need a reference to the LocationManager<\/a> class, which provides access to the system location services. This is done via a call to the getSystemService<\/a> method of our activity. We can then use the requestLocationUpdates<\/a> method in order to request notifications when the user’s location changes. This is not strictly required when developing proximity alerts, but I will use it here in order to calculate the distance between the point of interest and the current user location. At any given time, we can call the getLastKnownLocation<\/a> method and retrieve the last known location of a specific provider, in our case the GPS device. Finally, we will make use of the addProximityAlert<\/a> method that can be used to set a proximity alert for a location given by specific coordinates (latitude, longitude) and a given radius. We can also optionally define an expiration time for that alert if we wish to monitor the alert for a specific time period. A PendingIntent<\/a> can also be provided, which will be used to generate an Intent<\/a> to fire when entry to or exit from the alert region is detected.<\/p>\n
All these are translated into code as follows:<\/p>\n
package com.javacodegeeks.android.lbs;\r\n\r\nimport java.text.DecimalFormat;\r\nimport java.text.NumberFormat;\r\n\r\nimport android.app.Activity;\r\nimport android.app.PendingIntent;\r\nimport android.content.Context;\r\nimport android.content.Intent;\r\nimport android.content.IntentFilter;\r\nimport android.content.SharedPreferences;\r\nimport android.location.Location;\r\nimport android.location.LocationListener;\r\nimport android.location.LocationManager;\r\nimport android.os.Bundle;\r\nimport android.view.View;\r\nimport android.view.View.OnClickListener;\r\nimport android.widget.Button;\r\nimport android.widget.EditText;\r\nimport android.widget.Toast;\r\n\r\npublic class ProxAlertActivity extends Activity {\r\n    \r\n    private static final long MINIMUM_DISTANCECHANGE_FOR_UPDATE = 1; \/\/ in Meters\r\n    private static final long MINIMUM_TIME_BETWEEN_UPDATE = 1000; \/\/ in Milliseconds\r\n    \r\n    private static final long POINT_RADIUS = 1000; \/\/ in Meters\r\n    private static final long PROX_ALERT_EXPIRATION = -1; \r\n\r\n    private static final String POINT_LATITUDE_KEY = \"POINT_LATITUDE_KEY\";\r\n    private static final String POINT_LONGITUDE_KEY = \"POINT_LONGITUDE_KEY\";\r\n    \r\n    private static final String PROX_ALERT_INTENT = \r\n         \"com.javacodegeeks.android.lbs.ProximityAlert\";\r\n    \r\n    private static final NumberFormat nf = new DecimalFormat(\"##.########\");\r\n    \r\n    private LocationManager locationManager;\r\n    \r\n    private EditText latitudeEditText;\r\n    private EditText longitudeEditText;\r\n    private Button findCoordinatesButton;\r\n    private Button savePointButton;\r\n    \r\n    @Override\r\n    public void onCreate(Bundle savedInstanceState) {\r\n        \r\n        super.onCreate(savedInstanceState);\r\n        setContentView(R.layout.main);\r\n        \r\n        locationManager = (LocationManager) getSystemService(Context.LOCATION_SERVICE);\r\n\r\n        locationManager.requestLocationUpdates(\r\n                        LocationManager.GPS_PROVIDER, \r\n                        MINIMUM_TIME_BETWEEN_UPDATE, \r\n                        MINIMUM_DISTANCECHANGE_FOR_UPDATE,\r\n                        new MyLocationListener()\r\n        );\r\n        \r\n        latitudeEditText = (EditText) findViewById(R.id.point_latitude);\r\n        longitudeEditText = (EditText) findViewById(R.id.point_longitude);\r\n        findCoordinatesButton = (Button) findViewById(R.id.find_coordinates_button);\r\n        savePointButton = (Button) findViewById(R.id.save_point_button);\r\n        \r\n        findCoordinatesButton.setOnClickListener(new OnClickListener() {            \r\n            @Override\r\n            public void onClick(View v) {\r\n                populateCoordinatesFromLastKnownLocation();\r\n            }\r\n        });\r\n        \r\n        savePointButton.setOnClickListener(new OnClickListener() {            \r\n            @Override\r\n            public void onClick(View v) {\r\n                saveProximityAlertPoint();\r\n            }\r\n        });\r\n       \r\n    }\r\n    \r\n    private void saveProximityAlertPoint() {\r\n        Location location = \r\n            locationManager.getLastKnownLocation(LocationManager.GPS_PROVIDER);\r\n        if (location==null) {\r\n            Toast.makeText(this, \"No last known location. Aborting...\", \r\n                Toast.LENGTH_LONG).show();\r\n            return;\r\n        }\r\n        saveCoordinatesInPreferences((float)location.getLatitude(),\r\n               (float)location.getLongitude());\r\n        addProximityAlert(location.getLatitude(), location.getLongitude());\r\n    }\r\n\r\n    private void addProximityAlert(double latitude, double longitude) {\r\n        \r\n        Intent intent = new Intent(PROX_ALERT_INTENT);\r\n        PendingIntent proximityIntent = PendingIntent.getBroadcast(this, 0, intent, 0);\r\n        \r\n        locationManager.addProximityAlert(\r\n            latitude, \/\/ the latitude of the central point of the alert region\r\n            longitude, \/\/ the longitude of the central point of the alert region\r\n            POINT_RADIUS, \/\/ the radius of the central point of the alert region, in meters\r\n            PROX_ALERT_EXPIRATION, \/\/ time for this proximity alert, in milliseconds, or -1 to indicate no expiration \r\n            proximityIntent \/\/ will be used to generate an Intent to fire when entry to or exit from the alert region is detected\r\n       );\r\n        \r\n       IntentFilter filter = new IntentFilter(PROX_ALERT_INTENT);  \r\n       registerReceiver(new ProximityIntentReceiver(), filter);\r\n       \r\n    }\r\n\r\n    private void populateCoordinatesFromLastKnownLocation() {\r\n        Location location = \r\n            locationManager.getLastKnownLocation(LocationManager.GPS_PROVIDER);\r\n        if (location!=null) {\r\n            latitudeEditText.setText(nf.format(location.getLatitude()));\r\n            longitudeEditText.setText(nf.format(location.getLongitude()));\r\n        }\r\n    }\r\n    \r\n    private void saveCoordinatesInPreferences(float latitude, float longitude) {\r\n        SharedPreferences prefs = \r\n           this.getSharedPreferences(getClass().getSimpleName(),\r\n                           Context.MODE_PRIVATE);\r\n        SharedPreferences.Editor prefsEditor = prefs.edit();\r\n        prefsEditor.putFloat(POINT_LATITUDE_KEY, latitude);\r\n        prefsEditor.putFloat(POINT_LONGITUDE_KEY, longitude);\r\n        prefsEditor.commit();\r\n    }\r\n    \r\n    private Location retrievelocationFromPreferences() {\r\n        SharedPreferences prefs = \r\n           this.getSharedPreferences(getClass().getSimpleName(),\r\n                           Context.MODE_PRIVATE);\r\n        Location location = new Location(\"POINT_LOCATION\");\r\n        location.setLatitude(prefs.getFloat(POINT_LATITUDE_KEY, 0));\r\n        location.setLongitude(prefs.getFloat(POINT_LONGITUDE_KEY, 0));\r\n        return location;\r\n    }\r\n    \r\n    public class MyLocationListener implements LocationListener {\r\n        public void onLocationChanged(Location location) {\r\n            Location pointLocation = retrievelocationFromPreferences();\r\n            float distance = location.distanceTo(pointLocation);\r\n            Toast.makeText(ProxAlertActivity.this, \r\n                    \"Distance from Point:\"+distance, Toast.LENGTH_LONG).show();\r\n        }\r\n        public void onStatusChanged(String s, int i, Bundle b) {            \r\n        }\r\n        public void onProviderDisabled(String s) {\r\n        }\r\n        public void onProviderEnabled(String s) {            \r\n        }\r\n    }\r\n    \r\n}\r\n<\/pre>\n
In the onCreate<\/a> method we hook up the location manager with a custom class that implements the LocationListener<\/a> interface and allows to get notified on location changes via the onLocationChanged<\/a> method. We will see how to handle the updates later. We also find the various UI widgets and attach OnClickListener<\/a>s to the buttons. 
 
<\/div> <\/div><\/p>\n
When the user wants to find his current coordinates, the \u201cpopulateCoordinatesFromLastKnownLocation\u201d method is invoked. Inside that, we use the getLastKnownLocation<\/a> method and retrieve a Location<\/a> object. The EditText<\/a>s are then populated with the retrieved location information.<\/p>\n
Similarly, when the user wants to save the point and provide alerts for that (\u201csaveProximityAlertPoint\u201d), the location info is first retrieved. Then, we save the latitude<\/a> and longitude<\/a> information as preference data using the SharedPreferences<\/a> class and more specifically the SharedPreferences.Editor<\/a>. Finally, we create a PendingIntent<\/a> by using the getBroadcast<\/a> static method. For the encapsulated Intent<\/a>, we create an IntentFilter<\/a> and use the registerReceiver<\/a> method to associate a custom BroadcastReceiver<\/a> with the specific intent filter. Note that this binding could alternatively be achieved in a declarative way using the manifest file.<\/p>\n
Now let’s examine how we handle user’s location changes. In the implemented method of the \u201cMyLocationListener\u201d class, we extract the stored location info (\u201cretrievelocationFromPreferences\u201d) from the SharedPreferences<\/a> class. Then, we use the distanceTo<\/a> method to calculate the distance between the two locations, the current one and the one corresponding to the point of interest. This is done for debugging purposes, so that we know if we have actually entered the area around the point.<\/p>\n
The final step is to handle the events of entering the area of the point of interest. This is done inside the \u201cProximityIntentReceiver\u201d class that extends the BroadcastReceiver<\/a> and responds to the custom intent that we attached to the location manager when adding the proximity alert. The handling occurs inside the onReceive<\/a> method, which gets invoked upon event. Inside that, we retrieve the value of the KEY_PROXIMITY_ENTERING<\/a> key from the associated intent, which indicates whether a proximity alert is entering (true) or exiting (false). The code is the following:<\/p>\n
package com.javacodegeeks.android.lbs;\r\n\r\nimport android.app.Notification;\r\nimport android.app.NotificationManager;\r\nimport android.app.PendingIntent;\r\nimport android.content.BroadcastReceiver;\r\nimport android.content.Context;\r\nimport android.content.Intent;\r\nimport android.graphics.Color;\r\nimport android.location.LocationManager;\r\nimport android.util.Log;\r\n\r\npublic class ProximityIntentReceiver extends BroadcastReceiver {\r\n    \r\n    private static final int NOTIFICATION_ID = 1000;\r\n\r\n    @Override\r\n    public void onReceive(Context context, Intent intent) {\r\n        \r\n        String key = LocationManager.KEY_PROXIMITY_ENTERING;\r\n\r\n        Boolean entering = intent.getBooleanExtra(key, false);\r\n        \r\n        if (entering) {\r\n            Log.d(getClass().getSimpleName(), \"entering\");\r\n        }\r\n        else {\r\n            Log.d(getClass().getSimpleName(), \"exiting\");\r\n        }\r\n        \r\n        NotificationManager notificationManager = \r\n            (NotificationManager) context.getSystemService(Context.NOTIFICATION_SERVICE);\r\n        \r\n        PendingIntent pendingIntent = PendingIntent.getActivity(context, 0, null, 0);        \r\n        \r\n        Notification notification = createNotification();\r\n        notification.setLatestEventInfo(context, \r\n            \"Proximity Alert!\", \"You are near your point of interest.\", pendingIntent);\r\n        \r\n        notificationManager.notify(NOTIFICATION_ID, notification);\r\n        \r\n    }\r\n    \r\n    private Notification createNotification() {\r\n        Notification notification = new Notification();\r\n        \r\n        notification.icon = R.drawable.ic_menu_notifications;\r\n        notification.when = System.currentTimeMillis();\r\n        \r\n        notification.flags |= Notification.FLAG_AUTO_CANCEL;\r\n        notification.flags |= Notification.FLAG_SHOW_LIGHTS;\r\n        \r\n        notification.defaults |= Notification.DEFAULT_VIBRATE;\r\n        notification.defaults |= Notification.DEFAULT_LIGHTS;\r\n        \r\n        notification.ledARGB = Color.WHITE;\r\n        notification.ledOnMS = 1500;\r\n        notification.ledOffMS = 1500;\r\n        \r\n        return notification;\r\n    }\r\n    \r\n}\r\n<\/pre>\n
The code is pretty straightforward. After we determine whether we have an entering or exiting proximity alert, we are ready to provide a custom notification. To do so, we first take reference of the appropriate service, i.e. the NotificationManager<\/a>. Through that service, we may send alerts to the user, wrapped around Notification<\/a> objects. The notifications can be customized upon will and may include vibration<\/a>, flashing lights<\/a> etc. We also added a specific icon that will appear to the status bar. The setLatestEventInfo<\/a> is preferred when we just want  to add a basic title and text message. You can find more about notifications here<\/a>. Additionally, we can use a PendingIntent<\/a> in order to define an activity to be invoked when the user acknowledges the notification by clicking on it. However, to keep things simple, I do not use an intent to be launched in my example.<\/p>\n
Finally, let’s see what the Android manifest file looks like:<\/p>\n
<?xml version=\"1.0\" encoding=\"utf-8\"?>\r\n\r\n<manifest xmlns:android=\"http:\/\/schemas.android.com\/apk\/res\/android\"\r\n      package=\"com.javacodegeeks.android.lbs\"\r\n      android:versionCode=\"1\"\r\n      android:versionName=\"1.0\">\r\n      \r\n    <application android:icon=\"@drawable\/icon\" android:label=\"@string\/app_name\">\r\n        \r\n        <activity android:name=\".ProxAlertActivity\"\r\n                  android:label=\"@string\/app_name\">\r\n            <intent-filter>\r\n                <action android:name=\"android.intent.action.MAIN\" \/>\r\n                <category android:name=\"android.intent.category.LAUNCHER\" \/>\r\n            <\/intent-filter>\r\n        <\/activity>     \r\n\r\n    <\/application>\r\n    \r\n    <uses-sdk android:minSdkVersion=\"3\" \/>\r\n   \r\n    <uses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\" \/>\r\n    <uses-permission android:name=\"android.permission.ACCESS_MOCK_LOCATION\" \/> \r\n    <uses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\" \/>\r\n    <uses-permission android:name=\"android.permission.VIBRATE\" \/>\r\n\r\n<\/manifest> \r\n<\/pre>\n
Nothing special here, just remember to add the necessary permissions, i.e.<\/p>\n