Using geolocation

O Firefox 3.5 e versões superiores o Geolocation API, o qual permite que o usuário forneça sua localização para aplicações web, se assim o desejar. Por razões de privacidade, o usuário é solicitado a confirmar a permissão para relatar informações de localização.

O Firefox 3.5 inclui suporte para localizá-lo com base nas informações da sua rede Wi-Fi usando o Serviço Localização da Google (Google Location Services). Na comunicação entre o Firefox 3.5 e Google, os dados são trocados incluindo dados de acesso do Acess Point WiFi , um código token de acesso (semelhante a um cookie de duas semanas) e o endereço de IP do usuário. Para mais informações, por favor consulte a Politica de Provacidade da Mozilla e Politica de Privacidade da Google que cobrem como estes dados podem ser utilizados. Veja também o codigo fonte se você está curioso como este serviço é implementado.

Note: If your interest is in writing a geolocation provider -- a service which can be queried for the user's location -- please see nsIGeolocationProvider.  You may also find the WiFi access point monitoring service interesting.

O Firefox 3.6 (Gecko 1.9.2) adicionou suporte usando o GPSD (GPS daemon) serviço de Geolocalização do Linux.

Note: Extensions hosted on addons.mozilla.org must explicitly request permission before accessing geolocation data.

O objeto geolocation

O aplicativo de geolocalização é utilizado através de um objeto filho chamado geolocation localizado dentro do objeto navigator.  Se o objeto existe, os serviços de geolocalização estarão disponíveis. Você pode adicionalmente testar a presença da geolocalização:

if ("geolocation" in navigator) {
  /* geolocation is available */
} else {
  alert("I'm sorry, but geolocation services are not supported by your browser.");
}

Ao iniciar no Gecko 1.9.2 (Firefox 3.6), add-ons podem obter o objeto de geolocalização obtendo a referência para o serviço de geolocaliazação como se ve a seguir:

var geolocation = Components.classes["@mozilla.org/geolocation;1"]
                            .getService(Components.interfaces.nsIDOMGeoGeolocation);

Obtendo a posição atual

Para obter a localização atual do usuário, você pode utiliza o método getCurrentPosition().  Isto inicia uma requisição assíncrona para identificar a posição do usuário, e consulta ohardware de localizaçãopara conseguir informações atualizadas. Quando a posição é determinada, uma rotina específica de retorno é executada. Você pode opcionalmente gerar uma segunda rotina de retorno se um erro ocorrer.  Um terceiro, e opcional, parâmetro é a interface "opções" onde você pode configurar o tempo máximo da posição recebida e o tempo a se esperar por uma solicitação.

Use getCurrentPosition() se você deseja uma única posição rapidamente, independente da precisão.  Dispositivos com GPS, por exemplo, podem levar um minuto ou mais para conseguir a localização, e portanto dados menos precisos (localizxação do IP location ou rede wifi) podem retornar do método getCurrentPosition().

navigator.geolocation.getCurrentPosition(function(position) {
  do_something(position.coords.latitude, position.coords.longitude);
});

O exemplo acima irá fazer a função the do_something() executar quando a localização for obtida.

Verificando a posição atual

Se os dados de posição mudam (sejam pelo movimento do dispositivo ou se uma informação mais precisa for recebida), se pode configurar um retorno que é feito com esta informação de posição atual. Isto é feito usando a função watchPosition(), a qual tem os mesmos parâmetros de entrada da função getCurrentPosition(). Seu retorno é chamada múltiplas vezes, permitindo que o navegador ou atualize sua posição enquanto você se move, ou forneça uma localização mais precisa enquanto diferentes técnicas são usadas para localizar sua posição. O erro do retorno, o qual é opcional assim como no getCurrentPosition(), é chamado uma única vez, se nenhum resultado válido retornar.

watchPosition() pode ser usado sem que não haja a chamada inicial de getCurrentPosition().

var watchID = navigator.geolocation.watchPosition(function(position) {
  do_something(position.coords.latitude, position.coords.longitude);
}
);

The watchPosition() method returns an ID number that can be used to uniquely identify the requested position watcher; you use this value in tandem with the clearWatch() method to stop watching the user's location.

navigator.geolocation.clearWatch(watchID);

watchPosition() accepts a success callback and error callback (like getCurrentPosition) and an optional positionObjects object, which can have three properties:

  • enableHighAccuracy – A boolean which indicates to the device that you wish to obtain it’s most accurate readings (this parameter may or may not make a difference, depending on your hardware)
  • maximumAge – The maximum age (in milliseconds) of the reading (this is appropriate as the device may cache readings to save power and/or bandwidth)
  • timeout – The maximum time (in milliseconds) for which you are prepared to allow the device to try to obtain a Geo location

A call to watchPosition could look like:

var wpid = navigator.geolocation.watchPosition(geo_success, geo_error, {enableHighAccuracy:true, maximumAge:30000, timeout:27000});

A demo of watchPosition in use: http://www.thedotproduct.org/experiments/geo/


Describing a position

The user's location is described using a Position object, which has the following fields:

timestamp
The time at which the reading was taken, as a DOMTimeStamp.
coords
An nsIDOMGeoPositionCoords object indicating the location.
address Obsolete since Gecko 14.0
An nsIDOMGeoPositionAddress object specifying the corresponding address, if available.

Handling errors

The error callback, if provided when calling getCurrentPosition() or watchPosition(), has the following signature:

function errorCallback(PositionError error);

The PositionError structure has the following fields:

code
A numeric error code which much be one of the following:
UNKNOWN_ERROR (numeric value 0)
The location acquisition process failed due to an error not covered by the definition of any other error code in this interface.
PERMISSION_DENIED (numeric value 1)
The location acquisition process failed because the application origin does not have permission to use the Geolocation API.
POSITION_UNAVAILABLE (numeric value 2)
The position of the device could not be determined. One or more of the location providers used in the location acquisition process reported an internal error that caused the process to fail entirely.
TIMEOUT (numeric value 3)
The specified maximum length of time has elapsed before the implementation could successfully acquire a new Position object.
 
message
A human readable error message, suitable for use in logs and debugging -- but not for display to the user.

Browser compatibility

Browser Basic support Geolocation Level 2
Internet Explorer IE9 RC ---
Firefox (Gecko) 3.5 (1.9.1) ---
Opera 10.60 ---
Safari | Chrome | WebKit 5 | 5 | 533 ---

Prompting for permission

Any add-on hosted on addons.mozilla.org which makes use of geolocation data must explicitly request permission before doing so. The following function will request permission in a manner similar to the automatic prompt displayed for web pages. The user's response will be saved in the preference specified by the pref parameter, if applicable. The function provided in the callback parameter will be called with a boolean value indicating the user's response. If true, the add-on may access geolocation data.

function prompt(window, pref, message, callback) {
    let branch = Components.classes["@mozilla.org/preferences-service;1"]
                           .getService(Components.interfaces.nsIPrefBranch);

    if (branch.getPrefType(pref) === branch.PREF_STRING) {
        switch (branch.getCharPref(pref)) {
        case "always":
            return callback(true);
        case "never":
            return callback(false);
        }
    }

    let done = false;

    function remember(value, result) {
        return function() {
            done = true;
            branch.setCharPref(pref, value);
            callback(result);
        }
    }

    let self = window.PopupNotifications.show(
        window.gBrowser.selectedBrowser,
        "geolocation",
        message,
        "geo-notification-icon",
        {
            label: "Share Location",
            accessKey: "S",
            callback: function(notification) {
                done = true;
                callback(true);
            }
        }, [
            {
                label: "Always Share",
                accessKey: "A",
                callback: remember("always", true)
            },
            {
                label: "Never Share",
                accessKey: "N",
                callback: remember("never", false)
            }
        ], {
            eventCallback: function(event) {
                if (event === "dismissed") {
                    if (!done) callback(false);
                    done = true;
                    window.PopupNotifications.remove(self);
                }
            },
            persistWhileVisible: true
        });
}

prompt(window,
       "extensions.foo-addon.allowGeolocation",
       "Foo Add-on wants to know your location.",
       function callback(allowed) { alert(allowed); });

See also

Document Tags and Contributors

Etiquetas:
Contributors to this page: ronaldo.ap.abreu, emilianocarvalho
Última atualização por: ronaldo.ap.abreu,