The document presents a comprehensive overview of Apache Cordova APIs, including features for device motion detection via accelerometer, capturing audio/video, and accessing contacts and device information. It outlines methods for capturing media, error handling, and interaction with device hardware and software, along with practical coding examples. Additionally, it discusses event handling within Cordova applications, notably the 'deviceready' event that indicates readiness for API calls.

1. Gran Sasso Science Institute
Ivano Malavolta
Apache Cordova APIs
version 6.x

2. Roadmap
• Accelerometer
• Compass
• Capturing audio/video & camera
• Media playback
• Contacts
• Connection
• Device information
• Events
• Dialogs

3. Accelerometer
navigator.accelerometer
It is a global object that captures device motion in the x, y, and z directions
You can call 3 methods on it:
getCurrentAcceleration
watchAcceleration
clearWatch
Accelerometer

4. getCurrentAcceleration
getCurrentAcceleration(win, fail);
It gets the current acceleration along the x, y, and z axis
win
callback function with an Acceleration parameter
fail
error callback

5. watchAcceleration
var watchID = navigator.accelerometer.watchAcceleration(win, fail, [options]);
It gets the device's current acceleration at a regular interval
win
callback function with an Acceleration parameter, it is called at regular intervals
fail
error callback
options
the interval is specified in the frequency parameter

6. clearWatch
clearWatch(watchID);
Stop watching the Acceleration referenced by the watch ID parameter
watchID
ID returned by accelerometer.watchAcceleration

7. The Acceleration object
It contains accelerometer data captured at a specific point in time
Properties
x (Number): Amount of acceleration on the x-axis. (in m/s^2)
y (Number): Amount of acceleration on the y-axis. (in m/s^2)
z (Number): Amount of acceleration on the z-axis. (in m/s^2)
timestamp (DOMTimestamp): Creation timestamp in milliseconds
these values include the effect
of gravity (9.81 m/s^2)

8. Accelerometer example
var options = { frequency: 3000 };
var watchID = navigator.accelerometer.watchAcceleration(win, fail, options);
function win(acc) {
if((acc.x === 0) && (acc.y === 0) && (acc.z === 9.81)) {
console.log('I am on a table');
stop();
} else {
console.log('Please, leave me on the table');
}
}
function fail() {
alert('error');
}
function stop() {
if(watchID) {
navigator.accelerometer.clearWatch(watchID);
watchID = null;
}
}

9. Shake detection
var previousReading = {x: null, y: null, z: null};
navigator.accelerometer.watchAcceleration(function (reading) {
var changes = {},
threshold = 30;
if (previousReading.x !== null) {
changes.x = Math.abs(previousReading.x, reading.x);
changes.y = Math.abs(previousReading.y, reading.y);
changes.z = Math.abs(previousReading.z, reading.z);
}
if (changes.x + changes.y + changes.z > (threshold * 3)) {
console.log(“shake detected”);
}
previousReading = {
x: reading.x,
y: reading.y,
z: reading.z
}
}, errorCallback, { frequency: 300 });

10. Accelerometer
navigator.device.capture
Provides access for capturing directly from the device
Audio
Image
Video
Capturing Audio and Video
Omogeneous APIs between audio, image, and video
capturing based on a W3C specification

11. Supported formats
The navigator.device.capture object contains the supported formats it can record in
three properties
supportedAudioModes
The audio recording formats supported by the device
supportedImageModes
The recording image sizes and formats supported by the device
supportedVideoModes
The recording video resolutions and formats supported by the device
They all contain an array of
ConfigurationData objects

12. The ConfigurationData object
It is used to describe media capture modes supported by the device
Properties
type (String)
the string in lower case representing the media type
height (Number)
the height of the image or video in pixels
width (Number)
the height of the image or video in pixels
ex.
• video/3gpp
• video/quicktime
• image/jpeg
• audio/amr
• audio/wav

13. Supported format example
var imageModes = navigator.device.capture.supportedImageModes;
for(var i=0; i <imageModes.length; i++) {
var mode = imageModes[i];
console.log(mode.type);
console.log(mode.height);
console.log(mode.width);
}

14. Audio capture
captureAudio(win, fail, [options]);
Starts the audio recorder app and returns information about captured audio clip files
win
callback function with an array of MediaFile parameter
fail
error or when the users cancels the capture operation before capturing any media file
options
audio capture options
It uses the device's default
audio recording app
The operation allows the device
user to capture multiple
recordings in a single session

15. Options
limit (Number)
the maximum number of audio clips the user can record in a single capture operation
duration (Number)
the maximum duration of an audio sound clip, in seconds
not supported in iOS
not supported in Android

16. Audio capture example
var options = { limit: 2, duration: 5 };
navigator.device.capture.captureAudio(win, fail, options);
function win(mediaFiles) {
var i;
for (i=0; i<mediaFiles.length; i++) {
console.log(mediaFiles[i]);
}
}
function fail(error) {
console.log(‘Error with code: ' + error.code);
}

17. Image capture
captureImage(win, fail, [options]);
Start the camera application and return information about captured image file(s)
win
callback function with an array of MediaFile parameter
fail
error or when the users cancels the capture operation before capturing any media file
options
image capture options
It uses the device's
default camera app
The operation allows the device
user to capture multiple images
in a single session

18. Options
limit (Number)
the maximum number of photos the user can take in a single capture operation
not supported in iOS

19. Video capture
captureVideo(win, fail, [options]);
Start the camera application and return information about captured video file(s)
win
callback function with an array of MediaFile parameter
fail
error or when the users cancels the capture operation before capturing any media file
options
video capture options
It uses the device's
default camera app
The operation allows the device
user to capture multiple videos
in a single session

20. Options
limit (Number)
the maximum number of videos the user can take in a single capture operation
duration (Number)
the maximum duration of each video, in seconds
not supported in iOS

21. The MediaFile object
A MediaFile encapsulates properties of a media capture file
Properties
name (String): the name of the file, without path information
fullPath (String) : the full path of the file, including the name
type (String): the file's mime type
lastModifiedDate (Date): the date and time that the file was last modified
size (Number): the size of the file, in bytes

22. MediaFile format data
mediaFile.getFormatData(win, [fail]);
It is used to get information about the format of a captured media file
win
callback function with a MediaFileData parameter
fail
error callback

23. The MediaFileData object
Encapsulates format information about a media file
Properties
codecs (String): The actual format of the audio and video content
bitrate (Number) : The average bitrate of the content (zero for images)
height (Number): the height of the image or video in pixels (zero for audio clips)
width (Number): the width of the image or video in pixels (zero for audio clips)
duration (Number): the length of the video or sound clip in seconds (zero for images)

24. Capture Error
Encapsulates the error code resulting from a failed media capture operation
It contains a pre-defined error code
CaptureError.CAPTURE_INTERNAL_ERR
CaptureError.CAPTURE_APPLICATION_BUSY
CaptureError.CAPTURE_INVALID_ARGUMENT
CaptureError.CAPTURE_NO_MEDIA_FILES
CaptureError.CAPTURE_NOT__SUPPORTED

25. Camera
navigator.camera
It provides an home-grown API for capturing images from the device’s default camera
application
It is developed in-house by Cordova in order to provide more options to developers
Methods:
getPicture
cleanup

26. Getting pictures from the camera
camera.getPicture(win, [fail], [options]);
Takes a photousing the camera or retrieves a photo from the device's album
win
callback function with a image data parameter
fail
error callback
options
capture parameters
The result of getPicture can be:
• a base64 encoded string
• the URI of an image file
Encoding the image using Base64
can cause memory issues on some
devices

27. getPicture options
getPicture() can be called with the following options
{
quality : 75,
destinationType : Camera.DestinationType.DATA_URL,
sourceType : Camera.PictureSourceType.CAMERA,
allowEdit : true,
encodingType: Camera.EncodingType.JPEG,
targetWidth: 100,
targetHeight: 100,
popoverOptions: CameraPopoverOptions,
saveToPhotoAlbum: false
};

28. getPicture options
quality (Number)
quality of saved image Range [0, 100]
allowEdit (boolean)
allow simple editing of the image before selection
destinationType (Number)
not supported in Android

29. getPicture options
sourceType (Number)
encodingType (Number)

30. getPicture options
mediaType (Number)
correctOrientation (boolean)
Rotate the image to correct for the orientation of the device during capture

31. getPicture options
saveToPhotoAlbum (boolean)
Save the image to the photoalbum on the device after capture
popoverOptions (object)
iPad only

32. getPicture options
targetWidth, targetHeight (Number)
width/height in pixels to scale image
cameraDirection (Number)

33. Camera cleanup
camera.cleanup(win, [fail]);
Removes intermediate photos taken by the camera from temporary storage
win
callback function
fail
error callback
Valid only when
• the value of Camera.sourceType === Camera.PictureSourceType.CAMERA
• the Camera.destinationType === Camera.DestinationType.FILE_URI
iOS only

34. Camera example
var options = {quality: 50,
destinationType: Camera.DestinationType.FILE_URI,
sourceType: Camera.PictureSourceType.CAMERA
};
setTimeout(function() {
navigator.camera.getPicture(win, fail, options);
}, 3000);
function win(imageURI) {
var element = document.getElementById('block');
element.setAttribute('src', imageURI);
}
function fail (error) {
console.log(error); // this is provided by the device’s native code
}

35. Accelerometer
Media
The Media object provides the ability to record and play back audio files on a device
Media playback
It does not adhere to any W3C
specification, it is just a convenience API
provided by Cordova

36. The Media object
var media = new Media(src, win, [fail], [status]);
src (String): A URI containing the audio content
The URI can be local or can be a URL addressable by a standard HTTP get request
win: callback executed when the object executes a play, record, or stop action
fail: error callback
status: callback executed to indicate status changes
Media status parameter values:
• Media.MEDIA_NONE = 0;
• Media.MEDIA_STARTING = 1;
• Media.MEDIA_RUNNING = 2;
• Media.MEDIA_PAUSED = 3;
• Media.MEDIA_STOPPED = 4;

37. Media methods

38. Media example
var media = new Media(“http://path/to/mp3”, win, fail);
media.play();
setTimeout(function() {
media.seekTo(10000);
}, 5000);
// every second we log the position
var myTimer = setInterval(function () {
media.getCurrentPosition(
function (position) {
if (position > -1) {
console.log((position) + " seconds");
}
});
}, 1000);
function stopAudio() {
if (media) {
media.stop();
}
clearInterval(myTimer);
myTimer = null;
}

39. Recording example
function recordAudio() {
var src = ‘recording.mp3’;
var mediaRec = new Media(src, manageSuccess, manageError);
mediaRec.startRecord();
}
function manageSuccess() {
console.log(‘Audio recording successful’);
}
function manageError(error) {
console.log(‘Error recoding: ‘ + error.code);
}

40. Media Error
Encapsulates the error code resulting from a failed media operation
It contains a pre-defined error code
MediaError.MEDIA_ERR_ABORTED
MediaError.MEDIA_ERR_NETWORK
MediaError.MEDIA_ERR_DECODE
MediaError.MEDIA_ERR_NONE_SUPPORTED

41. Accelerometer
navigator.contacts
A global object that provides access to the device contacts DB
You can call 3 methods on navigator.contacts
• navigator.contacts.create
• navigator.contacts.find
• navigator.contacts.pickContact
Contacts

42. Creating contacts
navigator.contacts.create(properties);
One of the few synchronous functions of Cordova
It returns a new Contact object
The properties parameter is a map of properties of the new Contact object
To persist the Contact object to the device, you have to invoke the Contact.save method

43. The Contact object
It contains all the properties that a contact can have
Every platform has its own quirks,
you better check them on the
Cordova documentation

44. The Contact object
A contact object provides the following methods:
clone()
returns a new Contact object that is a deep copy of the calling object, its id property is null
remove(win, fail)
removes the contact from the device contacts database
save(win, fail)
saves a new contact to the device contacts database
updates an existing contact if a contact with the same id already exists

45. Create contact example
var contact = navigator.contacts.create({
"displayName": “Ivano“
});
var name = new ContactName();
name.givenName = “Ivano“;
name.familyName = “Malavolta“;
contact.name = name;
contact.birthday = new Date(“19 July 1983");
contact.save(win, fail);
function win(contact) {
console.log("Save Success");
};
function fail(contactError) {
console.log("Error = " + contactError.code);
};

46. Finding contacts
navigator.contacts.find(fields, win, fail, options);
It queries the device contacts database and returns an array of Contact objects
fields: contact fields to be used as search qualifier. Only these fields will have values in the
resulting Contact objects
win: callback function with the array of contacts returned from the contacts database
fail: error callback
options: search options to filter contacts

47. Contact fields
Specifies which fields should be used as qualifiers of the search
var fields = ["displayName", "name"]; // or [“*”]
navigator.contacts.find(fields, win, fail);
function win(contacts) {
console.log(‘ok');
};
function fail(err) {
console.log(err.code);
};

48. Contact find options
Contains properties that can be used to filter the results
filter (String)
the search string used to find contacts, a case-insensitive, partial value match is applied
to each field specified in the contactFields parameter
multiple (Boolean)
determines if the find operation should return multiple contacts

49. Contact Error
Encapsulates the error code resulting from a failed lookup operation in the contacts DB
It contains a pre-defined error code
ContactError.UNKNOWN_ERROR
ContactError.INVALID_ARGUMENT_ERROR
ContactError.TIMEOUT_ERROR
ContactError.PENDING_OPERATION_ERROR
ContactError.IO_ERROR
ContactError.NOT_SUPPORTED_ERROR
ContactError.PERMISSION_DENIED_ERROR

50. Contact find example
var options = new ContactFindOptions();
options.filter = “Ivano";
options.multiple = true;
filter = ["displayName",“birthday"];
navigator.contacts.find(filter, win, fail, options);
function win(contacts) {
for (var i=0; i<contacts.length; i++) {
console.log(contacts[i].displayName);
}
};
function fail(contactError) {
console.log("Error = " + contactError.code);
};

51. Picking contacts
navigator.contacts.pickContact(win,[fail]);
Launches the device contact picker to select a single contact
win: callback function with the selected Contact object
fail: error callback navigator.contacts.pickContact(win, fail);
function win(contact) {
console.log(’Just selected: ' + JSON.stringify(contact));
}
function fail(error) {
console.log('Error: ' + error);
}

52. Accelerometer
navigator.connection
provides information about the device's cellular and wifi connection
it is synchronous and very fast
You can access a single property
• connection.type
Network connection

53. Connection.type
Encapsulates the error code resulting from a failed lookup operation in the contacts DB
Values:
Connection.UNKNOWN
Connection.ETHERNET
Connection.WIFI
Connection.CELL_2G
Connection.CELL_3G
Connection.CELL_4G
Connection.CELL
Connection.NONE
iOS can't detect the type of cellular network
connection, it will return always Connection.CELL

54. Connection events
Based on two main events:
online - fires when the application's network connection changes to being
online (that is, it is connected to the Internet)
offline - fires when the application's network connection changes to being
offline (that is, no Internet connection available)
document.addEventListener(‘offline’, onOffline, false);
function onOffline() {
console.log(‘The user is not connected to the Internet now’);
}

55. Accelerometer
window.device
Contains information about the device’s hardware and software
It is assigned to the window global object
Device information

56. Device properties
A device object provides the following properties:
device.model
the name of the device's model or product (ex. “iPad 2”, “iPhone 5,1”,etc.)
device.cordova
the version of Cordova running on the device
device.platform
the devices’ operating system (ex. “Android”, “iOS”, etc.)
http://theiphonewiki.com/wiki/Models

57. Device properties
device.uuid
a unique identifier of the user’s device (UUID)
Android: a random 64-bit integer generated at device’s first boot
iOS: a string of hash values created from multiple hardware identifies
device.version
the OS version of the device (ex. “4.1”,“2.2”,etc.)
in iOS it is not reliable: The uuid on iOS is unique for each
device, but varies for each app, for each installation

58. Device information example
function getDeviceInfo() {
var element = document.getElementById('deviceProperties');
element.innerHTML = 'Device Model: ' + device.model + '<br />' +
'Device Cordova: ' + device.cordova + '<br />' +
'Device Platform: ' + device.platform + '<br />' +
'Device UUID: ' + device.uuid + '<br />' +
'Device Version: ' + device.version + '<br />';
}

59. Accelerometer
An event is an action that can be detected by your JavaScript code
In traditional JS programs, any element of the page can have certain events
ontouchstart, onclick, ...
To use any event, you’ll want to use an event listener
document.addEventListener(EVENTNAME, callback, false);
Events

60. Cordova events
• deviceready
• pause, resume
• batterycritical, batterylow, batterystatus
• backbutton, menubutton, searchbutton
• startcallbutton, endcallbutton
• volumedownbutton, volumeupbutton
these work on Blackberry 10 only
Android buttons events

61. deviceready
It is the most important in event in a Cordova app
Once deviceready is fired, you know two things:
• The DOM has loaded
• the Cordova native API are loaded too

62. App lifecycle events
Based on two main events:
pause
fires when an application is put into the background
resume
fires when a paused application is put back into the foreground
resign, active
iOS-specific events that are triggered when the users locks/unlocks the device
IOS: In the pause handler, any calls to the Cordova API or to
native plugins that go through Objective-C do not work,, they
are only processed when the app resumes.

63. Battery events
Based on two main events:
batterycritical
fires when the battery has reached the critical level threshold
batterylow
similar to batterycritical, but with a higher threeshold
batterystatus
fires a change in the battery status is detected
This value is device-specific
The battery status must
change of at least 1%

64. Battery events
The handler of a battery event is always called with an object that contains two properties:
level (Integer)
The percentage of battery (0-100)
isPlugged (Boolean)
true if the device is plugged to the battery charger

65. Events support across platforms

66. Accelerometer
Allows yout to provide feedback to the user
• alert
• confirm
• prompt
• beep
• vibrate
Dialogs

67. Alert
navigator.notification.alert(message, callback, [title], [button]);
Shows a custom alert to the user
• message: the string to present to the user
• callback: the function invoked when the user taps on the button
• title: title of the alert (default is “Alert”)
• button: name of the confirm button (default is “Ok”)

68. Confirm
navigator.notification.confirm(message, callback, [title], [buttons]);
Similarly to alert, it shows a customizable confirmation dialog to the user
• message: the string to present to the user
• callback: the function invoked when the dialog is dismissed
it takes a “buttonIndex“parameter to know which button has been pressed (it starts from 1)
• title: title of the dialog (default is “Confirm”)
• buttons:array of strings containing the button labels (default is [‘Ok’, ‘Cancel’])

69. Example
navigator.notification.confirm(
'You are the winner!', // message
onConfirm, // callback to invoke with index of button pressed
'Game Over', // title
['Restart','Exit'] // buttonLabels
);
function onConfirm(buttonIndex) {
alert('You selected button ' + buttonIndex);
}

70. Prompt
navigator.notification.prompt(message, callback, [title], [buttons], [text]);
It shows a customizable dialog with a prompt to the user
• message: the string to present to the user
• callback: the function invoked when the dialog is dismissed
it takes a “results“ parameter to know which button has been pressed (it starts from 1) and
the text entered by the user
• title: title of the dialog (default is “Prompt”)
• buttons:array of strings containing the button labels (default is [‘Ok’, ‘Cancel’])
• text: default text in the input box

71. Beep
navigator.notification.beep(times);
It playes a beep sound
• times (Number): the number of times to repeat the beep
Android plays the default "Notification ringtone" specified
under the "Settings/Sound & Display" panel

72. Vibration
navigator.vibrate(milliseconds);
It vibrates the device
• milliseconds (Number): the duration of the vibration
iOS ignores the millisecondsparameter, it always vibrates for a
fixed amount of time

73. What is not covered in this lecture
• Cordova Native Platform Dev workflow & Plugman
• Cordova’s secondary APIs:
• Splashscreen, InAppBrowser, Globalization, StatusBar
• Geolocalization
• File API
• PhoneGap Build
• How to develop a plugin

74. References
http://cordova.apache.org/docs/en/edge

75. LAB
1. Create a view to add a new picture of a product
– camera access
2. Manage the presence/absence of an Internet connection
– network connection checks
3. Add the feature of calling the producer of a product
4. Add the feature of sending an sms to the producer of a product
5. Add the feature of sending an email to the producer of a product
6. Add the feature of adding the producer of a product to the user’s contacts
– access to contacts

76. Contact
Ivano Malavolta |
Gran Sasso Science Institute
iivanoo
ivano.malavolta@gssi.infn.it
www.ivanomalavolta.com