(For more resources on iOS, see here.)

The iOS family makes use of many onboard sensors including the three-axis accelerometer, digital compass, camera, microphone, and global positioning system (GPS). Their inclusion has created a world of opportunity for developers, and has resulted in a slew of innovative, creative, and fun apps that have contributed to the overwhelming success of the App Store.

Determining your current location

The iOS family of devices are location-aware, allowing your approximate geographic position to be determined. How this is achieved depends on the hardware present in the device. For example, the original iPhone, all models of the iPod touch, and Wi-Fi-only iPads use Wi-Fi network triangulation to provide location information. The remaining devices can more accurately calculate their position using an on-board GPS chip or cell-phone tower triangulation.

The AIR SDK provides a layer of abstraction that allows you to extract location information in a hardware-independent manner, meaning you can access the information on any iOS device using the same code.

This recipe will take you through the steps required to determine your current location.

Getting ready

An FLA has been provided as a starting point for this recipe.

From Flash Professional, open chapter9recipe1recipe.fla from the code bundle which can be downloaded from http://www.packtpub.com/support.

How to do it...

Perform the following steps to listen for and display geolocation data:

1. Create a document class and name it Main.
2. Import the following classes and add a member variable of type Geolocation:

   package {
   import flash.display.MovieClip;
   import flash.events.GeolocationEvent;
   import flash.sensors.Geolocation;
   public class Main extends MovieClip {
   private var geo:Geolocation;
   public function Main() {
   // constructor code
   }
   }
   }

• Within the class' constructor, instantiate a Geolocation object and listen for updates from it:

  public function Main() {
  if(Geolocation.isSupported)
  {
  geo = new Geolocation();
  geo.setRequestedUpdateInterval(1000);
  geo.addEventListener(GeolocationEvent.UPDATE, geoUpdated);
  }
  }

• Now, write an event handler that will obtain the updated geolocation data and populate the dynamic text fields with it:

  private function geoUpdated(e:GeolocationEvent):void {
  latitudeField.text = e.latitude.toString();
  longitudeField.text = e.longitude.toString();
  altitudeField.text = e.altitude.toString();
  hAccuracyField.text = e.horizontalAccuracy.toString();
  vAccuracyField.text = e.verticalAccuracy.toString();
  timestampField.text = e.timestamp.toString();
  }

• Save the class file as Main.as within the same folder as the FLA. Move back to the FLA and save it too.
• Publish and test the app on your device.
• When launched for the first time, a native iOS dialog will appear.
• Tap the OK button to grant your app access to the device's location data.

Devices running iOS 4 and above will remember your choice, while devices running older versions of iOS will prompt you each time the app is launched.

The location data will be shown on screen and periodically updated. Take your device on the move and you will see changes in the data as your geographical location changes.

How it works...

AIR provides the Geolocation class in the flash.sensors package, allowing the location data to be retrieved from your device. To access the data, create a Geolocation instance and listen for it dispatching GeolocationEvent.UPDATE events.

We did this within our document class' constructor, using the geo member variable to hold a reference to the object:

geo = new Geolocation();
geo.setRequestedUpdateInterval(1000);
geo.addEventListener(GeolocationEvent.UPDATE, geoUpdated);

The frequency with which location data is retrieved can be set by calling the Geolocation. setRequestedUpdateInterval() method. You can see this in the earlier code where we requested an update interval of 1000 milliseconds. This only acts as a hint to the device, meaning the actual time between updates may be greater or smaller than your request. Omitting this call will result in the device using a default update interval. The default interval can be anything ranging from milliseconds to seconds depending on the device's hardware capabilities.

Each UPDATE event dispatches a GeolocationEvent object, which contains properties describing your current location. Our geoUpdated() method handles this event by outputting several of the properties to the dynamic text fields sitting on the stage:

private function geoUpdated(e:GeolocationEvent):void {
latitudeField.text = e.latitude.toString();
longitudeField.text = e.longitude.toString();
altitudeField.text = e.altitude.toString();
hAccuracyField.text = e.horizontalAccuracy.toString();
vAccuracyField.text = e.verticalAccuracy.toString();
timestampField.text = e.timestamp.toString();
}

The following information was output:

• Latitude and longitude
• Altitude
• Horizontal and vertical accuracy
• Timestamp

The latitude and longitude positions are used to identify your geographical location. Your altitude is also obtained and is measured in meters. As you move with the device, these values will update to reflect your new location.

The accuracy of the location data is also shown and depends on the hardware capabilities of the device. Both the horizontal and vertical accuracy are measured in meters.

Finally, a timestamp is associated with every GeolocationEvent object that is dispatched, allowing you to determine the actual time interval between each. The timestamp specifies the milliseconds that have passed since the app was launched.

Some older devices that do not include a GPS unit only dispatch UPDATE events occasionally. Initially, one or two UPDATE events are dispatched, with additional events only being dispatched when location information changes noticeably.

Also note the use of the static Geolocation.isSupported property within the constructor. Although this will currently return true for all iOS devices, it cannot be guaranteed for future devices. Checking for geolocation support is also advisable when writing cross-platform code.

For more information, perform a search for flash.sensors.Geolocation and flash. events.GeolocationEvent within Adobe Community Help.

There's more...

The amount of information made available and the accuracy of that information depends on the capabilities of the device.

Accuracy

The accuracy of the location data depends on the method employed by the device to calculate your position. Typically, iOS devices with an on-board GPS chip will have a benefit over those that rely on Wi-Fi triangulation.

For example, running this recipe's app on an iPhone 4, which contains a GPS unit, results in a horizontal accuracy of around 10 meters. The same app running on a third-generation iPod touch and relying on a Wi-Fi network, reports a horizontal accuracy of around 100 meters. Quite a difference!

Altitude support

The current altitude can only be obtained from GPS-enabled devices. On devices without a GPS unit, the GeolocationEvent.verticalAccuracy property will return -1 and GeolocationEvent.altitude will return 0. A vertical accuracy of -1 indicates that altitude cannot be detected.

You should be aware of, and code for these restrictions when developing apps that provide location-based services. Do not make assumptions about a device's capabilities.

If your application relies on the presence of GPS hardware, then it is possible to state this within your application descriptor file. Doing so will prevent users without the necessary hardware from downloading your app from the App Store.

Mapping your location

The most obvious use for the retrieval of geolocation data is mapping. Typically, an app will obtain a geographic location and display a map of its surrounding area. There are several ways to achieve this, but launching and passing location data to the device's native maps application is possibly the easiest solution.

If you would prefer an ActionScript solution, then there is the UMap ActionScript 3.0 API, which integrates with map data from a wide range of providers including Bing, Google, and Yahoo!. You can sign up and download the API from www.umapper.com.

Calculating distance between geolocations

When the geographic coordinates of two separate locations are known, it is possible to determine the distance between them. AIR does not provide an API for this but an AS3 solution can be found on the Adobe Developer Connection website at: http://cookbooks.adobe.com/index.cfm?event=showdetails&postId=5701.

The UMap ActionScript 3.0 API can also be used to calculate distances. Refer to www.umapper.com.

Geocoding

Mapping providers, such as Google and Yahoo!, provide geocoding and reverse-geocoding web services. Geocoding is the process of finding the latitude and longitude of an address, whereas reverse-geocoding converts a latitude-longitude pair into a readable address.

You can make HTTP requests from your AIR for iOS application to any of these services. As an example, take a look at the Yahoo! PlaceFinder web service at http://developer.yahoo.com/geo/placefinder.

Alternatively, the UMap ActionScript 3.0 API integrates with many of these services to provide geocoding functionality directly within your Flash projects. Refer to the uMapper website.

Gyroscope support

Another popular sensor is the gyroscope, which is found in more recent iOS devices. While the AIR SDK does not directly support gyroscope access, Adobe has made available a native extension for AIR 3.0, which provides a Gyroscope ActionScript class.

A download link and usage examples can be found on the Adobe Developer Connection site at www.adobe.com/devnet/air/native-extensions-for-air/extensions/gyroscope.html.

Determining your speed and heading

The availability of an on-board GPS unit makes it possible to determine your speed and heading. In this recipe, we will write a simple app that uses the Geolocation class to obtain and use this information. In addition, we will add compass functionality by utilizing the user's current heading.

Getting ready

You will need a GPS-enabled iOS device. The iPhone has featured an on-board GPS unit since the release of the 3G. GPS hardware can also be found in all cellular network-enabled iPads.

From Flash Professional, open chapter9recipe2recipe.fla from the code bundle.

Sitting on the stage are three dynamic text fields. The first two (speed1Field and speed2Field) will be used to display the current speed in meters per second and miles per hour respectively. We will write the device's current heading into the third—headingField.

Also, a movie clip named compass has been positioned near the bottom of the stage and represents a compass with north, south, east, and west clearly marked on it. We will update the rotation of this clip in response to heading changes to ensure that it always points towards true north.

How to do it...

To obtain the device's speed and heading, carry out the following steps:

1. Create a document class and name it Main.
2. Add the necessary import statements, a constant, and a member variable of type Geolocation:

   package {
   import flash.display.MovieClip;
   import flash.events.GeolocationEvent;
   import flash.sensors.Geolocation;
   public class Main extends MovieClip {
   private const CONVERSION_FACTOR:Number = 2.237;
   private var geo:Geolocation;
   public function Main() {
   // constructor code
   }
   }
   }

3. Within the constructor, instantiate a Geolocation object and listen for updates:

   public function Main() {
   if(Geolocation.isSupported)
   {
   geo = new Geolocation();
   geo.setRequestedUpdateInterval(50);
   geo.addEventListener(GeolocationEvent.UPDATE, geoUpdated);
   }
   }

4. We will need an event listener for the Geolocation object's UPDATE event. This is where we will obtain and display the current speed and heading, and also update the compass movie clip to ensure it points towards true north. Add the following method:

   private function geoUpdated(e:GeolocationEvent):void {
   var metersPerSecond:Number = e.speed;
   var milesPerHour:uint = getMilesPerHour(metersPerSecond);
   speed1Field.text = String(metersPerSecond);
   speed2Field.text = String(milesPerHour);
   var heading:Number = e.heading;
   compass.rotation = 360 - heading;
   headingField.text = String(heading);
   }

5. Finally, add this support method to convert meters per second to miles per hour:

   private function getMilesPerHour(metersPerSecond:Number):uint
   {
   return metersPerSecond * CONVERSION_FACTOR;
   }

6. Save the class file as Main.as. Move back to the FLA and save it too.
7. Compile the FLA and deploy the IPA to your device.
8. Launch the app. When prompted, grant your app access to the GPS unit.

Hold the device in front of you and start turning on the spot. The heading (degrees) field will update to show the direction you are facing. The compass movie clip will also update, showing you where true north is in relation to your current heading.

Take your device outside and start walking, or better still, start running. On average every 50 milliseconds you will see the top two text fields update and show your current speed, measured in both meters per second and miles per hour.

How it works...

In this recipe, we created a Geolocation object and listened for it dispatching UPDATE events. An update interval of 50 milliseconds was specified in an attempt to receive the speed and heading information frequently.

Both the speed and heading information are obtained from the GeolocationEvent object, which is dispatched on each UPDATE event. The event is captured and handled by our geoUpdated() handler, which displays the speed and heading information from the accelerometer.

The current speed is measured in meters per second and is obtained by querying the GeolocationEvent.speed property. Our handler also converts the speed to miles per hour before displaying each value within the appropriate text field. The following code does this:

var metersPerSecond:Number = e.speed;
var milesPerHour:uint = getMilesPerHour(metersPerSecond);
speed1Field.text = String(metersPerSecond);
speed2Field.text = String(milesPerHour);

The heading, which represents the direction of movement (with respect to true north) in degrees, is retrieved from the GeolocationEvent.heading property. The value is used to set the rotation property of the compass movie clip and is also written to the headingField text field:

var heading:Number = e.heading;
compass.rotation = 360 - heading;
headingField.text = String(heading);

The remaining method is getMilesPerHour() and is used within geoUpdated() to convert the current speed from meters per second into miles per hour. Notice the use of the CONVERSION_FACTOR constant that was declared within your document class:

private function getMilesPerHour(metersPerSecond:Number):uint
{
return metersPerSecond * CONVERSION_FACTOR;
}

Although the speed and heading obtained from the GPS unit will suffice for most applications, the accuracy can vary across devices. Your surroundings can also have an affect; moving through streets with tall buildings or under tree coverage can impair the readings.

You can find more information regarding flash.sensors.Geolocation and flash.events.GeolocationEvent within Adobe Community Help.

There's more...

The following information provides some additional detail.

Determining support

Your current speed and heading can only be determined by devices that possess a GPS receiver.

Although you can install this recipe's app on any iOS device, you won't receive valid readings from any model of iPod touch, the original iPhone, or W-Fi-only iPads. Instead the GeolocationEvent.speed property will return -1 and GeolocationEvent.heading will return NaN.

If your application relies on the presence of GPS hardware, then it is possible to state this within the application descriptor file. Doing so will prevent users without the necessary hardware from downloading your app from the App Store.

Simulating the GPS receiver

During the development lifecycle it is not feasible to continually test your app in a live environment. Instead you will probably want to record live data from your device and re-use it during testing. There are various apps available that will log data from the sensors on your device.

One such app is xSensor, which can be downloaded from iTunes or the App Store and is free. Its data sensor log is limited to 5KB but this restriction can be lifted by purchasing xSensor Pro.

Preventing screen idle

Many of this article's apps don't require you to touch the screen that often. Therefore you will be likely to experience the backlight dimming or the screen locking while testing them. This can be inconvenient and can be prevented by disabling screen locking.