Phonegap API 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 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
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

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
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
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
Network
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

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
Notification
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
DebugConsole
debug.log(msg)
debug.warn(msg)
debug.error(msg)
Android currently uses console.log
Both Android and BlackBerry should and will

implement these
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
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
Accelerometer
navigator.accelerometer.getCurrentAcceleration
navigator.accelerometer.watchAcceleration
navigator.accelerometer.clearWatch
Not supported on BlackBerry because the hardware

has limited support (depending on the handset)
Compass
navigator.compass.getCurrentHeading
navigator.compass.watchHeading
navigator.compass.clearWatch
Palm and Symbian: no hardware support
BlackBerry: depends on the device, not implemented

yet
Geolocation
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
Orientation
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

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
Camera
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
Contacts
Android, Blackberry, navigator.contacts.find

Symbian (filter, success, error,
options);
filter is an object of type

Contact
iPhone getAllContacts
newContact
chooseContact
displayContact
removeContact
contactsCount
Contacts
o The most inconsistent between platforms

o Test on devices, not just simulators!
File
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
Media (Audio)
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/Store
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
SMS/Telephony
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
Questions or Feedback
@alunny, andrew.lunny@nitobi.com

Phonegap API Deep Dive

Încărcat de

Informații document

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Phonegap API Deep Dive

Încărcat de

Drepturi de autor:

Formate disponibile

PhoneGap API Deep Dive

Andrew Lunny, Nitobi, July 8 2010

A set of consistent cross-platform APIs for

This is possible for a large subset of PhoneGap

• Some functionality is not present on all hardware

When in doubt, check mobile-spec

Device, Network, Notification, Debug

o Fundamentals for mobile apps and development

A JS Object with String/Boolean fields

except Palm: navigator.device.name

except Palm navigator.device.gap ||

One common public function: isReachable

BlackBerry also has Network.XHR

Android 2.2: ononline and onoffline events

The callback function is called with the parameter foo,

Palm/Symbian (what we want going forward)

Not on Symbian navigator.notification.beep

Not on Palm navigator.notification.vibrate

BlackBerry only navigator.notification.blink

iPhone only confirm

Android currently uses console.log

Both Android and BlackBerry should and will

o All related to physical state of device

Not supported on BlackBerry because the hardware

Palm and Symbian: no hardware support

BlackBerry: depends on the device, not implemented

Where available (iPhone, Android 2.0+), PhoneGap

Unlikely for BlackBerry (only makes sense on

Android: probably wait for Browser implementation

iPhone fires orientationChange event

CSS3 media queries can also be used

Camera, Contacts, File, Media (Audio),

o Reading and writing what's normally inaccessible

Android, iPhone success is passed a base-64 string

BlackBerry, Palm success is passed a file path to the

Android, Blackberry, navigator.contacts.find

filter is an object of type

o The most inconsistent between platforms

Palm webOS does not allow File I/O

Android & iPhone: based loosely on W3C file spec:

iPhone and Android can record audio also

Android < 2.0: sets up an SQLite database,

Symbian: key/value store:

BlackBerry: key/value store:

navigator.sms.send(number, message, success,

Any platform: set link HREF to sms: or tel:

In all cases, the user must confirm before the call or

S-ar putea să vă placă și