Geolocalización

Este plugin ofrece información sobre la localización del dispositivo, así como la latitud y la longitud. Las fuentes de información incluyen el sistema GPS y la localización referencia da por las señales de red como las direcciones IP, RFID, WiFi y Bluetooth. Esto no garantiza que la API lance la localización actual del dispositivo.

Esto supone un importante riesgo para la privacidad. Las aplicaciones que vulneren la privacidad deberían avisar del riesgo del uso, ya que se compartirían datos de localización con terceros. Además del aviso de que los datos podrían no ser siempre correctos. Por eso es necesario que la aplicación requiera el permiso del usuario (por ejemplo desde un cuadro de diálogo con OK y No, gracias)

org.apache.cordova.geolocation

Instalación

cordova plugin add org.apache.cordova.geolocation

Plataformas soportadas

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • Firefox OS
  • iOS
  • Tizen
  • Windows Phone 7 y 8
  • Windows 8

Métodos

  • navigator.geolocation.getCurrentPosition
  • navigator.geolocation.watchPosition
  • navigator.geolocation.clearWatch

Objetos (Solo lectura)

  • Position
  • PositionError
  • Coordinates

Métodos

navigator.geolocation.getCurrentPosition

Devuelve la actual posición del dispositivo a la llamada geolocationSuccess con un objeto Position como parámetro. Si hay algún error, la llamada geolocationError pasaría un objeto PositionError.

navigator.geolocation.getCurrentPosition(geolocationSuccess,
                                         [geolocationError],
                                         [geolocationOptions]);

Parámetros

  • geolocationSuccess: Devuelve la actual posición en caso positivo.
  • geolocationError: (Opcional) Ejecuta la respuesta al ocurrir un error.
  • geolocationOptions: (Opcional) Opciones de geolocalización.

navigator.geolocation.watchPosition

Devuelve la posición actual del dispositivo cuando se ha detectado algún cambio. Cuando el dispositivo recibe una nueva localización, la respuesta de geolocationSuccess se ejecuta con un objeto Position como parámetro. Si hay un error, la respuesta geolocationError se ejecuta con un objeto PositionError como parámetro.

var watchId = navigator.geolocation.watchPosition(geolocationSuccess,
                                                  [geolocationError],
                                                  [geolocationOptions]);

Parámetros

  • geolocationSuccess: La respuesta que devuelve la posición actual.
  • geolocationError: (Opcional) Ejecuta la respuesta al ocurrir un error.
  • geolocationOptions: (Opcional) Opciones de geolocalización.
  • String: devuelve un ID que referencia al intervalo de la posición. La ID debería ser usada con navigator.geolocation.clearWatch para detener la visualización de los cambios de posición.
  • enableHighAccuracy: Facilita las pautas que la aplicación necesita para ofrecer mejores resultados. Por defecto, el dispositivo intenta devolver una Position sirviéndose de métodos basados en la red. Modificando esta propiedad a true le decimos al framework que use métodos precisos, como el posicionamiento por satélite.
  • timeout: La máxima longitud de tiempo (milisegundos) que se permiten desde navigator.geolocation.getCurrentPosition o geolocation.watchPosition hasta que se ejecute la llamada geolocationSuccess. Si la llamada a geolocationSuccess no se invoca a tiempo, se le pasa a geolocationError el código del error  PositionError.TIMEOUT. (Number)
  • maximumAge: Acepta una posición que no haya durado el tiempo especificado en milisegundos. (Number)

Returns

  • string: devuelve un ID que referencia al intervalo de la posición. La ID debería ser usada con navigator.geolocation.clearWatch para detener la visualización de los cambios de posición.

Opciones

  • enableHighAccuracy: Facilita las pautas que la aplicación necesita para ofrecer mejores resultados. Por defecto, el dispositivo intenta devolver una Position sirviéndose de métodos basados en la red. Modificando esta propiedad a true le decimos al framework que use métodos precisos, como el posicionamiento por satélite.
  • timeout: La máxima longitud de tiempo (milisegundos) que se permiten desde navigator.geolocation.getCurrentPosition o geolocation.watchPosition hasta que se ejecute la llamada geolocationSuccess. Si la llamada a geolocationSuccess no se invoca a tiempo, se le pasa a geolocationError el código del error  PositionError.TIMEOUT. (Number)
  • maximumAge: Acepta una posición que no haya durado el tiempo especificado en milisegundos. (Number)

navigator.geolocation.clearWatch

Detiene el visionado de los cambios producidos por el dispositivo referenciados por el parámetro watchID.

navigator.geolocation.clearWatch(watchID);

Parámetros

  • watchID: El ID del intervalo watchPosition a limpiar. (String)

Objetos

Position

Contiene las coordenadas Position y el momento actual, creado por la API de geolocalización.

Propiedades

  • coords: Conjunto de coordenadas geográficas. (Coordinates)
  • timestamp: Crea un instante para las coords. (Date)

Coordinates

Un objeto Coordinates se envía al objeto Position que es el encargado de devolver a la funciones que devuelven la posición actual. Contiene un conjunto de propiedades que describen las coordenadas geográficas de una posición.

Propiedades

  • latitude: Latitudes en grados decimales. (Number)
  • longitude: Longitud en grados decimales. (Number)
  • altitude: Altura en metros respecto al nivel del mar. (Number)
  • accuracy: Nivel de exactitud de las coordenadas de latitud y longitud en metros. (Number)
  • altitudeAccuracy: Nivel de exactitud de las coordenadas de la altitud en metros. (Number)
  • heading: Dirección, especificada en grados que apunta al verdadero norte. (Number)
  • speed: Velocidad actual del dispositivo, especificado en metros por segundo. (Number)

NOTA: heading marcará siempre null cuando la velocidad devuelta sea siempre 0, o el dispositivo está detenido.

PositionError

El objeto PositionError se pasa a la función geolocationError cuando ocurre un error con navigator.geolocation.

Propiedades

  • code: Uno de los errores predefinidos listados a continuación.
  • message: Mensaje de error que describe con detalle el error encontrado.

Constantes

  • PositionError.PERMISSION_DENIED
    • Se devuelve cuando el usuario no permite que la aplicación recoja información sobre la posición. Es dependiente de la plataforma.
  • PositionError.POSITION_UNAVAILABLE
    • Se devuelve cuando el dispositivo es incapaz de recibir una posición. En general, significa que el dispositivo no está conectado a la red o no tiene soporte vía satélite.
  • PositionError.TIMEOUT
    • Se devuelve cuando el dispositivo es incapaz de recibir una posición dentro del tiempo especificado por timeout incluido en geolocationOptions