Phonegap Bridge – Device, Network, Console, Geolocation API’s CIS 136 Building Mobile Apps 1

Device API 2

DevicePlug-in org.apache.cordova.device 3  describes the device's hardware and software  Global in scope, but not available until the device is ready  Device object has 5 properties  cordova  model  platform  uuid  version

device.cordova 4  Gets the version of Cordova running on the device  Ex: document.addEventListener("deviceready", onDeviceReady, false); function onDeviceReady() { $(‘info’).html(device.cordova); }

device.model 5  Gets the the name of the device's model or product  set by the device manufacturer and may be different across versions of the same product  Might get the production code name  Ex: document.addEventListener("deviceready", onDeviceReady, false); function onDeviceReady() { $(‘info’).html(device.model); } Android: Nexus One returns "Passion" (Nexus One code name) Motorola Droid returns "voles" BlackBerry: Torch 9800 returns "9800" iOS: for the iPad Mini, returns iPad2,5; iPhone 5 is iPhone 5,1.

device.platform 6  Gets the operating system name  Ex: document.addEventListener("deviceready", onDeviceReady, false); function onDeviceReady() { $(‘info’).html(device.platform); }

device.uuid 7  Gets the Universally Unique Identifier  a 128-bit value that is ‘practically unique’  determined by the device manufacturer and are specific to the device's platform or model.  Ex: document.addEventListener("deviceready", onDeviceReady, false); function onDeviceReady() { $(‘info’).html(device.uuid); }

device.version 8  Gets the operating system version  Kitkat  Ex: document.addEventListener("deviceready", onDeviceReady, false); function onDeviceReady() { $(‘info’).html(device.uuid); }

Network Information API 9

Network Information Plug-in org.apache.cordova.network-information 10  provides information about the device's cellular and wifi connection  Indicates if the device has an internet connection  Connection Object has 1 property and 8 constants  connection.type  Connection.UNKNOWN  Connection.ETHERNET  Connection.WIFI  Connection.CELL_2G  Connection.CELL_3G  Connection.CELL_4G  Connection.CELL  Connection.NONE

navigator.connection.type 11  determine the device's network connection state, and type of connection  Ex: document.addEventListener("deviceready", onDeviceReady, false); function onDeviceReady() { var networkState = navigator.connection.type; $(‘info’).html(networkState); }

Network States 12  Using the type of connection, coupled with the translation of network state constants, can provide textual description - quirky document.addEventListener("deviceready", onDeviceReady, false); function onDeviceReady() { var networkState = navigator.connection.type; var states = {}; states[Connection.UNKNOWN] = 'Unknown connection'; states[Connection.ETHERNET] = 'Ethernet connection'; states[Connection.WIFI] = 'WiFi connection'; states[Connection.CELL_2G] = 'Cell 2G connection'; states[Connection.CELL_3G] = 'Cell 3G connection'; states[Connection.CELL_4G] = 'Cell 4G connection'; states[Connection.CELL] = 'Cell generic connection'; states[Connection.NONE] = 'No network connection'; $(‘info’).html(states[networkState]); }

Network related events 13  offline - fires when an application goes offline, and the device is not connected to the Internet document.addEventListener("offline", yourCallbackFunction, false);  online - fires when an application goes online, and the device becomes connected to the Internet document.addEventListener("offline", yourCallbackFunction, false);

Console API 14

Cordova Console Plugin org.apache.cordova.console 15  ensure that console.log() is as useful as it can be  Ex: document.addEventListener("deviceready", onDeviceReady, false); function onDeviceReady() { console.log(“message to console – Hello there”); }

geolocation API 16

Geolocation Plug-in org.apache.cordova.geolocation 17  Makes the app location-aware  information about the device's location, such as latitude and longitude  Common sources of location information include:  Global Positioning System (GPS)  location inferred from network signals such as:  IP address, RFID, WiFi and Bluetooth MAC addresses, and GSM/CDMA cell IDs  There is no guarantee that the API returns the device's actual location.

navigator.geolocation 18  determine the device's network connection state, and type of connection  Has 3 methods  getCurrentPosition  watchPosition  clearWatch  Exposes 3 objects  Position  PositionError  coordinates

navigator.geolocation.getCurrentPosition 19  Returns the device's current position to the Success callback with a Position object as the parameter  Position object contains the current GPS coordinates  Ex: document.addEventListener("deviceready", onDeviceReady, false); function onDeviceReady() { navigator.geolocation.getCurrentPosition(success,error); } function success(position) { // gets position object } function error(positionerror) { //gets PositionError object }

navigator.geolocation.getCurrentPosition 20  Position object has 7 coordinate properties and a timestamp  position.coords.latitude  position.coords.longitude  position.coords.altitude  position.coords.accuracy  position.coords.altitudeAccuracy  position.coords.heading  position.coords.speed  position.timestamp  Ex:

navigator.geolocation.watchPosition 21  Returns the device's current position when a change in position is detected  Returns the position to the Success callback with a Position object as the parameter  Position object contains the current GPS coordinates  Ex: document.addEventListener("deviceready", onDeviceReady, false); function onDeviceReady() { watchID = navigator.geolocation.watchPosition(success,error,opts); } function success(position) { // gets position object } function error(positionerror) { //gets PositionError object }

navigator.geolocation.watchPosition 22  Gets a watchID that references the watch position interval  optional parameters customize the retrieval of the position  Timeout - maximum length of time (milliseconds) that is allowed to pass from the call to get until the call to watch, until the success event occurs (number)  enableHighAccuracy -By default, the device attempts to retrieve a Position using network-based methods  Setting this property to true tells the framework to use more accurate methods, such as satellite positioning. (Boolean)  maximumAge: cached position whose age is no greater than the specified time in milliseconds (number)

navigator.geolocation.clearWatch 23  Like a timer - Stops watching for changes to the device's location referenced by the watchID parameter var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { enableHighAccuracy: true }); …. Later… navigator.geolocation.clearWatch(watchID);

Position object 24  Position object has 7 coordinate properties and a timestamp  position.coords.latitude  position.coords.longitude  position.coords.altitude  position.coords.accuracy  position.coords.altitudeAccuracy  position.coords.heading  position.coords.speed  position.timestamp  Ex:

Position error object 25  Created when an error occurs  code: A predefined error code  message: Error message describing the details of the error encountered  Codes:  PositionError.PERMISSION_DENIED  Returned when users do not allow the app to retrieve position information  PositionError.POSITION_UNAVAILABLE  Returned when the device is unable to retrieve a position  PositionError.TIMEOUT  Returned when the device is unable to retrieve a position within the time specified by the timeout included in geolocationOptions

Concerns 26  Collection and use of geolocation data raises important privacy issues  sensitive because it can reveal user's whereabouts  if stored, the history of their travels  app's privacy policy should discuss:  how the app uses geolocation data  whether it is shared with any other parties  the level of precision of the data (for example, coarse, fine, ZIP code level)  Should obtain the user's permission (e.g., by presenting choices for OK and No Thanks).