Utiliser la Géolocalisation

Cette traduction est incomplète. Aidez à traduire cet article depuis l'anglais.

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.

Note: Si vous voullez écrire un service de localisation, consultez nsIGeolocationProvider.  Vous pourriez aussi touver le service de gestion des point d'accès WiFi intéressant.

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

Note: Les extensions hébergées par addons.mozilla.org doivent explicitement demander la permission avant d'accéder à ces données.

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'autre 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 : http://www.thedotproduct.org/experiments/geo/


Représenter une position

La position de l'utilisateur est représenté par l'objet Position, contenant les champs suivants:

timestamp
L'instant auquel la lecture a été effectué, sous forme d'un DOMTimeStamp.
coords
Un objet nsIDOMGeoPositionCoords indiquant la position.
address Obsolète depuis Gecko 14.0
Un objet nsIDOMGeoPositionAddress spécifiant l'adresse correspondante, si disponible.

Gestion des erreurs

La fonction de rappel erreur, si fourni à l'appel de getCurrentPosition() ou watchPosition(), à la signature suivante:

function errorCallback(PositionError error);

La structure PositionError contient les champs suivants: 

code
Un code d'erreur numérique devant obligatoirement être l'un des suivants:
UNKNOWN_ERROR (valeur numérique 0)
La procédure d'acquisition de la position a échoué à cause d'une erreur non définie dans la liste des codes erreurs suivante.
PERMISSION_DENIED (valeur numérique 1)
La procédure d'acquisition de la position a échoué car l'application n'a pas l'autorisation d'utiliser l'API de Geolocalisation.
POSITION_UNAVAILABLE (valeur numérique 2)
La position de l'appareil n'a pu être déterminée. Une ou plusieurs sources utilisées pour l'acquisition de la position ont renvoyé une erreur interne causant l'échec total de la procédure.
TIMEOUT (valeur numérique 3)
La durée de temps maximum spécifiée a été dépassée avant que la procédure d'acquisition puisse récupérer un nouvel objet Position.
message
Un message d'erreur compréhensible, utilisable dans des logs et à des fins de debug -- mais à ne pas afficher à l'utilisateur.

Compatibilité navigateurs

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

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : lotfire24, edouard, fluxine, Nigel_Sheldon
 Dernière mise à jour par : lotfire24,