Phonegap Bridge – Device, Network, Console, Geolocation API’s

CIS 136 Building Mobile Apps

1

2

Device API

3

DevicePlug-inorg.apache.cordova.device

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

4

device.cordova Gets the version of Cordova running on the device Ex:

document.addEventListener("deviceready", onDeviceReady, false);function onDeviceReady() { $(‘info’).html(device.cordova);}

5

device.model 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.

6

device.platform Gets the operating system name

Ex:

document.addEventListener("deviceready", onDeviceReady, false);function onDeviceReady() { $(‘info’).html(device.platform);}

7

device.uuid 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);}

8

device.version Gets the operating system version

Kitkat 4.4.4 Ex:

document.addEventListener("deviceready", onDeviceReady, false);function onDeviceReady() { $(‘info’).html(device.uuid);}

9

Network Information API

10

Network Information Plug-inorg.apache.cordova.network-information 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

11

navigator.connection.type 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);}

12

Network States

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

13

Network related events 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);

14

Console API

15

Cordova Console Pluginorg.apache.cordova.console 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”); }

16

geolocation API

17

Geolocation Plug-inorg.apache.cordova.geolocation

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.

18

navigator.geolocation determine the device's network connection state, and

type of connection Has 3 methods

getCurrentPosition watchPosition clearWatch

Exposes 3 objects Position PositionError coordinates

19

navigator.geolocation.getCurrentPosition 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}

20

navigator.geolocation.getCurrentPosition 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:

21

navigator.geolocation.watchPosition 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}

22

navigator.geolocation.watchPosition 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)

23

navigator.geolocation.clearWatch 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);

24

Position object 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:

25

Position error object 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

26

Concerns 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).