Geolocalizzazione

Il geolocation oggetto fornisce accesso ai dati di localizzazione basato su sensore GPS del dispositivo o dedotto dai segnali di rete.

Geolocationfornisce informazioni sulla posizione del dispositivo, come latitudine e longitudine. Comuni fonti di informazioni sulla posizione comprendono Global Positioning System (GPS) e posizione dedotta dai segnali di rete come indirizzo IP, indirizzi, RFID, WiFi e Bluetooth MAC e cellulare GSM/CDMA IDs. Non non c'è alcuna garanzia che l'API restituisce la posizione effettiva del dispositivo.

Questa API è basata sulla Specifica di W3C Geolocation APIe viene eseguito solo su dispositivi che non già forniscono un'implementazione.

Nota importante sulla privacy: Raccolta e utilizzo dei dati di geolocalizzazione solleva questioni di privacy importante. Politica sulla privacy dell'app dovrebbe discutere come app utilizza dati di geolocalizzazione, se è condiviso con altre parti e il livello di precisione dei dati (ad esempio, Cap grossolana, fine, livello, ecc.). Dati di geolocalizzazione sono generalmente considerati sensibili perché può rivelare la sorte di una persona e, se conservati, la storia dei suoi viaggi. Pertanto, oltre alla politica di privacy dell'app, è fortemente consigliabile fornendo un preavviso di just-in-time prima della tua app di accedere ai dati di geolocalizzazione (se il sistema operativo del dispositivo non farlo già). Tale comunicazione deve fornire le informazioni stesse notate sopra, oltre ad ottenere l'autorizzazione (ad esempio, presentando scelte per OK e No grazie). Per ulteriori informazioni, vedere la guida sulla Privacy.

Metodi

Argomenti

Oggetti (sola lettura)

Position
PositionError
Coordinates

La funzionalità di accesso

A partire dalla versione 3.0, Cordova implementa le API a livello di dispositivo come plugin. Utilizzare la CLI plugin comando, descritto in Command-Line Interface, aggiungere o rimuovere questa funzionalità per un progetto:

    $ cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-geolocation.git
    $ cordova plugin rm org.apache.cordova.core.geolocation

Questi comandi si applicano a tutte le piattaforme mirate, ma modificano le impostazioni di configurazione specifiche della piattaforma descritte di seguito:

Android

(in app/res/xml/config.xml)
<feature name="Geolocation">
    <param name="android-package" value="org.apache.cordova.GeoBroker" />
</feature>


(in app/AndroidManifest.xml)
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_LOCATION_EXTRA_COMMANDS" />

BlackBerry WebWorks

(in www/plugins.xml)
<feature name="Geolocation">
    <param name="blackberry-package" value="org.apache.cordova.geolocation.Geolocation" />
</feature>


(in www/config.xml)
<rim:permissions>
    <rim:permit>read_geolocation</rim:permit>
</rim:permissions>

iOS (inconfig.xml)

<feature name="Geolocation">
    <param name="ios-package" value="CDVLocation" />
</feature>

Windows Phone (inProperties/WPAppManifest.xml)
```
<Capabilities>
    <Capability Name="ID_CAP_LOCATION" />
</Capabilities>
```
Riferimento: il manifesto dell'applicazione per Windows Phone

Alcune piattaforme possono supportare questa funzionalità senza richiedere alcuna configurazione speciale. Per una panoramica, vedere supporto della piattaforma.

geolocation.getCurrentPosition

Restituisce la posizione corrente del dispositivo come un Position oggetto.

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

Parametri

geolocationSuccess: il callback passato alla posizione corrente.
geolocationError: (facoltativo) il callback che viene eseguito se si verifica un errore.
geolocationOptions: (opzionale) le opzioni di geolocalizzazione.

Descrizione

geolocation.getCurrentPositionè una funzione asincrona. Restituisce la posizione corrente del dispositivo per la geolocationSuccess callback con un Position oggetto come parametro. Se c'è un errore, il geolocationError callback viene passata una PositionError oggetto.

Piattaforme supportate

Android
BlackBerry WebWorks (OS 5.0 e superiori)
iOS
Tizen
Windows Phone 7 e 8
Windows 8

Esempio rapido

// onSuccess Callback
// This method accepts a Position object, which contains the
// current GPS coordinates
//
var onSuccess = function(position) {
    alert('Latitude: '          + position.coords.latitude          + '\n' +
          'Longitude: '         + position.coords.longitude         + '\n' +
          'Altitude: '          + position.coords.altitude          + '\n' +
          'Accuracy: '          + position.coords.accuracy          + '\n' +
          'Altitude Accuracy: ' + position.coords.altitudeAccuracy  + '\n' +
          'Heading: '           + position.coords.heading           + '\n' +
          'Speed: '             + position.coords.speed             + '\n' +
          'Timestamp: '         + position.timestamp                + '\n');
};

// onError Callback receives a PositionError object
//
function onError(error) {
    alert('code: '    + error.code    + '\n' +
          'message: ' + error.message + '\n');
}

navigator.geolocation.getCurrentPosition(onSuccess, onError);

Esempio completo

<!DOCTYPE html>
<html>
  <head>
    <title>Device Properties Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // device APIs are available
    //
    function onDeviceReady() {
        navigator.geolocation.getCurrentPosition(onSuccess, onError);
    }

    // onSuccess Geolocation
    //
    function onSuccess(position) {
        var element = document.getElementById('geolocation');
        element.innerHTML = 'Latitude: '           + position.coords.latitude              + '<br />' +
                            'Longitude: '          + position.coords.longitude             + '<br />' +
                            'Altitude: '           + position.coords.altitude              + '<br />' +
                            'Accuracy: '           + position.coords.accuracy              + '<br />' +
                            'Altitude Accuracy: '  + position.coords.altitudeAccuracy      + '<br />' +
                            'Heading: '            + position.coords.heading               + '<br />' +
                            'Speed: '              + position.coords.speed                 + '<br />' +
                            'Timestamp: '          + position.timestamp                    + '<br />';
    }

    // onError Callback receives a PositionError object
    //
    function onError(error) {
        alert('code: '    + error.code    + '\n' +
              'message: ' + error.message + '\n');
    }

    </script>
  </head>
  <body>
    <p id="geolocation">Finding geolocation...</p>
  </body>
</html>

geolocation.watchPosition

Orologi per le modifiche alla posizione corrente del dispositivo.

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

Parametri

geolocationSuccess: il callback passato alla posizione corrente.
geolocationError: (facoltativo) il callback che viene eseguito se si verifica un errore.
geolocationOptions: opzioni (opzionale) la geolocalizzazione.

Restituisce

Stringa: restituisce un id di orologio che fa riferimento l'intervallo di posizione orologio. L'id dell'orologio deve essere usato con geolocation.clearWatch a smettere di guardare per cambiamenti di posizione.

Descrizione

geolocation.watchPositionè una funzione asincrona. Restituisce la posizione corrente del dispositivo quando viene rilevata una modifica della posizione. Quando il dispositivo recupera una nuova posizione, la geolocationSuccess callback viene eseguita con un Position oggetto come parametro. Se c'è un errore, il geolocationError callback viene eseguita con un PositionError oggetto come parametro.

Piattaforme supportate

Android
BlackBerry WebWorks (OS 5.0 e superiori)
iOS
Tizen
Windows Phone 7 e 8
Windows 8

Esempio rapido

// onSuccess Callback
//   This method accepts a `Position` object, which contains
//   the current GPS coordinates
//
function onSuccess(position) {
    var element = document.getElementById('geolocation');
    element.innerHTML = 'Latitude: '  + position.coords.latitude      + '<br />' +
                        'Longitude: ' + position.coords.longitude     + '<br />' +
                        '<hr />'      + element.innerHTML;
}

// onError Callback receives a PositionError object
//
function onError(error) {
    alert('code: '    + error.code    + '\n' +
          'message: ' + error.message + '\n');
}

// Options: throw an error if no update is received every 30 seconds.
//
var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { timeout: 30000 });

Esempio completo

<!DOCTYPE html>
<html>
  <head>
    <title>Device Properties Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    var watchID = null;

    // device APIs are available
    //
    function onDeviceReady() {
        // Throw an error if no update is received every 30 seconds
        var options = { timeout: 30000 };
        watchID = navigator.geolocation.watchPosition(onSuccess, onError, options);
    }

    // onSuccess Geolocation
    //
    function onSuccess(position) {
        var element = document.getElementById('geolocation');
        element.innerHTML = 'Latitude: '  + position.coords.latitude      + '<br />' +
                            'Longitude: ' + position.coords.longitude     + '<br />' +
                            '<hr />'      + element.innerHTML;
    }

        // onError Callback receives a PositionError object
        //
        function onError(error) {
            alert('code: '    + error.code    + '\n' +
                  'message: ' + error.message + '\n');
        }

    </script>
  </head>
  <body>
    <p id="geolocation">Watching geolocation...</p>
  </body>
</html>

geolocation.clearWatch

Smettere di guardare per le modifiche alla posizione del dispositivo a cui fa riferimento la watchID parametro.

navigator.geolocation.clearWatch(watchID);

Parametri

watchID: l'id del watchPosition intervallo per cancellare. (String)

Descrizione

Il geolocation.clearWatch si ferma a guardare i cambiamenti di posizione del dispositivo deselezionando il geolocation.watchPosition fanno riferimentowatchID.

Piattaforme supportate

Android
BlackBerry WebWorks (OS 5.0 e superiori)
iOS
Tizen
Windows Phone 7 e 8
Windows 8

Esempio rapido

/ / Opzioni: guardare per cambiamenti di posizione e utilizzare più / / preciso metodo di acquisizione disponibile position.
//
var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { enableHighAccuracy: true });

// ...later on...

navigator.geolocation.clearWatch(watchID);

Esempio completo

<!DOCTYPE html>
<html>
  <head>
    <title>Device Properties Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    var watchID = null;

    // device APIs are available
    //
    function onDeviceReady() {
        // Get the most accurate position updates available on the
        // device.
        var options = { enableHighAccuracy: true };
        watchID = navigator.geolocation.watchPosition(onSuccess, onError, options);
    }

    // onSuccess Geolocation
    //
    function onSuccess(position) {
        var element = document.getElementById('geolocation');
        element.innerHTML = 'Latitude: '  + position.coords.latitude      + '<br />' +
                            'Longitude: ' + position.coords.longitude     + '<br />' +
                            '<hr />'      + element.innerHTML;
    }

    // clear the watch that was started earlier
    //
    function clearWatch() {
        if (watchID != null) {
            navigator.geolocation.clearWatch(watchID);
            watchID = null;
        }
    }

        // onError Callback receives a PositionError object
        //
        function onError(error) {
          alert('code: '    + error.code    + '\n' +
                'message: ' + error.message + '\n');
        }

    </script>
  </head>
  <body>
    <p id="geolocation">Watching geolocation...</p>
        <button onclick="clearWatch();">Clear Watch</button>
  </body>
</html>

Coordinate

Un insieme di proprietà che descrivono le coordinate geografiche di una posizione.

Proprietà

latitudine: latitudine in gradi decimali. (Numero)
longitudine: longitudine in gradi decimali. (Numero)
altitudine: altezza della posizione in metri sopra l'ellissoide. (Numero)
accuratezza: livello di accuratezza delle coordinate latitudine e longitudine in metri. (Numero)
altitudeAccuracy: livello di accuratezza della coordinata altitudine in metri. (Numero)
rubrica: senso di marcia, specificata in gradi in senso orario rispetto al vero nord di conteggio. (Numero)
velocità: velocità attuale terra del dispositivo, specificato in metri al secondo. (Numero)

Descrizione

Il Coordinates oggetto è associato al Position oggetto disponibile per le funzioni di callback in richieste per la posizione corrente.

Piattaforme supportate

Android
BlackBerry WebWorks (OS 5.0 e superiori)
iOS
Tizen
Windows Phone 7 e 8
Windows 8

Esempio rapido

// onSuccess Callback
//
var onSuccess = function(position) {
    alert('Latitude: '          + position.coords.latitude          + '\n' +
          'Longitude: '         + position.coords.longitude         + '\n' +
          'Altitude: '          + position.coords.altitude          + '\n' +
          'Accuracy: '          + position.coords.accuracy          + '\n' +
          'Altitude Accuracy: ' + position.coords.altitudeAccuracy  + '\n' +
          'Heading: '           + position.coords.heading           + '\n' +
          'Speed: '             + position.coords.speed             + '\n' +
          'Timestamp: '         + position.timestamp                + '\n');
};

// onError Callback
//
var onError = function() {
    alert('onError!');
};

navigator.geolocation.getCurrentPosition(onSuccess, onError);

Esempio completo

<!DOCTYPE html>
<html>
  <head>
    <title>Geolocation Position Example</title>
    <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
    <script type="text/javascript" charset="utf-8">

    // wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // device APIs are available
    //
    function onDeviceReady() {
        navigator.geolocation.getCurrentPosition(onSuccess, onError);
    }

    // Display `Position` properties from the geolocation
    //
    function onSuccess(position) {
        var div = document.getElementById('myDiv');

        div.innerHTML = 'Latitude: '             + position.coords.latitude         + '<br/>' +
                        'Longitude: '            + position.coords.longitude        + '<br/>' +
                        'Altitude: '             + position.coords.altitude         + '<br/>' +
                        'Accuracy: '             + position.coords.accuracy         + '<br/>' +
                        'Altitude Accuracy: '    + position.coords.altitudeAccuracy + '<br/>' +
                        'Heading: '              + position.coords.heading          + '<br/>' +
                        'Speed: '                + position.coords.speed            + '<br/>';
    }

    // Show an alert if there is a problem getting the geolocation
    //
    function onError() {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <div id="myDiv"></div>
  </body>
</html>

Stranezze Android

altitudeAccuracy: non supportato dai dispositivi Android, restituendonull.

Posizione

Contiene Position coordinate e timestamp, creato da geolocation API.

Proprietà

CoOrds: un insieme di coordinate geografiche. (Coordinate)
timestamp: timestamp di creazione per coords . (Data)

Descrizione

Il Position oggetto viene creato e popolato di Cordova e restituito all'utente tramite una funzione di callback.

Piattaforme supportate

Android
BlackBerry WebWorks (OS 5.0 e superiori)
iOS
Tizen
Windows Phone 7 e 8
Windows 8

Esempio rapido

// onSuccess Callback
//
var onSuccess = function(position) {
    alert('Latitude: '          + position.coords.latitude          + '\n' +
          'Longitude: '         + position.coords.longitude         + '\n' +
          'Altitude: '          + position.coords.altitude          + '\n' +
          'Accuracy: '          + position.coords.accuracy          + '\n' +
          'Altitude Accuracy: ' + position.coords.altitudeAccuracy  + '\n' +
          'Heading: '           + position.coords.heading           + '\n' +
          'Speed: '             + position.coords.speed             + '\n' +
          'Timestamp: '         + position.timestamp                + '\n');
};

// onError Callback receives a PositionError object
//
function onError(error) {
    alert('code: '    + error.code    + '\n' +
          'message: ' + error.message + '\n');
}

navigator.geolocation.getCurrentPosition(onSuccess, onError);

Esempio completo

<!DOCTYPE html>
<html>
  <head>
    <title>Device Properties Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // device APIs are available
    //
    function onDeviceReady() {
        navigator.geolocation.getCurrentPosition(onSuccess, onError);
    }

    // onSuccess Geolocation
    //
    function onSuccess(position) {
        var element = document.getElementById('geolocation');
        element.innerHTML = 'Latitude: '          + position.coords.latitude         + '<br />' +
                            'Longitude: '         + position.coords.longitude        + '<br />' +
                            'Altitude: '          + position.coords.altitude         + '<br />' +
                            'Accuracy: '          + position.coords.accuracy         + '<br />' +
                            'Altitude Accuracy: ' + position.coords.altitudeAccuracy + '<br />' +
                            'Heading: '           + position.coords.heading          + '<br />' +
                            'Speed: '             + position.coords.speed            + '<br />' +
                            'Timestamp: '         + position.timestamp               + '<br />';
    }

        // onError Callback receives a PositionError object
        //
        function onError(error) {
            alert('code: '    + error.code    + '\n' +
                  'message: ' + error.message + '\n');
        }

    </script>
  </head>
  <body>
    <p id="geolocation">Finding geolocation...</p>
  </body>
</html>

PositionError

A PositionError oggetto è passato per la geolocationError callback quando si verifica un errore.

Proprietà

codice: uno dei codici di errore predefiniti elencati di seguito.
messaggio: messaggio di errore che descrive i dettagli dell'errore rilevato.

Costanti

PositionError.PERMISSION_DENIED
PositionError.POSITION_UNAVAILABLE
PositionError.TIMEOUT

Descrizione

Il PositionError oggetto è passato per la geolocationError funzione di callback quando si verifica un errore con geolocalizzazione.

`PositionError.PERMISSION_DENIED`

Restituito quando l'utente non consentono all'applicazione di recuperare le informazioni di posizione. Questo è dipendente dalla piattaforma.

`PositionError.POSITION_UNAVAILABLE`

Restituito quando il dispositivo è in grado di recuperare una posizione. In generale ciò significa che il dispositivo non dispone di rete connettività e/o non può ottenere un fix satellitare.

`PositionError.TIMEOUT`

Restituito quando il dispositivo è in grado di recuperare una posizione entro il tempo specificato nella geolocationOptions ' timeout proprietà. Quando utilizzato con geolocation.watchPosition , questo errore potrebbe essere passato alla geolocationError richiamata ogni timeout millisecondi.

geolocationSuccess

Funzione di callback dell'utente che viene eseguito quando una posizione di geolocalizzazione diventa disponibile (quando viene chiamato da geolocation.getCurrentPosition ), o quando si modifica la posizione (quando viene chiamato dageolocation.watchPosition).

function(position) {
    // Do something
}

Parametri

posizione: la posizione di geolocalizzazione restituita dal dispositivo. (Posizione)

Esempio

function geolocationSuccess(position) {
    alert('Latitude: '          + position.coords.latitude          + '\n' +
          'Longitude: '         + position.coords.longitude         + '\n' +
          'Altitude: '          + position.coords.altitude          + '\n' +
          'Accuracy: '          + position.coords.accuracy          + '\n' +
          'Altitude Accuracy: ' + position.coords.altitudeAccuracy  + '\n' +
          'Heading: '           + position.coords.heading           + '\n' +
          'Speed: '             + position.coords.speed             + '\n' +
          'Timestamp: '         + position.timestamp                + '\n');
}

geolocationError

Funzione di callback dell'utente che viene eseguito quando si verifica un errore per funzioni di geolocalizzazione.

function(error) {
    // Handle the error
}

Parametri

errore: l'errore restituito dal dispositivo. (PositionError)

geolocationOptions

Parametri opzionali per personalizzare il recupero di geolocalizzazionePosition.

{maximumAge: 3000, timeout: 5000, enableHighAccuracy: true};

Opzioni

enableHighAccuracy: fornisce un suggerimento che l'applicazione ha bisogno i migliori risultati possibili. Per impostazione predefinita, il dispositivo tenta di recuperare un Position usando metodi basati sulla rete. Impostando questa proprietà su true indica al framework di utilizzare metodi più accurati, come posizionamento satellitare. (Boolean)
timeout: la lunghezza massima di tempo (in millisecondi) che è consentito per passare dalla chiamata a geolocation.getCurrentPosition o geolocation.watchPosition fino a quando il corrispondente geolocationSuccess callback viene eseguito. Se il geolocationSuccess callback non viene richiamato entro questo tempo, il geolocationError callback viene passata una PositionError.TIMEOUT codice di errore. (Si noti che, quando utilizzato in combinazione con geolocation.watchPosition , il geolocationError callback potrebbe essere chiamato un intervallo ogni timeout millisecondi!) (Numero)
maximumAge: accettare una posizione memorizzata nella cache in cui età è minore il tempo specificato in millisecondi. (Numero)

Stranezze Android

Emulatori Android 2. x non restituiscono un risultato di geolocalizzazione a meno che il enableHighAccuracy opzione è impostata sutrue.

Geolocalizzazione

Guide

Riferimento API

PositionError.PERMISSION_DENIED

PositionError.POSITION_UNAVAILABLE

PositionError.TIMEOUT

`PositionError.PERMISSION_DENIED`

`PositionError.POSITION_UNAVAILABLE`

`PositionError.TIMEOUT`