Uso de la API de PhoneGap

A continuación vamos a ver ejemplos de uso de algunos de estos plugins.

Importante: En todos los casos tendremos que esperar a que la API de PhoneGap se haya terminado de cargar.

Información del dispositivo (cordova-plugin-device)

Este plugin permite obtener información del dispositivo como modelo, sistema operativo, etc. Para su utilización tenemos que esperar que se cargue la API de PhoneGap y ya podremos acceder a estos valores a través de las propiedades del objeto "device":

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(device.cordova);
}

Las propiedades que podemos utilizar son:

• device.cordova: Obtiene la versión de PhoneGap.

• device.model: Obtiene el nombre o modelo del dispositivo.

• device.platform: Obtiene el nombre del sistema operativo.

• device.uuid: Devuelve el Universally Unique Identifier (UUID) del dispositivo.

• device.version: Obtiene la versión del sistema operativo utilizado.

Para más información podéis consultar la siguiente página:

http://plugins.cordova.io/#/package/org.apache.cordova.device

Información sobre la conexión (cordova-plugin-network-information)

Este plugin proporciona información sobre el tipo de conexión a la red y además añade eventos para saber cuando el dispositivo se conecta o se desconecta de la red.

Para obtener información sobre el tipo de conexión utilizamos el objeto connection.type el cual podrá contener los siguientes valores:

• Connection.UNKNOWN

• Connection.ETHERNET

• Connection.WIFI

• Connection.CELL_2G

• Connection.CELL_3G

• Connection.CELL_4G

• Connection.CELL

• Connection.NONE

A continuación se incluye un ejemplo de uso:

function checkConnection() {
    var networkState = navigator.connection.type;

    var states = {};
    states[Connection.UNKNOWN]  = 'Tipo de conexión desconocida';
    states[Connection.ETHERNET] = 'Ethernet';
    states[Connection.WIFI]     = 'WiFi';
    states[Connection.CELL_2G]  = 'Cell 2G';
    states[Connection.CELL_3G]  = 'Cell 3G';
    states[Connection.CELL_4G]  = 'Cell 4G';
    states[Connection.CELL]     = 'Cell generic';
    states[Connection.NONE]     = 'Sin conexión';

    alert('Tipo de conexión: ' + states[networkState]);
}

checkConnection();

Para escuchar a los eventos de online y offline, igual que para el resto de eventos, simplemente tendremos que hacer:

document.addEventListener("online", onOnline, false);
document.addEventListener("offline", onOffline, false);

function onOnline() {
    // Se ha conectado a la red
}

function onOffline() {
    // Se ha perdido la conexión a la red
}

Brújula (cordova-plugin-device-orientation)

Este plugin proporciona el acceso a la brújula, el cual devuelve la orientación del dispositivo con respecto al norte como si de una brújula se tratase. El valor retornado estará en grados entre 0 y 359.99.

Una vez haya cargado la API de PhoneGap podremos utilizar los siguientes métodos:

• navigator.compass.getCurrentHeading

• navigator.compass.watchHeading

• navigator.compass.clearWatch

Para obtener el valor actual utilizamos el método navigator.compass.getCurrentHeading, el cual puede devolver la orientación o un error en caso de no pode acceder. A continuación se incluye un ejemplo de uso:

function onSuccess(heading) {
    alert('Orientación: ' + heading.magneticHeading + 'º');
};

function onError(error) {
    alert('Compass Error: ' + error.code);
};

navigator.compass.getCurrentHeading(onSuccess, onError);

Pero este método solo devuelve un valor. Si queremos que el valor se actualice según se mueva el dispositivo tenemos que utilizar el método navigator.compass.watchHeading. Este método llamará a la función "success" cada vez que obtenga la orientación con la frecuencia que se indique en las opciones, por ejemplo:

function onSuccess(heading) {
    var element = document.getElementById('heading');
    element.innerHTML = 'Orientacion: ' + heading.magneticHeading;
};

function onError(compassError) {
    alert('Compass error: ' + compassError.code);
};

var options = {
    frequency: 3000
}; // actualizar cada 3 segundos

var watchID = navigator.compass.watchHeading(onSuccess, onError, options);

El valor de retorno de esta función (watchID) nos permite detener el listener cuando queramos mediante la función:

navigator.compass.clearWatch(watchID);

Este plugin tiene un funcionamiento muy similar al del acelerómetro o al de la geolocalización, todos disponen un método para obtener el valor actual y métodos para obtener los valores en tiempo real (con una determinada frecuencia) y para detener el listener.