Utiliser la Géolocalisation

Firefox 3.5 et supérieur supportent l'API de Géolocalisation. Elle permet aux utilisateurs de donner leur localisation si ils le désirent. Afin de respecter la vie privée, on demande à l'utilisateur si il veut bien donner sa localisation.

Firefox 3.5 se basait sur les informations de votre WiFi en utilisant Google Location Services. Dans la transaction entre Firefox 3.5 et Google, les données échangées sont les informations au sujet de la borne WiFi, un token d'accès (similaire à un cookie de deux semaines) et l'adresse IP de l'utilisateur  Pour plus d'information, voir les règles de respect de la vie privée de Mozilla et celles de Google concernant ces données et leurs utilisations possibles. Voir aussi le code source si vous êtes curieux du mode de fonctionnement de ce service.

Firefox 3.6 (Gecko 1.9.2) a ajouté le support du GPSD (GPS daemon) pour la géolocalisation sous Linux.

L'objet de Géolocalisation

L'API de Géolocalisation est publiée via l'enfant geolocation dans l'objet navigator. Si l'objet existe, l'utilisation du service de géolocalisation est possible. Vous pouvez tester via ce code :

if ("geolocation" in navigator) {
  /* géolocalisation possible */
} else {
  alert("Le service de géolocalisation n'est pas disponible sur votre ordinateur.");
}

Depuis Gecko 1.9.2 (Firefox 3.6), les add-ons peuvent obtenir l'objet géolocalisation en obtenant une référence dans le service de géolocalisation de cette façon :

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

Obtenir la position actuelle

Pour obtenir la position actuelle de l'utilisateur, vous pouvez appeler la méthode getCurrentPosition(). Celà initie une requête asynchrone pour détecter la position de l'utilisateur et demande au matériel de garder cette position actualisée. Quand cette position est déterminée, une routine spécialisée est éxécutée. Vous pouvez optionnellement appeler une deuxième routine dans le cas d'erreurs. Un troisième paramètre optionel est une option qui permet de définir l'âge maximum de la position et le temps d'attente pour une requête.

Utilisez getCurrentPosition() si vous voulez une position de façon ponctuel, quelque soit la précision. Les appareils avec un GPS, par exemple, peuvent prendre une minute ou plus pour donner une position. donc des données moins précise (localisation via l'IP ou le WiFI) peuvent être d'abord retournées a getCurrentPosition() pour commencer.

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

Cet exemple éxécute la fonction do_something() quand la localisation est obtenue.

Être notifié des changements de position

Afin d'être notifié d'un changement de position (dû à un déplacement géographique de la machine ou si une geolocalisation plus précise est disponible), vous pouvez enregistrer une fonction de rappel (callback) qui sera appellée avec des informations de géolocation mises à jour. Pour celà utilisez la fonction watchposition(), qui a les mêmes paramètres d'entrée que getCurrentPosition(). La fonction de rappel donnée sera appellée régulièrement, permattant au code appelant de mettre à jour la position en même temps que vous bougez ou de raffiner une information de position déjà connue. La fonction de rappel error est optionnelle (comme pour getCurrentPosition()) et ne sera appelée qu'une fois (éventuellement) si aucune position valide ne sera jamais fournie.

Vous pouvez utiliser watchPosition() sans appel préalable à getCurrentPosition().

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

La méthode watchPosition() retourn un nombre ID qui peut être utilisé pour identifier de manière unique le scrutateur de position;  Cette valeur est à utiliser en duo avec la méthode  clearWatch() qui stoppe le processus de scrutation.

navigator.geolocation.clearWatch(watchID);

watchPosition() accèpte deux fonctions de rappel : la première pour le cas de succès, l'uatre pour le cas d'erreur (comme getCurrentPosition) et un paramètre optionnel  positionObjects, qui peut avoir trois champs:

• enableHighAccuracy – Un booléen indicant au matériel que vous souhaitez les mesures les plus précise qu'il peut fournir (ce paramètre peut ne faire aucune différence, tout dépends du matériel)
• maximumAge – L'âge maximum (en millisecondes) de la mesure (La matériel peut mettre les mesures en cache pour économiser ses battéries ou sa bande passante)
• timeout – Le temps maximal (en millisecondes) alloué au matériel pour fournir une position

Un appel à watchPosition could look like:

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

Une démo de watchPosition : https://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 Obsolète depuis 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

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

• nsIGeolocationProvider
• nsIDOMGeolocation
• nsIDOMGeoPosition
• nsIDOMGeoPositionCallback
• nsIDOMGeoPositionError
• nsIDOMGeoPositionErrorCallback
• nsIDOMGeoPositionOptions
• nsIDOMNavigatorGeolocation
• Geolocation API on w3.org
• Demos about the Geolocation API