# 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*) <a href="#informacion-del-dispositivo-cordova-plugin-device" id="informacion-del-dispositivo-cordova-plugin-device"></a>

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:

```javascript
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*) <a href="#informacion-sobre-la-conexion-cordova-plugin-network-information" id="informacion-sobre-la-conexion-cordova-plugin-network-information"></a>

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:

```javascript
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:

```javascript
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*) <a href="#brujula-cordova-plugin-device-orientation" id="brujula-cordova-plugin-device-orientation"></a>

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.&#x20;
* `navigator.compass.watchHeading`: Crea un listener para obtener la orientación con una determinada frecuencia.&#x20;
* `navigator.compass.clearWatch`: Nos permite detener un listener creado.&#x20;

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:

```javascript
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:

```javascript
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:

```javascript
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.