phonegap deep-dive

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

@alunny, andrew.lunny@nitobi.com

Questions or Feedback