Apple’s announcement of offering applications the ability to receive location updates while running in the background has given SimpleGeo another reason to shine. There are many attractive use-cases that this new feature opens up. We’re happy to announce that iPhone developers can seamlessly update their endusers’ record whenever the device is sent into the background. Combine this with our ability to provide a record’s history and we have a way to track a record’s location across its entire lifetime.

Along with background location updates, we also wanted to provide a wrapper class around the location manager that incorporates our pushpin service. One of the features of our pushpin service is the ability to query for a set of regions the encompasses a latitude and longitude. For example, you could tell us your user was at 37.75899333917751, -122.42711305618286 and we’d tell you they were in the Mission District, which is in 94107, which is in San Francisco, which is in California, etc. We wrote a nice wrapper around the location manager delegates in iOS 4 which will call your delegate when a user enters or exits a region. Yes, this means you can now do background geofencing on any iOS 4 device for geographic, political, and cultural boundaries. Of course, this works just fine in iOS 3+ devices as well, but only works if the application is open and running.

Adding Background Location to your Application

First you need to setup your XCode environment to be working with the iOS 4.0 SDK. Next, clone the current HEAD of the master branch from the SGClient Github repository. There are instructions in the README file that tell you how to add the compiled static library to your project. If you don’t feel like working with the static library, you can also just import the source files into your own project.

There are a total of six steps, two of which are optional, that must be met in order to get background location up-and-running within your application. These requirements can all be implemented wherever your application defines its UIApplicationDelegate.

Step 1

Initialize the SGLocationService shared instance with your OAuth token/secret that can be viewed on your dashboard.

Step 2

Notify the shared location service that the application entered the background.

Step 3

Notify the shared location service that the application left the background.

Step 4

Create a couple of end-user records that you want to be updated while the application is running in the background.

Once you’ve registered the records that you wish to have tracked in the background, you are done! Requests will be sent out for each of the tracked records every time the location is updated. We wanted to be nice to peoples’ data plans and their batteries so we added an extra cherry on top! The SGLocationService provides a cacheing mechanism that commits all generated requests to a file so they can be sent over the wire when the application enters the foreground.

The following steps are optional and are only required if you wish to support said caching.

Step 5 (Optional)

Notify the shared location service that the application has entered the foreground.

Step 6 (Optional)

The SGLocationServiceDelegate must implement the option method locationService:shouldCacheRecord: method and return a YES boolean value.

Retrieving a Record’s History

SimpleGeo offers the ability to query the history of a enduser record. The client creates its request asynchronously which decreases time spent on the main thread. This allows the SimpleGeo client to respect the delegate notification model while allowing UI events to propagate through unharmed. There are two different ways to query for a record’s history depending on what type of objects you are using.

id<SGRecordAnnotation>

If you are a person who enjoys working with low-level objects, the SGLocationService comes equipped with a single method named history:. It takes in a single SGHistoryQuery object as its only parameter which provides the proper values that initialize the future history request.

SGRecord

The SGRecord class is created not only as a demo implementation of a class that conforms to the SGRecordAnnotation protocol, but also to add some extra features to its subclasses. One of these features is the ability to generate a history request from the object itself.

SGLocationManager

SimpleGeo’s pushpin service provides a way to retrieve a list of polygons for a given latitude and longitude. These polygons define regions that encompass the latitude and longitude. Regions can be anything from a neighborhood or city to a state or zip code. Wrapping the `CLLocationManager` around this functionality provides a way for the client to receive callback notifications about regions that the phone has just left or entered. This is commonly referred to as [geofencing](http://en.wikipedia.org/wiki/Geofence).

SGLocationManager is a simple wrapper around CLLocationManager. Meaning, wherever you have CLLocationManager being allocated and initialized you can simply swap it out for the SGLocationManager. If you wish to receive callback notifications concerning region updates, there are just two extra methods that need to be implemented by the CLLocationManagerDelegate.

The following is an example implementation of these two methods that simply presents a message for the new region set.

So that’s it! You can now track where all of your users are and when and you can now have your application be notified when they leave a given city, state, zip code, neighborhood, etc. Please use your newfound powers with care.

Tweet