Le APIs di geolocalizzazione non sono tecnicamente parte delle specifiche HTML5, sono descritte in un documento separato (che trovate qui)che riporta come "incipit": "le APIs definiscono un’interfaccia di alto livello allo scopo di fornire, tramite script, accesso alle informazioni relative alla posizione geografica associata ad un device (dispositivo)".
Per dispositivo si intende un cellulare, un tablet, laptop ospitante l’applicazione richiedente le informazioni.
Attualmente esiste un draft datato ottobre 2011 che descrive le specifiche della versione 2, esplicitamente retrocompatibili con la versione 1.
Ho deciso di inserire le APIs in questa guida perchè fanno parte, a mio modo di vedere, di quello sforzo teso a dotare il Web di quegli strumenti di cui necessita per effettuare un ulteriore, importante passo avanti, in termini di funzionalità ed interattività.
N.B.: Nel processo di stesura delle specifiche è coinvolto solamente il W3C.
Introduzione
Le APIs sono agnostiche delle sottostanti sorgenti che forniscono la localizzazione: queste sorgenti tipicamente comprendono: GPS, dati ricavati dalla rete come l’IP del "chiamante", RFID, WiFi, celle telefoniche; esse non garantiscono in alcun modo che venga ritornata la posizione del dispositivo. Sono supportate sia richieste one-shot, sia richieste ripetute; è implementata la funzionalità di ricerca (query) sulle posizioni "cached" (precedentemente ricavate).
Le informazioni sulla localizzazione sono rappresentate nella forma di coordinate geografiche: longitudine e latitudine. Il documento indica che le informazioni così recuperate, potenzialmente lesive della privacy qualora fossero diffuse, vengano rese disponibili, in una implementazione conforme, esclusivamente dietro esplicito permesso dell’utente, espresso tramite una interfaccia (o ereditato da rapporti commerciali già vigenti tra le parti).
Le APIs
N.B.: Le APIs definiscono interfacce, le implementazioni sono a carico delle varie piattaforme.
Il meccanismo alla base del funzionamento delle API ruota intorno all’interfaccia Geolocation; definisce tre metodi, che analizziamo nel dettaglio.
getCurrentPosition
Signature
void getCurrentPosition(in PositionCallback successCallback,
in optional PositionErrorCallback errorCallback,
in optional PositionOptions options);Descrizione
Il metodo accetta da uno fino a tre parametri in entrata; quando viene invocato deve immediatamente "ritornare" (ripassare il controllo al chiamante) e successivamente tentare in modalità asincrona di ottenere la posizione attuale del dispositivo. Quando il tentativo di recupero approda a buon fine deve essere invocata la funzione di callback legata a questo evento (la handleEvent dell’oggetto successCallback) con un nuovo oggetto Position contenente la localizzazione del dispositivo, altrimenti il controllo deve passare all’oggetto errorCallback con un oggetto PositionError che descriva le cause del fallimento della richiesta.
watchPosition
Signature
long watchPosition(in PositionCallback successCallback,
in optional PositionErrorCallback errorCallback,
in optional PositionOptions options);Descrizione
Il metodo watchPosition accetta da uno a tre parametri. Quando chiamato deve immediatamente ritornare un numero (di tipo long) che identifichi univocamente una operazione di watch/monitoraggio (un watchID) e poi iniziare asincronicamente l’operazione stessa.
Il flusso di funzionamento dell’operazione con la chiamata a successCallback/errorCallback procede in modo identico a quanto avviene per getCurrentPosition. L’operazione di monitoraggio della posizione del dispositivo deve poi continuare ed invocare l’appropiato callback ogniqualvolta la posizione muti o comunque finchè non intervenga una invocazione al metodo clearWatch (utilizzando come chiave il watchID).
clearWatch
Signature
void clearWatch(in long watchId);Descrizione
Il metodo clearWatch accetta in input un argomento, l’identifier del monitoraggio attualmente in corso (generato da watchPosition). Qualora il watchID non corrispondesse a nessuno di quelli attesi relativi a processi in corso il metodo deve ripassare immediatamente il controllo al chiamante. Laddove invece l’identificatore fosse riconosciuto il processo ad esso relativo dovrebbe essere immadiatamente fermato senza richiamare alcun callback.
È importante notare che nel caso in cui l’utente non acconsentisse a rivelare la propria posizione i metodi getCurrentPosition e watchPosition chiamerebbero immediatamente la errorCallback passando come error code PERMISSION_DENIED.
L’interfaccia PositionOptions
getCurrentPosition e watchPosition prevedono come terzo parametro opzionale un oggetto PositionOptions: vediamolo più da vicino:
interface PositionOptions {
attribute boolean enableHighAccuracy;
attribute long timeout;
attribute long maximumAge;
attribute boolean requireCoords;
attribute boolean requestAddress;
};Analizziamone gli attributes:
enableHighAccuracy
Fornisce l’indicazione che l’applicazione si attende il massimo risultato in termini di precisione; la richiesta implica un possibile rallentamente nei tempi della risposta oppure un consumo più elevato di risorse (batterie ad esempio).
L’utente potrebbe anche "disabilitare" questa possibilità o equivalentemente il dispositivo potrebbe non essere in grado di ottenere dati più accurati rispetto ad una richiesta con l’attributo non specificato.
Lo scopo reale dell’attributo è quindi pensato al contrario (enableHighAccuracy = false o attributo assente), informare l’implementazione che non è richiesta nessuna particolare precisione, in modo che siano risparmiati tempi di attesa e batterie.
timeout
L’attributo definisce la massima latenza accettata (in millisecondi) entro cui getCurrentPosition e watchPosition passino il controllo ai relativi successCallback. Nel caso in cui questo tempo di attesa superi quello indicato verrà chiamata in causa la errorCallback passando un parametro PositionError il cui attributo error sarà valorizzato a TIMEOUT. Il tempo speso in attesa del permesso dell’utente non rientra nel computo totale del timeout. Il valore di default per l’attributo è Infinity.
maximumAge
Indica che l’applicazione accetta posizioni cached non più vecchie del valore definito (in millisecondi). Quando il valore è 0 oppure non esistono posizione precedentemente ricavate verrà immediatamente cercata una nuova posizione. Nel caso invece valesse Infinity l’implementazione restituirebbe una cached position senza valutarne il tempo di acquisizione. Attenzione: per watchPosition il valore temporale è calcolato sulla prima posizione ricavata (prima chiamata).
requireCoords
Comunica allo user agent che qualora non fosse possibile recuperare le informazioni per gli attributi Position.coords.latitude, Position.coords.longitude e Position.coords.accuracy la chiamata dovrebbe essere considerata fallita ed errorCallback dovrebbe essere invocato. Se settato a true (default) l’applicazione deve garantire che i suddetti attributi siano valorizzati (non nulli).
requestAddress
L’attributo indica che l’applicazione vorrebbe ricevere un indirizzo. Lo scopo è di evitare che questa informazione, costosa dal punto di vista dei tempi di recupero venga inutilmente cercata quando non richiesta (requestAddress = false o assente). Laddove l’attributo valesse true e l’indirizzo non fosse trovato la richiesta non dovrebbe comunque essere considerata fallita.
