Uso de la API de Cordova

A continuación vamos a ver algunos ejemplos de uso de los plugins más utilizados.

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

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

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

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

Las propiedades que podemos utilizar son:

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

• 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:

https://www.npmjs.com/package/cordova-plugin-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 cuándo 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 indicando el tipo de conexión:

• 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
}

Para más información podéis consultar: https://www.npmjs.com/package/cordova-plugin-network-information

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 los valores 0 y 359.99.

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

• navigator.compass.getCurrentHeading: Devuelve la orientación actual del dispositivo.

• navigator.compass.watchHeading: Crea un listener para obtener la orientación con una determinada frecuencia.

• navigator.compass.clearWatch: Nos permite detener un listener creado.

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.