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

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

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

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