PhoneGap provides a consistent set of cross-platform APIs for accessing native device capabilities through JavaScript. While some functionality is not fully exposed across all platforms, PhoneGap aims to provide a core set of APIs for basics like device, network, and notifications. Sensors like accelerometer and compass generally have consistent APIs, while user data access like contacts and storage are most prone to inconsistency between platforms. The PhoneGap documentation is being reworked to better expose inconsistencies and exceptions across platforms.

1. PhoneGap API Deep Dive
Andrew Lunny, Nitobi, July 8 2010

2. PhoneGap Goal
A set of consistent cross-platform APIs for
accessing native device capabilities through
JavaScript
This is possible for a large subset of PhoneGap
APIs

3. However
• Some functionality is not present on all hardware
o Accelerometer, Compass
• Some features aren't exposed by all platforms
o SMS, Telephony, File System
• Some features are exposed in varying ways
o Camera, Contacts
• Some features are platform specific
o notification.activityStart, KeyEvent

4. PhoneGap 1.0
• Consistent Core API
• Plugins for majority of platform specific code
• Platform specific functionality for exceptional purposes
Documentation Push
• Reworking phonegap-docs
o http://docs2.phonegap.com
o http://github.com/phonegap/phonegap-docs/tree/
rework
• Better expose and fix inconsistencies
When in doubt, check mobile-spec

5. API Outline
D evic e
N etwork
B asic
Notific ation
D e bug C onsole
A c c elerometer
C omp ass
Sensors
G eoloc ation
Orientation
C amera
C onta cts
File
User D ata / File Stora g e
Me dia (Audio)
Stora g e/Store
SMS/Tele phony

6. Basics
Device, Network, Notification, Debug
o Fundamentals for mobile apps and development
o Well-supported on all platforms
o Consistent core, with platform specific extensions

7. Device
iPhone, Android, BlackBerry, Palm, Symbian.wrt
A JS Object with String/Boolean fields
Everywhere: navigator.device.uuid
navigator.device.platform
except Palm: navigator.device.name
navigator.device.version
except Palm navigator.device.gap ||
and Symbian: navigator.device.gapVersion
device.gap = iPhone and BlackBerry
device.gapVersion = Android

8. Network
iPhone, Android, BlackBerry, Palm, Symbian.wrt
One common public function: isReachable
BlackBerry also has Network.XHR
since the BlackBerry webview doesn't give us an
XMLHttpRequest by default
Android 2.2: ononline and onoffline events

9. navigator.network.isReachable(hostname,
callback, options);
The callback function is called with the parameter foo,
which is used to compare the NetworkStatus against
the NetworkStatus constants (for example,
NetworkStatus.NOT_REACHABLE)
Palm/Symbian (what we want going forward)
foo != NetworkStatus.NOT_REACHABLE
iPhone
foo.remoteHostStatus !=
NetworkStatus.NOT_REACHABLE
Android/BlackBerry
foo.code != NetworkStatus.NOT_REACHABLE

10. Notification
iPhone, Android, BlackBerry, Palm, Symbian.wrt
Common navigator.notification.alert
Not on Symbian navigator.notification.beep
Not on Palm navigator.notification.vibrate
BlackBerry only navigator.notification.blink
iPhone only confirm
activityStart, activityStop
loadingStart, loadingStop

11. DebugConsole
iPhone, Android, BlackBerry, Palm, Symbian.wrt
debug.log(msg)
debug.warn(msg)
debug.error(msg)
Android currently uses console.log
Both Android and BlackBerry should and will
implement these

12. Sensors
Accelerometer, Compass,
Geolocation, Orientation
o All related to physical state of device
o Time sensitive and liable to change
o Consistent between platforms and consistent
between environment modules
o Moving into the browser
• Google I/O Keynote promises all of these in
Browser soon:
• http://bit.ly/android-io
• cf. http://dev.w3.org/geo/api/spec-source-
orientation.html

13. Sensor APIs
navigator.sensor.getCurrentVariable(success,
error, options);
• asynchronously calls success with the current reading/status
navigator.sensor.watchVariable(success, error,
options);
• calls getCurrentVariable repeatedly, at frequency
specified in options parameter; returns a watch id
navigator.sensor.clearWatch(watchId);
• cancels the watch set by watchVariable

14. Accelerometer
iPhone, Android, BlackBerry, Palm, Symbian.wrt
navigator.accelerometer.getCurrentAcceleration
navigator.accelerometer.watchAcceleration
navigator.accelerometer.clearWatch
Not supported on BlackBerry because the hardware
has limited support (depending on the handset)

15. Compass
iPhone, Android, BlackBerry, Palm, Symbian.wrt
navigator.compass.getCurrentHeading
navigator.compass.watchHeading
navigator.compass.clearWatch
Palm and Symbian: no hardware support
BlackBerry: depends on the device, not implemented
yet

16. Geolocation
iPhone, Android, BlackBerry, Palm, Symbian.wrt
navigator.geolocation.getCurrentPosition
navigator.geolocation.watchPosition
navigator.geolocation.clearWatch
Where available (iPhone, Android 2.0+), PhoneGap
uses the browser's geolocation API, rather than
implementing our own

17. Orientation
iPhone, Android, BlackBerry, Palm, Symbian.wrt
navigator.orientation.getCurrentOrientation
navigator.orientation.watchOrientation
navigator.orientation.clearWatch
Unlikely for BlackBerry (only makes sense on
certain handsets)
Android: probably wait for Browser implementation
iPhone fires orientationChange event
automagically; you can use window.orientation
instead of the PhoneGap method
CSS3 media queries can also be used

18. User Data / File Storage
Camera, Contacts, File, Media (Audio),
Storage/Store, SMS/Telephony
o Reading and writing what's normally inaccessible
o Most prone to inconsistency
• between platforms
• between device models/OS versions
o Least settled PhoneGap APIs

19. Camera
iPhone, Android, BlackBerry, Palm, Symbian.wrt
navigator.camera.getPicture(success, error,
options);
Android, iPhone success is passed a base-64 string
of image data
BlackBerry, Palm success is passed a file path to the
image
Symbian.wrt success is passed an array of file
paths

20. Contacts
iPhone, Android, BlackBerry, Palm, Symbian.wrt
Android, Blackberry, navigator.contacts.find
Symbian (filter, success, error,
options);
filter is an object of type
Contact
iPhone getAllContacts
newContact
chooseContact
displayContact
removeContact
contactsCount

21. Contacts
o The most inconsistent between platforms
o Test on devices, not just simulators!

22. File
iPhone, Android, BlackBerry, Palm, Symbian.wrt
navigator.fileMgr
FileReader object
FileWriter object
Palm webOS does not allow File I/O
File.read is implemented with an XHR
BlackBerry should be implemented...
• use Store (see later slide) instead
Android & iPhone: based loosely on W3C file spec:
http://bit.ly/w3cfile
example API usage: http://bit.ly/pg-file

23. Media (Audio)
iPhone, Android, BlackBerry, Palm, Symbian.wrt
var mySong = new Media
("urthebest.mp3",success,error);
mySong.play();
mySong.pause();
mySong.stop();
Blackberry, Palm and Symbian as Audio, not
Media
iPhone and Android can record audio also
• iPhone: startAudioRecord,
stopAudioRecord
• Android: startRecord,
stopRecordingAudio

24. Storage/Store
iPhone, Android, BlackBerry, Palm, Symbian.wrt
iPhone/Android 2.0+/Palm: unneeded - use
localStorage or HTML5 db
Android < 2.0: sets up an SQLite database,
accessed through window.openDatabase
• Unstable: use with caution
Symbian: key/value store:
navigator.storage.getItem
navigator.storage.setItem
BlackBerry: key/value store:
navigator.store.get
navigator.store.put

25. SMS/Telephony
iPhone, Android, BlackBerry, Palm, Symbian.wrt
navigator.sms.send(number, message, success,
error, options);
navigator.telephony.send(number);
To be implemented on iPhone/Android
Any platform: set link HREF to sms: or tel:
In all cases, the user must confirm before the call or
message is placed

26. Questions or Feedback
@alunny, andrew.lunny@nitobi.com