This presentation has been developed in the context of the Mobile Applications Development course, DISIM, University of L'Aquila (Italy), Spring 2016.
http://www.ivanomalavolta.com
Rising Above_ Dubai Floods and the Fortitude of Dubai International Airport.pdf
Â
[2015/2016] Apache Cordova APIs
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
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
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;
}
}
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
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
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;
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);
}
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â);
}
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
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
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
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
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