16. Device
The PhoneGap Device object allows an application to access a limited amount of information about the application and device running a PhoneGap application. The device object represents the following properties:
• device.name: Returns the name assigned to the device; this could be something assigned by the device manufacturer or assigned by the smartphone user depending on the mobile device platform.
• device.phonegap: Returns the version of the PhoneGap framework used to build the application.
• device.platform: On most platforms, returns the name of the mobile device platform the application is running on. Exceptions will be discussed later in the chapter.
• device.uuid: Returns the universally unique identifier (UUID) associated with the device (http://en.wikipedia.org/wiki/Universally_Unique_Identifier).
• device.version: Returns the OS version running on the device.
The device object has scope at the window level, so you can access any of the device properties using the following:
var deviceName = window.device.name;
or this:
var deviceName = device.name;
An example application using device properties was shown in Chapter 2. Example 16-1 highlights each of the supported device properties.
<!DOCTYPE html>
<html>
<head>
<title>Example 16-1</title>
<meta http-equiv="Content-type" content="text/html;
charset=utf-8">
<meta name="viewport" id="viewport"
content="width=device-width, height=device-height,
initial-scale=1.0, maximum-scale=1.0, user-scalable=no;"
/>
<script type="text/javascript" charset="utf-8"
src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
function onBodyLoad() {
document.addEventListener("deviceready", onDeviceReady,
false);
}
function onDeviceReady() {
//HTML Break string
var br = "<br />";
//Get the appInfo DOM element
var element = document.getElementById("deviceInfo");
//replace it with specific information about the
//device running the application
element.innerHTML =
"<b>device.name: " + device.name + br +
"<b>device.phonegap:</b> " + device.phonegap + br +
"<b>device.platform:</b> " + device.platform + br +
"<b>device.uuid:</b> " + device.uuid + br +
"<b>device.version:</b> " + device.version + br;
}
</script>
</head>
<body onload="onBodyLoad()">
<h1>Example 16-1</h1>
<p id="deviceInfo">Waiting for PhoneGap Initialization to
complete</p>
</body>
</html>
In this example, once PhoneGap has initialized, the onDeviceReady function is executed, and the application replaces the deviceInfo content on the page with values from each of the properties of the device object.
Let’s take a look at the output of this application on different devices.
Figure 16-1 shows Example 16-1 running on a LG Thrill smartphone. As you can see from the example, the device.name property reports the name the manufacturer has assigned to the device. I built this application using PhoneGap Build, so they’re using the latest (at the time) version of PhoneGap, version 1.1.0. The device is running Android version 2.2.2.
Figure 16-1 Example 16-1 running on an Android device
Figure 16-2 shows the same application running on the BlackBerry simulator. As you can see, PhoneGap on BlackBerry has an issue displaying the platform name, reporting 3.0.0.100 instead of the word BlackBerry.
Figure 16-2 Example 16-1 running on a BlackBerry simulator
When you take a look at the source code in the phonegap.js file for the BlackBerry platform, you see the following:
function Device() {
this.platform = phonegap.device.platform;
this.version = blackberry.system.softwareVersion;
this.name = blackberry.system.model;
this.uuid = phonegap.device.uuid;
this.phonegap = phonegap.device.phonegap;
};
PhoneGap is simply calling JavaScript methods provided by the BlackBerry WebWorks platform, and for some bizarre reason, the developer has chosen to implement the device.name property using a system call that returns the version number of the BlackBerry platform running on the device rather than the word BlackBerry. In reality, the code should really look like this:
this.name = "BlackBerry";
RIM provides a Java API that allows an application to know whether the application is running on a physical device or a simulator, which is useful information to have when testing an application. Unfortunately, the developer of PhoneGap for BlackBerry has not chosen to expose that distinction, which as you’ll see next has been implemented on iOS.
Figure 16-3 shows Example 16-1 running on an iPhone device. For this OS, the device.name property returns the name the user has assigned to the device in iTunes.
Figure 16-3 Example 16-1 running on an iPhone device
Figure 16-4 shows Example 16-1 running on the iPad simulator, but the PhoneGap application is configured in Xcode as an iPhone application. This particular configuration puts the application in compatibility mode, running as an iPhone application in a little iPhone window on the iPad. Users can click the 2X button in the bottom-right corner of the screen to expand the window so the application runs full-screen.
Figure 16-4 Example 16-1 running on the iPad simulator as an iPhone application
The application reports that it’s running on an iPhone, but in reality device.platform should return iOS since that’s the OS platform the application is running on. Expect that this will change someday, and any code you have that looks for iPhone will have to be updated to check for iOS as well.
Notice too that on iOS PhoneGap reports correctly when the application is running on a simulator. This particular feature makes it easier to perform testing in situations where a particular feature (like the camera) is available only on a physical device; your code can test to see whether the application is running on a simulator and run substitute code in those cases.
Figure 16-5 shows Example 16-1 running on the iPad simulator. Happily, the application is now running in full-screen mode and reports correctly that it’s running on an iPad rather than an iPhone, as shown in Figure 16-4.
Figure 16-5 Example 16-1 running on the iPad simulator