Developing the “Places In My Proximity” Android Service

More coming soon!

Developing the “Retailer Rewards” Class – a POJO Requesting Campaign Details from the “Retailer Campaign” Server-side RESTful Service

More coming soon!

Developing the “Consumer Settings Activity” and Supporting XML Configuration Files

More coming soon!

Developing the “Rewards Notification” Class

More coming soon!

Developing the “Display Retailer Reward Activity” Class

More coming soon!

Now let’s actually create something fun and useful.  First we need an idea.  And I have a good one!

Exercising Core Location-Based Features Using the Places API

Let’s quickly identify some core location-based features.  These features are made possible by the ability of smart phones to track their GPS location and use GPS coordinates within applications to correlate user location to people and places in proximity to that location.  Generally, the following is a list of such features:

• Ability to identify and publish current location
• Search for places that are in proximity to a given location
• Obtain details about a specific place, usually selected from a proximity search
• Generate a proximity alert upon entering a location proximity
• Generate a proximity alert upon exiting a location proximity

Now, real innovation comes from your ability to enhance those features.  For example, let’s say your smart phone contains an application that alerts you to store specials as you come within proximity to participating stores.  So one day you are driving by and a proximity alert alerts you to a store special (or discount) at your favorite store.  But you don’t have time, and drive on by.

Now let’s say you drive by the same store on your return home.  Since you are within proximity to that store again, you get another proximity alert.  However, this time the application somehow knows you were nearby about an hour ago, and doubles the discount offered earlier.  You are excited and drive straight to the store.

That’s real innovation enhancing the core location-based features we discussed earlier.

Developing an Android-Based Mobile Application Using the Places API – Getting Started

As developers, we tend to learn new concepts and techniques best through examples.  Given the example we discussed earlier in enhancing the core location-based features, let’s develop this into a working mobile application using the Android platform.  To review, we stated the following:

For example, let’s say your smart phone contains an application that alerts you to store specials as you come within proximity to participating stores.  So one day you are driving by and a proximity alert “alerts” you to a store special (or discount) at your favorite store.  But you don’t have time, and drive on by.

Now let’s say you drive by the same store on your return home.  Since you are within proximity to that store again, you get another proximity alert.  However, this time the application somehow “knows” you were nearby about an hour ago, and doubles the discount offered earlier.  You are excited and drive straight to the store.

In order to tackle this, we need to better understand are requirements and end goals.

Use Cases

A great place to start is defining the Use Cases.  Of course we need to identify our key Actors first.  I see the following:

• Retailer
• Consumer
• System

Per Actor, the Use Cases are as follows:

1. Retailer - ability to manage discounts and rules by defining campaigns, similar to CRM and relational marketing
2. Retailer - report results of campaigns
3. Consumer - enable/disable proximity alerts
4. Consumer - ability to select/filter retailers of interest
5. Consumer - ability to select proximity alert radius
6. Consumer - provide display, store, and retrieve functionality for store specials/discounts
7. System - record all consumer proximity alert activities
8. System - manage retailer registrations

Considerations

Let’s identify some considerations and assumptions to make our development simple and well-defined.

We will track retailers and campaigns, and consumer proximity alert activities on the server using RESTful services.  We’ll generate a quick report of customer proximity alert activities by querying the database and returning results in either JSON or XML.

We will assume a standard campaign with simple rules used by all retailers and exclude a full-blown retailer campaign management process.  We will assume two or three registered retailers and exclude a full-blown retailer registration process.

And we will assume store specials/discounts never expire! 

Now did you think we were done?  We need to think about how we should manage the actual redemption of a reward.  We can’t assume the consumer will just click a button.  Therefore we need a website for the retailer to access and manage consumer reward redemption’s and basic reporting needs.

And lastly, you may wonder what technology I have chosen for the server-side.  It is ASP.NET MVC. as it is easy to create RESTful services supported by POCO’s, as Business Objects, and working with DTO’s and Repositories.  Click here to review my previous post for more information on POCO’s, as Business Objects, DTO’s, and Repositories.

Design Overview

Per our Considerations above,

• we will require a database to store retailer and customer information
• we will also require RESTful services to support the retailer and client requests (just a handful)
• and lastly, we need to provide several application screens for management of user configuration settings and display and persistence of store specials/discounts

Entity Diagram

We will define our data model (or entity diagram) as follows:

Entity Diagram

Note that there is no relationship between Retailers and Campaigns.  Normally one would exist (e.g., one-to-many), but we are assuming that all retailers are using the same campaign since we are excluding the retailer campaign management process per our considerations.

Services

Our mobile application is considered a client that requires services to provide the complete system functionality.  Remember that system functionality is required by both retailers and consumers, and all retailer relevant information is stored on the server.  Therefore, we define our required services as follows:

1. Retrieve campaign reward for retailer service (assumes consumer has entered retailer proximity).
2. Record consumer proximity visitation service (consumer enters retailer proximity).
3. Redeem consumer reward service (consumer makes a purchase at the retailer and redeems reward).
4. Retrieve campaign results service (used to report on campaign success).
5. Optional:  If we decided to manage campaigns, we would add a campaign management service.

Application Screens

Our mobile application needs several screens to provide basic settings management and rewards display/management functionality.

The required screens are:

1. Mobile Client – User Configuration Settings
2. Mobile Client – List of Retailer Rewards Display
3. Mobile Client – Detail Retailer Reward Display
4. Server - Redeem Consumer Reward

More on Design – Flushing Out the Details

We’ve already designed our data model, spec’ed our services, and identified our application screens.  Since we are tapping into location-based features, we need to discuss and agree on certain design strategies to allow us to be a mobile friendly mobile application, and not one that sucks battery life, or lives in the user thread (thus, being a bad citizen), etc…

We need a way to identify the places that match the user’s selected categories, and are within the user’s target proximity radius.

Therefore it makes sense for us to create a service that periodically call’s the place’s search API, and return those places that are within the user’s current proximity. From these results, we can easily filter those that match the user’s selected categories.

In general, our mobile application will need the following:

• A service that provides “who is within my proximity”.
• A service that provides details on a retailer, e.g., currently running campaigns and relevant rewards.
• A class that manages and retrieves user proximity, category, and enable/disable settings.
• An activity to display “who is in my proximity”, on-demand.
• A POJO requesting retailer campaign attributes, e.g., rewards. Note, this requires a server-side RESTful service.
• An notification to notify user of retailer reward.
• An activity to display retailer reward.
• An activity to display and manage “user received” retailer rewards. Note, we’ll use local persistence.

And our server-side application will require the following:

• A retailer campaign manager class.
• A “look up” consumer’s information and reward(s) class.
• A redeem consumer reward(s) class.
• A generate reports class.

UML Diagrams

Let’s describe some general classes that depict our system design as follows:

Class Diagram - Places In Proximity

For brevity, I am showing classes that belong to all components found in our system, without showing a more detailed architectural, or component diagram.

And we’ll describe the sequence through those classes for the core use cases in retrieving places in proximity as follows:

Sequence Diagram - Places in Proximity

Note that I did skip some important calls to the Android API to help keep our focus on the main sequence per our use cases.

We’ll start developing the mobile application next.

Enhancements Excluded

The following enhancements are my opinions of details required to make this a practical application.  Since my intention focuses on location-based concepts, not full application development, some application features are excluded as follows:

• Proper handling (both system and user interface) of the volume of reward notifications received by client.  If left unchecked, this will get messy, real fast!
• Consumer reward deletion.  The item above should actually manage this.
• Avoid duplicate reward notifications.  Again, the top item should manage this.
• Retailer campaign management.
• Expiring rewards by date at client.
• Expiring/deletion rewards after redemption at client.

In Part 3 we will start tackling the code for our location-based mobile application.  See you in Part 3.

This will open up innovative thinking for businesses trying to attract more customers, and enhance the services of existing customers.

As developers, we have a great opportunity to move mobile application development from cheap Soundboard applications, to powerful, business savvy applications capable of legitimizing mobile’s presence as a significant business contributor.

I plan to discuss all details required for you to get started developing these truly innovative mobile applications on the Android platform.

And as a bonus, I will discuss the difference between Proximity Alert and Location-based Mobile Applications, and how the two can be combined to create an even higher level of innovation. We will discuss these details in the last part.

Let’s get started with Part 1 to identify the items we need to complete before we can develop using the Places API.  If you’re wondering if it’s more involved than the other API’s. You’re right.  It is!

Requirements for Using Google’s Places API

The easy answer is that you need to fill out a registration form.  However, you will notice that an Adsense publisher id is required, and you may not have this.  Don’t fret.  You can fill out the application here to obtain your Adsense account.  It may take several days to get approved, so be patient. 

BTW, Once you have your Adsense account, you can register to use Google’s Places API by filling out this registration form.

Additionally, say you want to track your Adsense performance using URL Channels.  The aforementioned link will provide all the information you need.

Required:  Google Map API Key

In order to use Google’s Places API, you will need to register and obtain a Google Map’s API Key.  I created a post detailing exactly how to do this found here.

Getting Familiar with URL Authentication

Requests to certain Maps API web services now require digital signatures using a cryptographic key.  In fact, all Places API service requests require URL Authentication.  Click here to learn more.

Getting Familiar with Place Searches and Place Details

Per Google, and I quote

The Google Places API is a service that returns information about a “place” (hereafter referred to as a Place) — defined within this API as an establishment, a geographic location, or prominent point of interest — using an HTTP request. Place requests specify locations as latitude/longitude coordinates.

Two basic Place requests are available: a Place Search request and a Place Details request. Generally, a Place Search request is used to return candidate matches, while a Place Details request returns more specific information about a Place.

This service is designed for processing place requests generated by a user for placement of application content on a map; this service is not designed to respond to batch of offline queries, which are a violation of its terms of use.

As a developer, keep in mind that you usually first obtain a list of places that satisfy your filter, and allow a user drill-down into the details of a specific place.  Thus the existence of the two API’s.

Getting Familiar Calling the Places API

In general, calls to the Places API are made as follows.  This is an example of a call to the Place Search Service, and the client Id and signature are intentionally supplied as invalid:

// JSON:  http://maps.google.com/maps/api/place/search/json?location=40.717859,-73.9577937&radius=1600&client=clientId&sensor=true_or_false&signature=SIGNATURE

// XML:  http://maps.google.com/maps/api/place/search/xml?location=40.717859,-73.9577937&radius=1600&client=clientId&sensor=true_or_false&signature=SIGNATURE

This is asking for places for about a mile around Williamsburg, Brooklyn.

And you can expect a response formatted in JSON as follows:

{
 "status": "OK",
 "results": [ {
 "name": "Williamsburg",
 "types": [ "locality", "political" ],
 "icon": "http://maps.gstatic.com/mapfiles/place_api/icons/geocode-71.png",
 "reference": "ClRBAAAAXP...lHAPyHom2aG"
 }, {
 "name": "Greenpoint",
 "vicinity": "New York",
 "types": [ "neighborhood", "political" ],
 "icon": "http://maps.gstatic.com/mapfiles/place_api/icons/geocode-71.png",
 "reference": "CkQ_AAAAhd...MF45fwr44Ek"
 }, {
 "name": "Peter Luger Steakhouse",
 "vicinity": "Broadway, Brooklyn",
 "types": [ "restaurant", "food", "establishment" ],
 "icon": "http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png",
 "reference": "ClRCAAAAt3...6Nt7k11iQdT"
 }, {
 "name": "Music Hall of Williamsburg",
 "vicinity": "North 6th Street, Brooklyn",
 "types": [ "establishment" ],
 "icon": "http://maps.gstatic.com/mapfiles/place_api/icons/generic_business-71.png",
 "reference": "ClRFAAAAN...6UOKCbjv7Sxy"
 },
 ...additional results ...
 ],
 "html_attributions": [ ]
}

Or in XML as follows:

<PlaceSearchResponse>
 <status>OK</status>
 <result>
   <name>Williamsburg</name>
   <type>locality</type>
   <type>political</type>
   <icon>http://maps.gstatic.com/mapfiles/place_api/icons/geocode-71.png</icon>
   <reference>CkRAAAAAUhZG...Yy0b4-sd1zCUu9P8</reference>
 </result>
 <result>
   <name>Greenpoint</name>
   <vicinity>New York</vicinity>
   <type>neighborhood</type>
   <type>political</type>
   <icon>http://maps.gstatic.com/mapfiles/place_api/icons/geocode-71.png</icon>
   <reference>CkQ-AAAAHIDo...nYmSR8l52FmkMH6c</reference>
   <name>Peter Luger Steakhouse</name>
   <vicinity>Broadway, Brooklyn</vicinity>
   <type>restaurant</type>
   <type>food</type>
   <type>establishment</type>
   <icon>http://maps.gstatic.com/mapfiles/place_api/icons/restaurant-71.png</icon>
   <reference>ClRBAAAATIpR...mHSxoyiRcr_FVuww</reference>
 </result>
 ...additional results...
</PlaceSearchResponse>

In order to make a valid call, you are required to encrypt your URL with your private key and attach result as your signature.  Note that the call above excluded a valid client Id and signature.  In java, for example, you can create your signature as follows:

import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.net.URI;
import java.net.URISyntaxException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URL;
import java.io.BufferedReader;
import java.io.InputStreamReader;

public class UrlSigner {

 // Note: Generally, you should store your private key someplace safe
 // and read them into your code

 private static String keyString = "YOUR_PRIVATE_KEY";

 // The URL shown in these examples is a static URL which should already
 // be URL-encoded. In practice, you will likely have code
 // which assembles your URL from user or web service input
 // and plugs those values into its parameters.
 private static String urlString = "YOUR_URL_TO_SIGN";

 // This variable stores the binary key, which is computed from the string (Base64) key
 private static byte[] key;

 public static void main(String[] args) throws IOException,
 InvalidKeyException, NoSuchAlgorithmException, URISyntaxException {

   BufferedReader input = new BufferedReader(new InputStreamReader(System.in));

   String inputUrl, inputKey = null;

   // For testing purposes, allow user input for the URL.
   // If no input is entered, use the static URL defined above.
   System.out.println("Enter the URL (must be URL-encoded) to sign: ");
   inputUrl = input.readLine();
   if (inputUrl.equals("")) {
     inputUrl = urlString;
   }

   // Convert the string to a URL so we can parse it
   URL url = new URL(inputUrl);

   // For testing purposes, allow user input for the private key.
   // If no input is entered, use the static key defined above.
   System.out.println("Enter the Private key to sign the URL: ");
   inputKey = input.readLine();
   if (inputKey.equals("")) {
     inputKey = keyString;
   }

   UrlSigner signer = new UrlSigner(inputKey);
   String request = signer.signRequest(url.getPath(),url.getQuery());

   System.out.println("Signed URL :" + url.getProtocol() + "://" + url.getHost() + request);
 }

 public UrlSigner(String keyString) throws IOException {
   // Convert the key from 'web safe' base 64 to binary
   keyString = keyString.replace('-', '+');
   keyString = keyString.replace('_', '/');
   System.out.println("Key: " + keyString);
   this.key = Base64.decode(keyString);
 }

 public String signRequest(String path, String query) throws NoSuchAlgorithmException,
 InvalidKeyException, UnsupportedEncodingException, URISyntaxException {

   // Retrieve the proper URL components to sign
   String resource = path + '?' + query;

   // Get an HMAC-SHA1 signing key from the raw key bytes
   SecretKeySpec sha1Key = new SecretKeySpec(key, "HmacSHA1");

   // Get an HMAC-SHA1 Mac instance and initialize it with the HMAC-SHA1 key
   Mac mac = Mac.getInstance("HmacSHA1");
   mac.init(sha1Key);

   // compute the binary signature for the request
   byte[] sigBytes = mac.doFinal(resource.getBytes());

   // base 64 encode the binary signature
   String signature = Base64.encodeBytes(sigBytes);

   // convert the signature to 'web safe' base 64
   signature = signature.replace('+', '-');
   signature = signature.replace('/', '_');

   return resource + "&signature=" + signature;
 }
}

Given that you have your client Id, you should now be able to sign your request.

Next…

In Part 2, to keep things interesting and informing, we will discuss how to develop a mobile application, targeting the core features of this post.  We will create some fun location-based requirements and flush out the design details.

See you next time!

Enhancements

Therefore, we will implement three major enhancements in this post as follows:

• Process proximity alerts in the background by moving processing to an Android Service.  We will call our service PromityAlertService.
• We will use Android’s built-in NotificationManager to provide true Android notifications that appear and can be controlled within the status bar.
• And we will provide a checkbox in the ProximityAlertSetActivity screen allowing the user to enable/disable alerts anytime.  We will default to disabled to ensure that an alert is not fired immediately (since you are standing in the actual proximity of the alert when creating/editing the alert!).

Moving Proximity Alert Detection Processing to the Background by Creating an Android Service

More coming soon!

Enhancing Proximity Alert Notifications

When we add or save a proximity alert, we add the alert to the LocationManager via our AlertHelper class.  Note:  I have renamed the addProximityAlerts(…) method we used previously, to addProximityAlertsToLocationManager(…) to be more precise.  It is within this method that we add a PendingIntent that will perform a broadcast to our ProximityIntentReceiver (you may recall we created the ProximityIntentReceiver in a previous post).

The ProximityAlertHelper’s addProximityAlertsToLocationManager(…) method is as follows:

public boolean addProximityAlertsToLocationManager(Context caller, ArrayList<ProximityAlert> alerts) {
  if (initialized) {
    String context = Context.LOCATION_SERVICE;
    LocationManager mgr = ((LocationManager) caller.getSystemService(context));

    removeAlerts(caller);

    for (int i=1; i <alerts.size(); i++) {
      ProximityAlert alert = alerts.get(i);

      if (alert.Enabled) {
        Intent intent = new Intent(ProximityAlertActivity.class.getName());
        intent.putExtra("id", alert.Id);
        PendingIntent proximityIntent = PendingIntent.getBroadcast(caller, i, intent, PendingIntent.FLAG_CANCEL_CURRENT);
        float proxRadius = Float.parseFloat(PreferenceManager.getDefaultSharedPreferences(caller).getString("proxradius", "2"));
        mgr.addProximityAlert(alert.Lat, alert.Lng, proxRadius, -1, proximityIntent);
        proximityIntentsMap.put(alert, proximityIntent);
      }
    }
    return true;
  }

  return false;
}

Note that we add the alert’s id field to the intent in line 13.  We will use this later to retrieve the alert object upon processing a proximity alert notification event.

Let’s focus our attention on ProximityIntentReceiver class and discuss one addition to the onReceive(…) method.  We make our notification request to the NotificationManager here, on line 14, as follows:

public class ProximityIntentReceiver extends BroadcastReceiver implements IDebugSwitch {
  @Override
  public void onReceive(Context context, Intent intent) {
    String key = LocationManager.KEY_PROXIMITY_ENTERING;
    Boolean entering = intent.getBooleanExtra(key, false);

    if (entering) {
      ProximityAlert alert;
      try {
        alert = ProximityAlertHelper.getInstance().getAlert(intent.getExtras().getLong("id"));

        ArrayList<ProximityAlert> alerts = new ArrayList<ProximityAlert>();
        alerts.add(alert);
        NotifierHelper.sendNotification(context, ProximityAlertActivity.class, alerts);
      }
      catch (Exception ex) {
        Log.e(AppSettings.DEBUG_TAG, "General failure in ProximityIntentReceiver", ex);
        throw;
      }
    }
  }
}

Note, in line 10 the actual event’s alert object is retrieved using the id field we earlier stored in the intent.

And finally, I have created a helper class called NotifierHelper to handle the heavy lifting of adding a notification to the NoticationManager as follows:

public class NotifierHelper implements IDebugSwitch {
  private static final int NOTIFY_1 = 0x1001;

  public static void sendNotification(Context context, Class<?> activityToLaunch, ArrayList<ProximityAlert> alerts) {
    // String values should be stored in "strings.xml"
    // I show them here for convenience.

    NotificationManager notifier = (NotificationManager) context.getSystemService(Context.NOTIFICATION_SERVICE);

    // Create this outside the button so we can increment the number drawn over the notification icon,
    // indicating the number of alerts for this event.
    final Notification notify = new Notification(R.drawable.android_32, "", System.currentTimeMillis());

    // Add status bar notification
    notify.icon = R.drawable.android_32;
    notify.tickerText = "Proximo has new Proximity Alerts!";
    notify.when = System.currentTimeMillis();
    notify.number = alerts.size();
    notify.flags |= Notification.FLAG_AUTO_CANCEL;

    // Add lights
    notify.flags |= Notification.FLAG_SHOW_LIGHTS;
    notify.ledARGB = Color.WHITE;
    notify.ledOnMS = 500;
    notify.ledOffMS = 500;

// Add vibs
    notify.vibrate = new long[] {100, 200, 200, 200, 200, 200, 1000, 200, 200, 200, 1000, 200};

    Intent toLaunch = new Intent(context, activityToLaunch);
    toLaunch.putExtra("id", alerts.get(0).Id);
    PendingIntent intentBack = PendingIntent.getActivity(context, 0, toLaunch, 0);

    notify.setLatestEventInfo(context, "Proximity Alerts", "You have " + alerts.size() + " proximity alerts!", intentBack);
    notifier.notify(NOTIFY_1, notify);
  }

  public static void clear(Activity caller) {
    NotificationManager notifier = (NotificationManager) caller.getSystemService(Context.NOTIFICATION_SERVICE);
    notifier.cancelAll();
  }
}

Providing the Ability to Enable and Disable Proximity Alerts

Enabling and disabling proximity alerts is a fundamental feature that must not be overlooked.  Let’s first update the ProximityAlert entity to define an Enabled field.  The updates to the class are as follows:

public class ProximityAlert extends BaseEntity<ProximityAlert> {
  private static long nextId = 0;
  public long Id = -1;
  public double Lat = 0;
  public double Lng = 0;
  public String Name = "";
  public String Desc = "";
  public String Expiration = "";
  public int Month = -1;
  public int DayOfMonth = -1;
  public int Year = -1;
  public ArrayList<String> Items = new ArrayList<String>();
  public boolean Enabled = false;
  public boolean IsNew = true;

  public ProximityAlert(long id, double lat, double lng, String name, String desc, int month, int dayOfMonth, int year, boolean enabled) {
    this.Lat = lat;
    this.Lng = lng;
    this.Id = id;
    this.Name = name;
    this.Desc = desc;
    this.Month = month;
    this.DayOfMonth = dayOfMonth;
    this.Year = year;
    this.Enabled = enabled;
  }

  public ProximityAlert(double lat, double lng, String name, String desc, int month, int dayOfMonth, int year, boolean enabled) {
    this(nextId++, lat, lng, name,  desc, month, dayOfMonth, year, enabled);
  }

  public ProximityAlert(long id, String name, String desc) {
    this(id, 0.0, 0.0, name, desc, Calendar.getInstance().get(Calendar.MONTH), Calendar.getInstance().get(Calendar.DAY_OF_MONTH), Calendar.getInstance().get(Calendar.YEAR), false);
  }

  public JSONObject serializeToObj() {
    JSONObject serializedObj = new JSONObject();
    try {
      serializedObj.put("Id", this.Id);
      serializedObj.put("Lat", this.Lat);
      serializedObj.put("Lng", this.Lng);
      serializedObj.put("Name", this.Name);
      serializedObj.put("Desc", this.Desc);
      serializedObj.put("Month", this.Month);
      serializedObj.put("DayOfMonth", this.DayOfMonth);
      serializedObj.put("Year", this.Year);
      serializedObj.put("Enabled", this.Enabled);

      ArrayList<JSONObject> itemObjs = new ArrayList<JSONObject>();
      for (String item:this.Items) {
        JSONObject serializedItemObj = new JSONObject();
        serializedItemObj.put("Item", item);
        itemObjs.add(serializedItemObj);
      }
      serializedObj.put("Items", new JSONArray(itemObjs));
    }
    catch(Exception ex) {
      if (debug) Log.e(AppSettings.DEBUG_TAG, ex.getMessage(), ex);
    }

    return serializedObj;
  }

  public ProximityAlert deserializeFromObj(JSONObject obj) throws JSONException {
    this.Id = obj.getLong("Id");
    this.Lat = obj.getDouble("Lat");
    this.Lng = obj.getDouble("Lng");
    this.Name = obj.getString("Name");
    this.Desc = obj.getString("Desc");
    this.Month = obj.getInt("Month");
    this.DayOfMonth = obj.getInt("DayOfMonth");
    this.Year = obj.getInt("Year");
    this.Enabled = obj.getBoolean("Enabled");

    if (obj.has("Items")) {
      JSONArray jsonObjs = obj.getJSONArray("Items");
      this.Items = new ArrayList<String>(jsonObjs.length());
      for (int i=0; i<jsonObjs.length(); i++) {
        JSONObject itemObj = jsonObjs.getJSONObject(i);
        this.Items.add(itemObj.getString("Item"));
      }
    }

    return this;
  }
}

The highlighted lines above represent the changes required to support the Enabled field.

Now we take a look at how the Enabled field is used within the ProximityAlertHelper’s addProximityAlertsToLocationManager(…) method.  Line 9 below now requires that the alert be enabled before adding it to the LocationManager.

public boolean addProximityAlertsToLocationManager(Context caller, ArrayList<ProximityAlert> alerts) {
  if (initialized) {
    String context = Context.LOCATION_SERVICE;
    LocationManager mgr = ((LocationManager) caller.getSystemService(context));

    removeAlerts(caller);

    for (int i=1; i <alerts.size(); i++) {
      ProximityAlert alert = alerts.get(i);

      if (alert.Enabled) {
        Intent intent = new Intent(ProximityAlertActivity.class.getName());
        intent.putExtra("id", alert.Id);
        PendingIntent proximityIntent = PendingIntent.getBroadcast(caller, i, intent, PendingIntent.FLAG_CANCEL_CURRENT);
        float proxRadius = Float.parseFloat(PreferenceManager.getDefaultSharedPreferences(caller).getString("proxradius", "2"));
        mgr.addProximityAlert(alert.Lat, alert.Lng, proxRadius, -1, proximityIntent);
        proximityIntentsMap.put(alert, proximityIntent);
      }
    }
    return true;
  }

  return false;
}

And lastly, let’s see the actual enabled field within the ProximityAlertSetActivity screen.

Addition of Enabled Field into ProximityAlertSetActivity Screen

Note that the details of integrating the enabled field into the application are straightforward, and begin as follows:

boolean enabled = ((CheckBox) findViewById(R.id.CheckBox_alert_enabled)).isChecked();

I hope this discussion of enhancements to the Proximity Alert Mobile Application helps extend your understanding of how to properly build proximity alert applications using the Android platform.

I look forward to discussing new mobile development concepts in my next post!  Please come back soon!

Bonus: I have just added Part 4 to discuss important new enhancements to the Proximity Alert Application!

Capturing Proximity Alert Events

For the record, capturing proximity alerts is a fancy pants way of saying “set up a proximity alert reminder”.  The process is similar, in thought, to setting up an event reminder within your favorite calendaring tool.

We will capture a proximity alert event by creating a custom BroadcastReceiver that receives events upon the triggering of an actual alert by the LocationManager Service.  In general, there are six steps necessary to capture proximity alerts as follows:

1. Create a ProximityAlert object containing the fields of your proximity alert.  For example, name and description.
2. Create a BroadcastReceiver for receiving proximity alerts and override onReceive(…).
3. Create a ProximityAlertActivity.
4. Register the BroadcastReceiver by associating it to your ProximityAlertActivity as an IntentFilter, and registering all to the application context.
5. Retrieve a PendingIntent from the broadcast associated to the registered IntentFilter of your ProximityAlertActivity.
6. Add a proximity alert to the LocationManager by associating your ProximityAlert object to the PendingIntent.

Note, you handle the actual proximity alert event within your BroadcastReceiver‘s onReceive(…) method.  For example, you may simply write a Toast, displaying a description of the proximity, or location, found within the ProximityAlert object located within the bundle supplied within onReceive(…)’s intent parameter.

Details – Capturing Proximity Alert Events

The first thing our application needs to do, is register a BroadcastReceiver by associating it to a ProximityAlertActivity (see 4 above).  Let’s look at the code that supports this BroadcastReceiver registration process.

public class ProximityAlertHomeActivity extends ListActivity {
  private ArrayList<ProximityAlert> reminders = null;

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    String context = Context.LOCATION_SERVICE;
    ProximityAlertHelper.getInstance().initializeLocationManager(this, (LocationManager) getSystemService(context));

    loadReminders();
  }
}

public class ProximityAlertHelper {
  public static ProximityAlertHelper getInstance() {
    if (instanceOf == null) {
      instanceOf = new ProximityAlertHelper();
    }
    return instanceOf;
  }

  public String Provider;
  private static ProximityAlertHelper instanceOf;
  private static boolean initialized = false;
  private ProximityIntentReceiver receiver = null;

  public boolean initializeLocationManager(Context context, LocationManager locationManager) {
    Criteria criteria = new Criteria();
    criteria.setAccuracy(Criteria.ACCURACY_FINE);
    criteria.setAltitudeRequired(false);
    criteria.setBearingRequired(false);
    criteria.setCostAllowed(true);
    criteria.setPowerRequirement(Criteria.POWER_LOW);

    this.Provider = locationManager.getBestProvider(criteria, false);
    this.receiver = new ProximityIntentReceiver();

    IntentFilter filter = new IntentFilter(ProximityAlertActivity.class.getName());
    context.registerReceiver(this.receiver, filter);

    return initialized = true;
  }
}

Above, I show the call to ProximityAlertHelper.getInstance().initializeLocationManager(…) from the ProximityAlertHomeActivity’s onCreate(…) method.  This happens immediately at application startup.  Immediately afterwards, we see the ProximityAlertHelper.getInstance().initializeLocationManager(…) method that carries out the actual BroadcastReceiver registration.

Next, let’s look at the details involved in creating the BroadcastReceiver.  We implement our ProximityIntentReceiver class by inheriting from the BroadcastReceiver class as follows:

public class ProximityIntentReceiver extends BroadcastReceiver implements IDebugSwitch {
  @Override
  public void onReceive(Context context, Intent intent) {
    String key = LocationManager.KEY_PROXIMITY_ENTERING;

    Boolean entering = intent.getBooleanExtra(key, false);
    if (entering) {
      ProximityAlert alert;

      try {
        alert = new ProximityAlert(intent.getStringExtra("current"));
        Msg.ToastLong(context, "entered " + alert.Name);
        NotifierHelper.vibrate(context);
      } catch (JSONException ex) {
        ex.printStackTrace();
      }
    }
  }
}

Upon receiving an alert, we simply display a toast and vibrate the phone (lines 12 and 13).  Note that we retrieve the serialized AlertProximity object from the intent bundle, and deserialize it to an actual instance of AlertProximity by supplying the serialized string to the constructor (line 11).  This object contains the proximity alert information we can use to display to the user.  For more details on the AlertProximity class, see Part 2.

More coming soon!

Setting Proximity Alert Preferences

We will use Android’s PreferencesActivity class to manage our configuration settings.  We need to be able to configure the following preferences for our proximity alert mobile application:

• the minimum frequency to update location (to set a proximity alert),
• the minimum distance to update location (to set a proximity alert), and
• the proximity radius required to trigger a proximity alert

Before discussing further, let’s take a quick look at the actual Proximity Alert Preferences Screen.

Proximity Alert Preferences Activity Screen

Our ProximityAlertPreferencesActivity class provides the settings management we require.

public class ProximityAlertPreferencesActivity extends PreferenceActivity implements IDebugSwitch {
  public ProximityAlertPreferencesActivity() {
  }

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(null);
    addPreferencesFromResource(R.xml.settings);
  }
}

As you can see, all of the functionality is provided by Android’s PreferenceActivity base class.  We simply supply the resource file.  The following is the settings.xml resource file referenced by our AlertProximityPreferencesActivity class displayed above, and required to manage our proximity alert settings:

<?xml version="1.0" encoding="utf-8"?>
  <PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android">
    <PreferenceCategory android:title="Location Update Frequency" android:key="locupdate">
      <ListPreference
        android:title="Set Minimum Frequency"
        android:summary="How often to update location"
        android:key="mintimeinc"
        android:defaultValue="2000"
        android:entries="@array/minTimeIncs"
        android:entryValues="@array/minTimeVals" />
      <ListPreference
        android:title="Set Minimum Distance"
        android:summary="Minimum distance of movement necessary to update location"
        android:key="mindistance"
        android:defaultValue="2"
        android:entries="@array/minDistance"
        android:entryValues="@array/minDistanceVals"
      />
    </PreferenceCategory>
    <PreferenceCategory android:title="Proximity Radius" android:key="locupdatefreq">
      <ListPreference
        android:title="Set Proximity Radius"
        android:summary="Proximity radius necessary to trigger alert"
        android:key="proxradius"
        android:defaultValue="2"
        android:entries="@array/proxRadius"
        android:entryValues="@array/proxRadiusVals"
      />
    </PreferenceCategory>
  </PreferenceScreen>

And lastly, the following settingvalues.xml resource file contains the actual values required by the settings.xml resource file:

<?xml version="1.0" encoding="utf-8"?>
  <resources>
    <string-array name="minTimeIncs">
      <item name="0">0</item>
      <item name="1000">Every 1 second</item>
      <item name="2000">Every 2 seconds</item>
      <item name="5000">Every 5 seconds</item>
      <item name="10000">Every 10 seconds</item>
      <item name="30000">Every 30 seconds</item>
      <item name="60000">Every 1 minute</item>
      <item name="300000">Every 5 minutes</item>
      <item name="1800000">Every 30 minutes</item>
    </string-array>
    <string-array name="minTimeVals">
      <item name="0">0</item>
      <item name="1000">1000</item>
      <item name="2000">2000</item>
      <item name="5000">5000</item>
      <item name="10000">10000</item>
      <item name="30000">30000</item>
      <item name="60000">60000</item>
      <item name="300000">300000</item>
      <item name="1800000">1800000</item>
    </string-array>
    <string-array name="minDistance">
      <item name="1">1 meters</item>
      <item name="2">2 meters</item>
      <item name="3">3 meters</item>
      <item name="5">5 meters</item>
      <item name="10">10 meters</item>
      <item name="25">25 meters</item>
      <item name="50">50 meters</item>
      <item name="100">100 meters</item>
      <item name="250">250 meters</item>
      <item name="500">500 meters</item>
      <item name="1000">1000 meters</item>
    </string-array>
    <string-array name="minDistanceVals">
      <item name="1">1</item>
      <item name="2">2</item>
      <item name="3">3</item>
      <item name="5">5</item>
      <item name="10">10</item>
      <item name="25">25</item>
      <item name="50">50</item>
      <item name="100">100</item>
      <item name="250">250</item>
      <item name="500">500</item>
      <item name="1000">1000</item>
    </string-array>
    <string-array name="proxRadius">
      <item name="1">1 meters</item>
      <item name="2">2 meters</item>
      <item name="3">3 meters</item>
      <item name="5">5 meters</item>
      <item name="10">10 meters</item>
      <item name="25">25 meters</item>
      <item name="50">50 meters</item>
      <item name="100">100 meters</item>
      <item name="250">250 meters</item>
      <item name="500">500 meters</item>
      <item name="1000">1000 meters</item>
    </string-array>
    <string-array name="proxRadiusVals">
      <item name="1">1</item>
      <item name="2">2</item>
      <item name="3">3</item>
      <item name="5">5</item>
      <item name="10">10</item>
      <item name="25">25</item>
      <item name="50">50</item>
      <item name="100">100</item>
      <item name="250">250</item>
      <item name="500">500</item>
      <item name="1000">1000</item>
    </string-array>
  </resources>

And that’s it!  I believe Google’s Android platform is paving the way for both advancing mobile technologies and getting them quickly, and affordably, into consumers’ hands.

I hope this helps you design and create innovative, mobile-based Android applications.

Bonus: Please see Part 4 as I discuss important new enhancements to this Proximity Alert Application!

This is Brian Buikema.  See you next time!

Now the fun begins!

One Data Entity

As far as data models go, this one is simple.  One entity.  The ProximityAlertEntity.  As well as representing common DTO functionality, we will expand the ProximityEntity to include the repository functionality.  After all, this is a fairly simple application.  First, let’s look at the DTO functionality.  It includes both the fields representing our alert needs and the necessary JSON serialization/deserialization methods.

public class ProximityAlertReminder extends BaseEntity {
  private static long nextId = 0;
  public long Id = -1;
  public double Lat = 0;
  public double Lng = 0;
  public String Name = "";
  public String Desc = "";
  public int Month = -1;
  public int DayOfMonth = -1;
  public int Year = -1;
  public ArrayList<String> Items = new ArrayList<String>();

  public ProximityAlertReminder(long id, double lat, double lng, String name, String desc, int month, int dayOfMonth, int year) {
    this.Lat = lat;
    this.Lng = lng;
    this.Id = id;
    this.Name = name;
    this.Desc = desc;
    this.Month = month;
    this.DayOfMonth = dayOfMonth;
    this.Year = year;
  }

  public ProximityAlertReminder(double lat, double lng, String name, String desc, int month, int dayOfMonth, int year) {
    this(nextId++, lat, lng, name,  desc, month, dayOfMonth, year);
  }

  public ProximityAlertReminder(long id, String name, String desc) {
    this(id, 0.0, 0.0, name, desc, Calendar.getInstance().get(Calendar.MONTH), Calendar.getInstance().get(Calendar.DAY_OF_MONTH), Calendar.getInstance().get(Calendar.YEAR));
  }

  public ProximityAlertReminder(JSONObject obj) throws JSONException {
    deserializeFromObj(obj);
  }

  public ProximityAlertReminder(String serializedObj) throws JSONException {
    deserialize(serializedObj);
  }

  public Object getId() {
    return this.Id;
  }

  public JSONObject serializeToObj() {
    JSONObject serializedObj = new JSONObject();
    try {
      serializedObj.put("Id", this.Id);
      serializedObj.put("Lat", this.Lat);
      serializedObj.put("Lng", this.Lng);
      serializedObj.put("Name", this.Name);
      serializedObj.put("Desc", this.Desc);
      serializedObj.put("Month", this.Month);
      serializedObj.put("DayOfMonth", this.DayOfMonth);
      serializedObj.put("Year", this.Year);

      ArrayList itemObjs = new ArrayList();
      for (String item:this.Items) {
        JSONObject serializedItemObj = new JSONObject();
        serializedItemObj.put("Item", item);
        itemObjs.add(serializedItemObj);
      }

      serializedObj.put("Items", new JSONArray(itemObjs));
    }
    catch(Exception ex) {
      if (debug) Log.e(AppSettings.DEBUG_TAG, ex.getMessage(), ex);
    }

    return serializedObj;
  }

  public AlertReminder deserializeFromObj(JSONObject obj) throws JSONException {
    this.Id = obj.getLong("Id");
    this.Lat = obj.getDouble("Lat");
    this.Lng = obj.getDouble("Lng");
    this.Name = obj.getString("Name");
    this.Desc = obj.getString("Desc");
    this.Month = obj.getInt("Month");
    this.DayOfMonth = obj.getInt("DayOfMonth");
    this.Year = obj.getInt("Year");

    if (obj.has("Items")) {
      JSONArray jsonObjs = obj.getJSONArray("Items");
      this.Items = new ArrayList(jsonObjs.length());
      for (int i=0; i
        JSONObject itemObj = jsonObjs.getJSONObject(i);
        this.Items.add(itemObj.getString("Item"));
      }
    }

    return this;
  }
}

The ProximityAlertReminder repository functions are represented as static methods.  Note that we are writing using SharedPreferences and not the database for persistence.

public class ProximityAlertReminder extends BaseEntity<ProximityAlertReminder> {
  public static ArrayList<ProximityAlertReminder> load(Context caller) {
    ArrayList<ProximityAlertReminder> reminders = new ArrayList<ProximityAlertReminder>();
    try {
      SharedPreferences settingsActivity = PreferenceManager.getDefaultSharedPreferences(caller);
      String serializedReminders = settingsActivity.getString(caller.getString(R.string.reminders), "").trim();
      reminders = new ArrayList<ProximityAlertReminder>();

      if (serializedReminders.length() > 0) {
        JSONArray jsonObjs = new JSONArray(serializedReminders);
        for (int i=0; i<jsonObjs.length(); i++) {
          JSONObject itemObj = jsonObjs.getJSONObject(i);
          reminders.add(new ProximityAlertReminder(itemObj));
        }
      }

      if (reminders.size() == 0) {
        ProximityAlertReminder addReminder = new ProximityAlertReminder(-2, "<click to add new alert>", "Add";
        reminders.add(0, addReminder);
      }
    }
    catch (Exception ex) {
      Log.e(AppSettings.DEBUG_TAG, ex.getMessage(), ex);
    }

    return reminders;
  }

  public static ArrayList<ProximityAlertReminder> add(Context caller, ProximityAlertReminder reminder) {
    ArrayList<ProximityAlertReminder> reminders = load(caller);
    reminders.add(reminder);
    save(caller, reminders);

    return reminders;
  }

  public static boolean save(Context caller, ArrayList<ProximityAlertReminder> reminders) {
    boolean success = false;

    try {
      SharedPreferences.Editor prefEditor = PreferenceManager.getDefaultSharedPreferences(caller).edit();

      ArrayList<JSONObject> itemObjs = new ArrayList<JSONObject>(reminders.size());
      for (ProximityAlertReminder item:reminders) {
        JSONObject serializedItemObj = new JSONObject(item.serialize());
        itemObjs.add(serializedItemObj);
      }

      prefEditor.putString(caller.getString(R.string.reminders), new JSONArray(itemObjs).toString());
      prefEditor.commit();
      success = true;
    }
    catch (Exception ex) {
      Log.e(AppSettings.DEBUG_TAG, ex.getMessage(), ex);
      success = false;
    }

    return success;
  }

  public static boolean deleteAll(Context caller) {
    boolean success = false;

    try {
      SharedPreferences.Editor prefEditor = PreferenceManager.getDefaultSharedPreferences(caller).edit();
      prefEditor.putString(caller.getString(R.string.reminders), "");

      prefEditor.commit();
      success = true;
    }
    catch (Exception ex) {
      Log.e(AppSettings.DEBUG_TAG, ex.getMessage(), ex);
      success = false;
    }

    return success;
  }
}

These represent the CRUD based methods used in common entity storage and retrieval.

Setting Proximity Alerts

Let’s discuss how we will actually set a proximity alert.  We will take the approach that we will set a proximity alert based on our current physical location.  First, we must have a user interface that allow us to display the list of current proximity alerts, and add new proximity alerts.  Our ProximityAlertHomeActivity view will encompass the former, and, from an action initiated at the home activity, the ProximityAlertSetActivity will provide the later, the actual create and edit alert functionality.  Additionally, the ProximityAlertHelper class comprises the proximity alert technical functionality that makes this all work.

A screenshot of our ProximityAlertHomeActivity Screen is as follows:

Proximity Alert Home Activity Screen

The ProximityAlertHomeActivity class is as follows:

public class ProximityAlertHomeActivity extends ListActivity {
  private ArrayList<ProximityAlert> reminders = null;

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    String context = Context.LOCATION_SERVICE;
    ProximityAlertHelper.getInstance().initializeLocationManager(this, (LocationManager) getSystemService(context));

    loadReminders();
  }

  public void onListItemClick(ListView parent, View v, int position, long id)
  {
    if (position == 0) {
      Intent intent = new Intent(this, ProximityAlertSetActivity.class);
      startActivityForResult(intent, 0);
      return;
    }

    editReminder(v, position);
  }

  // Creates the menu items
  public boolean onCreateOptionsMenu(android.view.Menu menu) {
    getMenuInflater().inflate(R.menu.home, menu);
    return true;
  }

  // Handles item selections
  public boolean onOptionsItemSelected(android.view.MenuItem item) {
    switch (item.getItemId()) {
      case R.id.home_menu_add:
        Intent intent = new Intent(this, ProximityAlertSetActivity.class);
        startActivityForResult(intent, 0);
        return true;
      case R.id.home_menu_delall:
        DialogHelper.getInstance().displayConfirmationDialog(this, this.dialogResultHandler, "Confirmation", "Would you like to delete all alerts now?");
        return true;
      case R.id.home_menu_settings:
        intent = new Intent(this, ProximityAlertPreferencesActivity.class);
        startActivityForResult(intent, 0);
        return true;
      case R.id.home_menu_about:
        showDialog(0);
        return true;
    }

    return false;
  }

  @Override
  public void finish() {
    ProximityAlertHelper.getInstance().closeLocationManager(this);
    super.finish();
  }

  @Override
  public void onBackPressed() {
    ProximityAlertHelper.getInstance().closeLocationManager(this);
    super.onBackPressed();
  }

  protected Handler dialogResultHandler = new Handler() {
    @Override
    public void handleMessage(Message msg) {
      if (Boolean.parseBoolean(msg.obj.toString())) {
        ProximityAlertHomeActivity.this.reminders.clear();
        ProximityAlertHelper.getInstance().removeAlerts(ProximityAlertHomeActivity.this);
        ProximityAlert.deleteAll(ProximityAlertHomeActivity.this);
        Msg.ToastShort(ProximityAlertHomeActivity.this, "All Alerts Deleted");
        loadReminders();
      }
      else {
        Msg.ToastShort(ProximityAlertHomeActivity.this, "Canceled");
      }
    }
  };

  @Override
  protected Dialog onCreateDialog(int id) {
    // we have only one - defaulted to 0
    return DialogHelper.getInstance().displayAboutDialog(this);
  }

  @Override
  protected void onResume() {
    super.onResume();
    loadReminders();
  }

  protected void loadReminders() {
    setListAdapter(new ArrayAdapter<String>(this, android.R.layout.simple_list_item_1, loadFormattedAlertReminders()));
    ProximityAlertHelper.getInstance().addProximityAlerts(this, this.reminders);
  }

  protected void editReminder(View v, int position) {
    Intent intent = new Intent(v.getContext(), ProximityAlertSetActivity.class);
    intent.putExtra("current", this.reminders.get(position).serialize());
    startActivityForResult(intent, 0);
  }

  protected ArrayList<String> loadFormattedAlertReminders()
  {
    this.reminders = ProximityAlert.load(this);
    ArrayList<String> formattedReminders = new ArrayList<String>();

    for (ProximityAlert reminder:this.reminders) {
      formattedReminders.add(reminder.Name);
    }

    return formattedReminders;
  }
}

Note that much of the technical work is done by the ProximityAlertHelper class.

Of particular interest, is the fact that within the loadReminders(…) method, we both

• load the proximity alerts from persistent storage (e.g., SharedPreferences in our case) AND
• add them to the LocationManager

via the ProximityAlertHelper class.

Also of interest, within the onResume(…) method, we call the loadReminders(…) method to reload our proximity alerts upon resume.

Lastly, within the finish(…) method, we call AlertProximityHelper.getInstance(…).closeLocationManager(…) to both

• remove the proximity alerts from the LocationManager AND
• unregister our custom BroadcastReceiver called ProximityIntentReceiver (more on this later).

A screenshot of the ProximityAlertSetActivityScreen is as follows:

Proximity Alert Set Activity Screen

The following introduces our ProximityAlertSetActivity class.

public class ProximityAlertSetActivity extends Activity {
  private double lat = 00;
  private double lng = 00;
  private boolean newReminder = true;

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.alert_reminder);

    this.newReminder = !(getIntent().getExtras() != null && getIntent().getExtras().containsKey("current"));
    if (this.newReminder) {
      String context = Context.LOCATION_SERVICE;
      updateWithNewLocation(((LocationManager) getSystemService(context)).getLastKnownLocation(ProximityAlertHelper.getInstance().Provider));
    }
    else {
      ProximityAlert current = retrieveCurrentAlertReminder();
      ((TextView) findViewById(R.id.TextView_reminder_location_hdr)).setText("Lat:" + current.Lat + "\nLong:" + current.Lng);
      ((TextView) findViewById(R.id.EditText_reminder_name)).setText(current.Name);
      ((TextView) findViewById(R.id.EditText_reminder_desc)).setText(current.Desc);
      DatePicker picker = (DatePicker)findViewById(R.id.DatePicker_reminder_expiration);
      picker.updateDate(current.Year, current.Month, current.DayOfMonth);
    }
  }

  // Creates the menu items
  public boolean onCreateOptionsMenu(android.view.Menu menu) {
    getMenuInflater().inflate(R.menu.alert_reminder_add, menu);
    return true;
  }

  // Handles item selections
  public boolean onOptionsItemSelected(android.view.MenuItem item) {
    switch (item.getItemId()) {
      case R.id.add_menu_save:
        addAlert();
        return true;
      case R.id.add_menu_cancel:
        DialogHelper.getInstance().displayConfirmationDialog(this, this.dialogCancelResultHandler, "Confirmation", "Would you like to cancel adding this alert?");
        return true;
      case R.id.add_menu_del:
        DialogHelper.getInstance().displayConfirmationDialog(this, this.dialogDeleteResultHandler, "Confirmation", "Would you like to delete this alert?");
        return true;
      case R.id.add_menu_settings:
        Intent intent = new Intent(this, ProximityAlertPreferencesActivity.class);
        startActivityForResult(intent, 0);
        return true;
      case R.id.add_menu_about:
        showDialog(0);
        return true;
    }

    return false;
  }

  protected ProximityAlert retrieveCurrentAlertReminder() {
    ProximityAlert current = null;

    try {
      current = new ProximityAlert(getIntent().getExtras().getString("current"));
    }
    catch (JSONException ex) {
      Log.e(AppSettings.DEBUG_TAG, "JSON failure in AlertReminderActivity", ex);
    }

    return current;
  }

  protected void addAlert() {
    String name = ((TextView) findViewById(R.id.EditText_reminder_name)).getText().toString();
    String desc = ((TextView) findViewById(R.id.EditText_reminder_desc)).getText().toString();
    DatePicker picker = (DatePicker)findViewById(R.id.DatePicker_reminder_expiration);

    // add proximity alert intent
    if (newReminder) {
      ProximityAlert reminder = new ProximityAlert(this.lat, this.lng, name, desc, picker.getMonth(), picker.getDayOfMonth(), picker.getYear());
      ProximityAlertHelper.getInstance().addProximityAlerts(this, ProximityAlert.add(this, reminder));
    }

    finish();
  }

  protected Handler dialogCancelResultHandler = new Handler() {
    @Override
    public void handleMessage(Message msg) {
      if (Boolean.parseBoolean(msg.obj.toString())) {
        Msg.ToastShort(ProximityAlertSetActivity.this, "Alert has been canceled!");
        finish();
      }
      else {
        Msg.ToastShort(ProximityAlertSetActivity.this, "Alert has NOT been canceled");
      }
    }
  };

  protected Handler dialogDeleteResultHandler = new Handler() {
    @Override
    public void handleMessage(Message msg) {
      if (Boolean.parseBoolean(msg.obj.toString())) {
        ProximityAlert current = retrieveCurrentAlertReminder();
        ProximityAlertHelper.getInstance().removeAlert(ProximityAlertSetActivity.this, current);
        Msg.ToastShort(ProximityAlertSetActivity.this, "Alert has been deleted!");
        finish();
      }
      else {
        Msg.ToastShort(ProximityAlertSetActivity.this, "Alert has NOT been deleted");
      }
    }
  };

  @Override
  protected Dialog onCreateDialog(int id) {
    // we have only one - defaulted to 0
    return DialogHelper.getInstance().displayAboutDialog(this);
  }

  //Register for the updates when Activity is in foreground
  @Override
  protected void onResume() {
    super.onResume();
    if (this.newReminder) {
      ProximityAlertHelper.getInstance().requestLocationUpdates(this, this.locationListener);
    }
  }

  // Stop the updates when Activity is paused
  @Override
  protected void onPause() {
    super.onPause();
    if (this.newReminder) {
      String context = Context.LOCATION_SERVICE;
      ((LocationManager) getSystemService(context)).removeUpdates(this.locationListener);
    }
  }

  private final LocationListener locationListener = new LocationListener() {
    public void onLocationChanged(Location location) {
      updateWithNewLocation(location);
    }

    public void onProviderDisabled(String provider) {
      updateWithNewLocation(null);
    }

    public void onProviderEnabled(String provider) {
    }

    public void onStatusChanged(String provider, int status, Bundle extras) {
    }
  };

  private void updateWithNewLocation(Location location) {
    String latLongString;
    TextView myLocationText = (TextView) findViewById(R.id.TextView_reminder_location_hdr);
    if (location != null) {
      this.lat = location.getLatitude();
      this.lng = location.getLongitude();
      latLongString = "Lat:" + lat + "\nLong:" + lng;
    } else {
      latLongString = "No location found - Please move more than " + AppSettings.MinDistance + " from current position";
    }

    myLocationText.setText("Your Current Position is:\n" + latLongString);
  }
}

The LocationListener allows us to refresh the view (e.g., position status) as our longitude and latitude changes due to changes in our physical location.  Or, more specifically, our smart phone detects changes to its physical location.  Again, much of the technical lifting is done by the ProximityAlertHelper class.

And lastly, the ProximityAlertHelper class is implemented as follows:

public class ProximityAlertHelper {
  public static ProximityAlertHelper getInstance() {
    if (instanceOf == null) {
      instanceOf = new ProximityAlertHelper();
    }
    return instanceOf;
  }

  public String Provider;

  private static ProximityAlertHelper instanceOf;
  private static boolean initialized = false;
  private LocationListener locationListener;
  private HashMap<ProximityAlert, PendingIntent> proximityIntentsMap = new HashMap<ProximityAlert, PendingIntent>();
  private ProximityIntentReceiver receiver = null;

  public boolean initializeLocationManager(Context context, LocationManager locationManager) {
    Criteria criteria = new Criteria();
    criteria.setAccuracy(Criteria.ACCURACY_FINE);
    criteria.setAltitudeRequired(false);
    criteria.setBearingRequired(false);
    criteria.setCostAllowed(true);
    criteria.setPowerRequirement(Criteria.POWER_LOW);

    this.Provider = locationManager.getBestProvider(criteria, false);
    this.receiver = new ProximityIntentReceiver();

    IntentFilter filter = new IntentFilter(ProximityAlertActivity.class.getName());
    context.registerReceiver(this.receiver, filter);

    return initialized = true;
  }

  public void requestLocationUpdates(Context caller, LocationListener locationListener) {
    if (initialized) {
      this.locationListener = locationListener;
      String context = Context.LOCATION_SERVICE;
      LocationManager mgr = ((LocationManager) caller.getSystemService(context));
      mgr.removeUpdates(locationListener);

      mgr.removeUpdates(locationListener);
      long minInc = Long.parseLong(PreferenceManager.getDefaultSharedPreferences(caller).getString("mintimeinc", "2000"));
      float minDistance = Float.parseFloat(PreferenceManager.getDefaultSharedPreferences(caller).getString("mindistance", "2"));
      mgr.requestLocationUpdates(this.Provider, minInc, minDistance, locationListener);
    }
  }

  public boolean addProximityAlerts(Context caller, ArrayList<ProximityAlert> reminders) {
    if (initialized) {
      String context = Context.LOCATION_SERVICE;
      LocationManager mgr = ((LocationManager) caller.getSystemService(context));

      removeAlerts(caller);

      for (int i=1; i <reminders.size(); i++) {
        ProximityAlert reminder = reminders.get(i);
        Intent intent = new Intent(ProximityAlertActivity.class.getName());
        intent.putExtra("current", reminder.serialize());
        PendingIntent proximityIntent = PendingIntent.getBroadcast(caller, i, intent, 0);
        float proxRadius = Float.parseFloat(PreferenceManager.getDefaultSharedPreferences(caller).getString("proxradius", "2"));
        mgr.addProximityAlert(reminder.Lat, reminder.Lng, proxRadius, -1, proximityIntent);
        proximityIntentsMap.put(reminder, proximityIntent);
      }
      return true;
    }
    return false;
  }

  public void removeAlert(Context caller, ProximityAlert reminder) {
    if (initialized) {
      String context = Context.LOCATION_SERVICE;
      LocationManager mgr = ((LocationManager) caller.getSystemService(context));

      removeAlert(mgr, reminder);
    }
  }

  public void removeAlerts(Context caller) {
    if (initialized) {
      String context = Context.LOCATION_SERVICE;
      LocationManager mgr = ((LocationManager) caller.getSystemService(context));

      for (ProximityAlert reminder:this.proximityIntentsMap.keySet()) {
        removeAlert(mgr, reminder);
      }
    }
  }

  public void closeLocationManager(Context caller) {
    if (initialized) {
      try {
        String context = Context.LOCATION_SERVICE;
        LocationManager mgr = ((LocationManager) caller.getSystemService(context));

        if (this.locationListener != null) {
          mgr.removeUpdates(this.locationListener);
        }

        removeAlerts(caller);

        caller.unregisterReceiver(this.receiver);
      }
      catch(Exception ex) {
        Log.e(AppSettings.DEBUG_TAG, "exception thrown in closeLocationManager(...)", ex);
      }
    }
  }

  protected void removeAlert(LocationManager mgr, ProximityAlert reminder) {
    if (initialized) {
      if (reminder.Name.trim().length() > 0) {
        mgr.removeProximityAlert(this.proximityIntentsMap.get(reminder));
      }
    }
  }
}

As new proximity alerts are added via the LocationManager, we first remove the old ones and add all alerts again.

Note that the actual xml layout and menu files will be included in the download.

We will continue our discussion on

• Capturing Promity Alert Events and
• Setting Proximity Alert Preferences

in Part 3 of Developing Proximity Alerts for Mobile Applications using the Android Platform.

More coming soon!

We’ve all used Event Reminders as a way to remind ourselves of important events.  These reminders are time triggered, that is, our reminders are activated at a specific time in the future.  Birthdays, meetings, time to pay the bills are all examples of Event Reminders.

But let’s say you don’t know the specific time of an event, but would like to be reminded, or alerted, of the event when you are actually at a particular place.  For example, Grandma’s garbage disposal is broken, and you will fix it the next time you go to her house.  And say you don’t know the next time you are coming over, but would benefit from an alert that is activated when you actually arrive at her house.

Another example is activating an alert that lists some items to pick up the next time you are at the grocery store.

The good news is now we can generate these alerts using our Android-based smart phones.  This is specifically known as proximity alerts, and is the topic of this post.  We will discuss how the LocationManager class helps us in this endeavor.  We will also create a ProximityIntent based on the PendingIntent.  And we will create a ProximityIntentReceiver by extending the BroadcastReceiver in order to receive the proximity intents.

In this post, we will develop a Proximity Alert Mobile Application using the Android Platform.  The final application will look like the following:

Proximity Alert Mobile Application (Home Screen)

And we will use the following screen to add proximity alerts:

Proximity Alert Set Activity Screen

Let’s Get Started

Mission Statement

To build a Proximity Alert Mobile Application allowing users to set and receive alerts based on location proximity, similar to setting and receiving traditional time-based event reminders.

Use Cases

• To set one or more location proximity alert(s), configurable by location, radius of proximity (in meters), and expiration date/time
• To insert/edit freestyle attributes to the location proximity alerts, e.g., todo list, grocery list, etc…
• To be notified (that is, alerted) when the user enters the location within configured proximity parameters
• To delete one, or all, proximity alert(s)

Considerations

• In order to “set” a location proximity alert, it is necessary to actually take the smart phone to the location being targeted and “set” the alert
• We will need to create both proximity configuration and proximity alert screens
• We will register the application as a “service” in order to run it in the background
• User Interface style is a low priority!  Also known as lazy author!

Design

Before we start cutting code, we need to think through our design.  As a minimum, we need the following:

1. Home View – all actions start from this screen, and display our active list of proximity alerts
2. Proximity Alert View – this will allow us to add/edit/delete proximity alerts
3. Proximity Alert Entity – represents a single alert, and functions like a DTO
4. Proximity Alert Repository – this will provide persistent storage of our alerts
5. Proximity Alert Notification View – notifies of a proximity alert, i.e., displays an alert screen when an actual alert is fired
6. Proximity Intent Receiver – this is our Broadcast Receiver (more on this later)
7. Settings “Preferences” View – we will use Android’s PreferenceActivity to edit common configuration settings, e.g., proximity radius

Ask anyone who has been around the block creating Android applications, and they will tell you to make sure your AndroidManifest.xml file is set up properly.  All Activities referenced by your application, additional libraries used by your application, and all necessary permissions must be set up in this in order for your application to work properly.

With that said, our manifest file is as follows:

<?xml version="1.0" encoding="utf-8"?>
  <manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="iqspike.proximityalert.activity"
    android:versionCode="1" android:versionName="1.0">
    <application android:icon="@drawable/icon" android:label="@string/app_name">
      <uses-library android:name="com.google.android.maps"/>
      <activity android:name=".ProximityAlertHomeActivity" android:label="@string/app_name">
        <intent-filter>
          <action android:name="android.intent.action.MAIN" />
          <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
      </activity>
      <activity android:name="ProximityAlertActivity">
      </activity>
      <activity android:name="ProximityAlertSetActivity">
      </activity>
      <activity android:name="ProximityAlertPreferencesActivity">
      </activity>
    </application>
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    <uses-permission android:name="android.permission.VIBRATE"/>
  </manifest>

Note the highlighted lines near the bottom indicating the INTERNET, ACCESS_FINE_LOCATION, and VIBRATE permissions we require.  Note that ACCESS_FINE_LOCATION is a bit more battery intensive than ACCESS_COARSE_LOCATION, but is necessary when you need a finer level of GPS information.

We’re just getting started.  Please see Part 2 as we start cutting code for our Mobile Proximity Alert Application using the Android Platform!

More coming soon!