phonegap deep-dive
TRANSCRIPT
PhoneGap API Deep Dive
Andrew Lunny, Nitobi, July 8 2010
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
However
• Some functionality is not present on all hardwareo Accelerometer, Compass
• Some features aren't exposed by all platformso SMS, Telephony, File System
• Some features are exposed in varying wayso Camera, Contacts
• Some features are platform specifico notification.activityStart, KeyEvent
PhoneGap 1.0
• Consistent Core API• Plugins for majority of platform specific code• Platform specific functionality for exceptional purposes
Documentation Push• Reworking phonegap-docso http://docs2.phonegap.como http://github.com/phonegap/phonegap-docs/tree/
rework• Better expose and fix inconsistencies
When in doubt, check mobile-spec
API Outline
Basic
DeviceNe twork
Notifica tion Debug Console
Sensors
Acce lerome terCompass
G eoloca tionOrienta tion
User Da ta / F ile Storage
C ameraContac ts
F ileMed ia (Aud io)Storage/Store
SMS/Te lephony
Basics
o Fundamentals for mobile apps and developmento Well-supported on all platformso Consistent core, with platform specific extensions
Device, Network, Notification, Debug
DeviceiPhone, Android, BlackBerry, Palm, Symbian.wrt
A JS Object with String/Boolean fields
navigator.device.uuidnavigator.device.platform
Everywhere:
except Palm: navigator.device.namenavigator.device.version
except Palm and Symbian:
navigator.device.gap || navigator.device.gapVersion
device.gap = iPhone and BlackBerrydevice.gapVersion = Android
NetworkiPhone, Android, BlackBerry, Palm, Symbian.wrt
One common public function: isReachable
BlackBerry also has Network.XHRsince the BlackBerry webview doesn't give us an XMLHttpRequest by default
Android 2.2: ononline and onoffline events
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
iPhonefoo.remoteHostStatus != NetworkStatus.NOT_REACHABLE
Android/BlackBerryfoo.code != NetworkStatus.NOT_REACHABLE
NotificationiPhone, Android, BlackBerry, Palm, Symbian.wrt
Common navigator.notification.alert
navigator.notification.beep
navigator.notification.vibrateNot on Palm
Not on Symbian
navigator.notification.blinkBlackBerry only
confirmactivityStart, activityStoploadingStart, loadingStop
iPhone only
DebugConsoleiPhone, 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
Sensors
o All related to physical state of deviceo Time sensitive and liable to changeo Consistent between platforms and consistent
between environment moduleso 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
Accelerometer, Compass, Geolocation, Orientation
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
AccelerometeriPhone, Android, BlackBerry, Palm, Symbian.wrt
navigator.accelerometer.getCurrentAccelerationnavigator.accelerometer.watchAccelerationnavigator.accelerometer.clearWatch
Not supported on BlackBerry because the hardware has limited support (depending on the handset)
CompassiPhone, Android, BlackBerry, Palm, Symbian.wrt
navigator.compass.getCurrentHeadingnavigator.compass.watchHeadingnavigator.compass.clearWatch
Palm and Symbian: no hardware support
BlackBerry: depends on the device, not implemented yet
GeolocationiPhone, Android, BlackBerry, Palm, Symbian.wrt
navigator.geolocation.getCurrentPositionnavigator.geolocation.watchPositionnavigator.geolocation.clearWatch
Where available (iPhone, Android 2.0+), PhoneGap uses the browser's geolocation API, rather than implementing our own
OrientationiPhone, Android, BlackBerry, Palm, Symbian.wrt
navigator.orientation.getCurrentOrientationnavigator.orientation.watchOrientationnavigator.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
User Data / File Storage
o Reading and writing what's normally inaccessibleo Most prone to inconsistency•between platforms•between device models/OS versions
o Least settled PhoneGap APIs
Camera, Contacts, File, Media (Audio), Storage/Store, SMS/Telephony
CameraiPhone, Android, BlackBerry, Palm, Symbian.wrt
navigator.camera.getPicture(success, error, options);
Android, iPhone
BlackBerry, Palm
Symbian.wrt
success is passed a base-64 string of image data
success is passed a file path to the image
success is passed an array of file paths
ContactsiPhone, Android, BlackBerry, Palm, Symbian.wrt
Android, Blackberry, Symbian
iPhone
navigator.contacts.find(filter, success, error, options);
filter is an object of type Contact
getAllContactsnewContactchooseContactdisplayContactremoveContactcontactsCount
Contacts
o The most inconsistent between platformso Test on devices, not just simulators!
FileiPhone, Android, BlackBerry, Palm, Symbian.wrt
navigator.fileMgrFileReader objectFileWriter object
Palm webOS does not allow File I/O File.read is implemented with an XHRBlackBerry should be implemented...• use Store (see later slide) instead
Android & iPhone: based loosely on W3C file spec:http://bit.ly/w3cfileexample API usage: http://bit.ly/pg-file
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
Storage/StoreiPhone, 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.getItemnavigator.storage.setItem
BlackBerry: key/value store: navigator.store.getnavigator.store.put
SMS/TelephonyiPhone, 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
