[2015/2016] apache cordova apis
TRANSCRIPT
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 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 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
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
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
www.ivanomalavolta.com