phonegap api deep dive

8/9/2019 Phonegap API Deep Dive

1/26

PhoneGap API Deep Dive

Andrew Lunny, Nitobi, July 8 2010


2/26

PhoneGap Goal

A set of consistent cross-platform APIs foraccessing native device capabilities through

JavaScript

This is possible for a large subset of PhoneGapAPIs


3/26

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


4/26

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.como http://github.com/phonegap/phonegap-docs/tree/

rework Better expose and fix inconsistencies

When in doubt, check mobile-spec


5/26

API Outline

BasicDev

iceNetwork

NotificationDebugConsole

Sensors

Acce lerometerCompass

G eoloca tionOrientation

User Data / F ile Storage

CameraContac ts

FileMed ia (Aud io)

Storage/StoreSMS/Telephony


6/26

Basics

o Fundamentals for mobile apps and developmento Well-supported on all platforms

o Consistent core, with platform specific extensions

Device, Network, Notification, Debug


7/26

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 Palmand Symbian:

navigator.device.gap ||navigator.device.gapVersion

device.gap = iPhone and BlackBerrydevice.gapVersion = Android


8/26

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 anXMLHttpRequest by default

Android 2.2: ononline and onoffline events


9/26

navigator.network.isReachable(hostname,callback, options);

The callback function is called with the parameterfoo,which is used to compare the NetworkStatus againstthe 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


10/26

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


11/26

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


12/26

Sensors

o All related to physical state of device

o Time sensitive and liable to changeo Consistent between platforms and consistent

between environment moduleso Moving into the browserGoogle I/O Keynote promises all of these in

Browser soon:http://bit.ly/android-iocf. http://dev.w3.org/geo/api/spec-source-

orientation.html

Accelerometer, Compass,Geolocation, Orientation


13/26

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/26

AccelerometeriPhone, Android, BlackBerry, Palm, Symbian.wrt

navigator.accelerometer.getCurrentAccelerationnavigator.accelerometer.watchAccelerationnavigator.accelerometer.clearWatch

Not supported on BlackBerry because the hardwarehas limited support (depending on the handset)


15/26

Compass

iPhone, Android,BlackBerry, Palm, Symbian.wrt

navigator.compass.getCurrentHeadingnavigator.compass.watchHeadingnavigator.compass.clearWatch

Palm and Symbian: no hardware support

BlackBerry: depends on the device, not implementedyet


16/26

Geolocation

iPhone, Android,BlackBerry, Palm, Symbian.wrt

navigator.geolocation.getCurrentPositionnavigator.geolocation.watchPosition

navigator.geolocation.clearWatch

Where available (iPhone, Android 2.0+), PhoneGapuses the browser's geolocation API, rather thanimplementing our own


17/26

OrientationiPhone,Android, BlackBerry, Palm, Symbian.wrt

navigator.orientation.getCurrentOrientationnavigator.orientation.watchOrientationnavigator.orientation.clearWatch

Unlikely for BlackBerry (only makes sense oncertain handsets)

Android: probably wait for Browser implementation

iPhone fires orientationChange eventautomagically; you can use window.orientationinstead of the PhoneGap method

CSS3 media queries can also be used


18/26

User Data / File Storage

o Reading and writing what's normally inaccessibleo Most prone to inconsistencybetween platformsbetween device models/OS versions

o Least settled PhoneGap APIs

Camera, Contacts, File, Media (Audio),Storage/Store, SMS/Telephony


19/26

CameraiPhone, Android, BlackBerry, Palm, Symbian.wrt

navigator.camera.getPicture(success, error,options);

Android, iPhone

BlackBerry, Palm

Symbian.wrt

success is passed a base-64 stringof image data

success is passed a file path to theimage

success is passed an array of filepaths


20/26

ContactsiPhone, Android, BlackBerry, Palm, Symbian.wrt

Android, Blackberry,Symbian

iPhone

navigator.contacts.find(filter, success, error,options);

filter is an object of typeContact

getAllContactsnewContact

chooseContactdisplayContactremoveContactcontactsCount


21/26

Contacts

o The most inconsistent between platformso Test on devices, not just simulators!


22/26

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 looselyon W3C file spec:http://bit.ly/w3cfileexample API usage: http://bit.ly/pg-file


23/26

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, notMedia

iPhone and Android can record audio also iPhone: startAudioRecord,stopAudioRecord

Android: startRecord,stopRecordingAudio


24/26

Storage/StoreiPhone,Android, BlackBerry, Palm, Symbian.wrt

iPhone/Android 2.0+/Palm: unneeded - uselocalStorage 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.getnavigator.store.put


25/26

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: ortel:

In all cases, the user must confirm before the call ormessage is placed


26/26

@alunny, [email protected]

Questions or Feedback

phonegap api deep dive

Documents