Gran Sasso Science Institute

Ivano Malavolta

Apache Cordova APIsversion 6.x

Roadmap• Accelerometer

• Compass

• Capturing audio/video & camera

• Media playback

• Contacts

• Connection

• Device information

• Events

• Dialogs

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

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

watchAccelerationvar 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

clearWatchclearWatch(watchID);

Stop watching the Acceleration referenced by the watch ID parameter

watchID

ID returned by accelerometer.watchAcceleration

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)

Accelerometer examplevar 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;

}}

Shake detectionvar 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 });

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

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

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

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);

}

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

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

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);

}

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

Options

limit (Number)

the maximum number of photos the user can take in a single capture operation

not supported in iOS

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

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

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

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

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)

Capture ErrorEncapsulates 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

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

Getting pictures from the camera

camera.getPicture(win, [fail], [options]);

Takes a photo using 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

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

};

getPicture optionsquality (Number)

quality of saved image Range [0, 100]

allowEdit (boolean)

allow simple editing of the image before selection

destinationType (Number)

not supported in Android

getPicture optionssourceType (Number)

encodingType (Number)

getPicture optionsmediaType (Number)

correctOrientation (boolean)

Rotate the image to correct for the orientation of the device during capture

getPicture optionssaveToPhotoAlbum (boolean)

Save the image to the photo album on the device after capture

popoverOptions (object)

iPad only

getPicture optionstargetWidth, targetHeight (Number)

width/height in pixels to scale image

cameraDirection (Number)

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

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

}

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

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;

Media methods

Media examplevar media = new Media(“http://path/to/mp3”, win, fail);media.play();setTimeout(function() {

media.seekTo(10000); }, 5000);

// every second we log the positionvar 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;

}

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);

}

Media ErrorEncapsulates 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

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

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

The Contact objectIt contains all the properties that a contact can have

Every platform has its own quirks, you better check them on the Cordova documentation

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

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);

};

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

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);};

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

Contact ErrorEncapsulates 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

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);

};

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);

}

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

Connection.typeEncapsulates 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

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’);

}

Accelerometer

window.device

Contains information about the device’s hardware and software

It is assigned to the window global object

Device information

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

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

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 />';

}

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

Cordova events

• deviceready

• pause, resume

• batterycritical, batterylow, batterystatus

• backbutton, menubutton, searchbutton

• startcallbutton, endcallbutton

• volumedownbutton, volumeupbuttonthese work on Blackberry 10 only

Android buttons events

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

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.

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%

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

Events support across platforms

Accelerometer

Allows yout to provide feedback to the user

• alert

• confirm

• prompt

• beep

• vibrate

Dialogs

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”)

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’])

Example

navigator.notification.confirm('You are the winner!', // messageonConfirm, // callback to invoke with index of button pressed

'Game Over', // title['Restart','Exit'] // buttonLabels

);

function onConfirm(buttonIndex) {alert('You selected button ' + buttonIndex);

}

Promptnavigator.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

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

Vibration

navigator.vibrate(milliseconds);

It vibrates the device

• milliseconds (Number): the duration of the vibration

iOS ignores the milliseconds parameter, it always vibrates for a fixed amount of time

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

References

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

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

ContactIvano Malavolta |

Gran Sasso Science Institute

iivanoo

ivano.malavolta@gssi.infn.it

www.ivanomalavolta.com