Révision 330443 sur Utiliser la Géolocalisation

  • Raccourci de la révision : en/Using_geolocation
  • Titre de la révision : Utiliser la Géolocalisation
  • ID de la révision : 330443
  • Créé :
  • Créateur : Nigel_Sheldon
  • Version actuelle ? Non
  • Commentaire
Étiquettes : 

Contenu de la révision

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 {{ Interface("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.");
}

{{ gecko_minversion_header("1.9.2") }}

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.

Watching the current position

If the position data changes (either by device movement or if more accurate geo information arrives) , you can set up a callback that is called with that updated position information.  This is done using the watchPosition() function, which has the same input parameters as getCurrentPosition().  Its callback is called multiple times, allowing the browser to either update your location as you move, or provide a more accurate location as different techniques are used to geolocate you.  The error callback, which is optional just as it is for getCurrentPosition(), is called only once, if there will never be valid results returned.

You can use watchPosition() without an initial getCurrentPosition() call.

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 {{ gecko_minversion_inline("1.9.2") }} {{obsolete_inline("14.0")}}
An {{ interface("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

  • {{ Interface("nsIGeolocationProvider") }}
  • {{ Interface("nsIDOMGeolocation") }}
  • {{ Interface("nsIDOMGeoPosition") }}
  • {{ Interface("nsIDOMGeoPositionCallback") }}
  • {{ Interface("nsIDOMGeoPositionError") }}
  • {{ Interface("nsIDOMGeoPositionErrorCallback") }}
  • {{ Interface("nsIDOMGeoPositionOptions") }}
  • {{ Interface("nsIDOMNavigatorGeolocation") }}
  • Geolocation API on w3.org
  • Demos about the Geolocation API
{{ HTML5ArticleTOC() }}

Source de la révision

<p>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.</p>
<p>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&nbsp; Pour plus d'information, voir les règles de respect de la vie privée de <a href="http://www.mozilla.com/en-US/legal/privacy/" title="http://www.mozilla.com/en-US/legal/privacy/">Mozilla</a> et celles de <a href="http://www.google.com/privacy-lsf.html" title="http://www.google.com/privacy-lsf.html">Google</a> concernant ces données et leurs utilisations possibles. Voir aussi le <a href="http://mxr.mozilla.org/mozilla1.9.1/source/dom/src/geolocation/NetworkGeolocationProvider.js" title="http://mxr.mozilla.org/mozilla1.9.1/source/dom/src/geolocation/NetworkGeolocationProvider.js">code source</a> si vous êtes curieux du mode de fonctionnement de ce service.</p>
<div class="note">
  <strong>Note:</strong> Si vous voullez écrire un service de localisation, consultez {{ Interface("nsIGeolocationProvider") }}.&nbsp; Vous pourriez aussi touver le <a href="/fr/docs/Monitoring_WiFi_access_points" title="/En/Monitoring_WiFi_access_points">service de gestion des point d'accès WiFi</a> intéressant.</div>
<p>Firefox 3.6 (Gecko 1.9.2) a ajouté le support du <a href="http://catb.org/gpsd/" title="http://catb.org/gpsd/">GPSD</a> (GPS daemon) pour la géolocalisation sous Linux.</p>
<div class="note">
  <strong>Note:</strong> Les extensions hébergées par addons.mozilla.org doivent explicitement demander la permission avant d'accéder à ces données.</div>
<h2 id="The_geolocation_object">L'objet de Géolocalisation</h2>
<p>L'API de Géolocalisation est publiée via l'enfant <code>geolocation</code> dans l'objet <code>navigator</code>. Si l'objet existe, l'utilisation du service de géolocalisation est possible. Vous pouvez tester via ce code :</p>
<pre class="brush: js">
if ("geolocation" in navigator) {
  /* géolocalisation possible */
} else {
&nbsp; alert("Le service de géolocalisation n'est pas disponible sur votre ordinateur.");
}
</pre>
<p>{{ gecko_minversion_header("1.9.2") }}</p>
<p>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 :</p>
<pre class="brush: js">
var geolocation = Components.classes["@mozilla.org/geolocation;1"]
                            .getService(Components.interfaces.nsIDOMGeoGeolocation);
</pre>
<h3 id="Getting_the_current_position">Obtenir la position actuelle</h3>
<p>Pour obtenir la position actuelle de l'utilisateur, vous pouvez appeler la méthode <code>getCurrentPosition()</code>. 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.</p>
<p>Utilisez <code>getCurrentPosition()</code> 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 <code>getCurrentPosition()</code> pour commencer.</p>
<pre class="brush: js">
navigator.geolocation.getCurrentPosition(function(position) {
&nbsp;&nbsp;do_something(position.coords.latitude, position.coords.longitude);
});</pre>
<p>Cet exemple éxécute la fonction <code>do_something()</code> quand la localisation est obtenue.</p>
<h3 id="Watching_the_current_position">Watching the current position</h3>
<p>If the position data changes (either by device movement or if more accurate geo information arrives) , you can set up a callback that is called with that updated position information.&nbsp; This is done using the <code>watchPosition()</code>&nbsp;function, which has the same input parameters as <code>getCurrentPosition()</code>.&nbsp; Its callback is called multiple times, allowing the browser to either update your location as you move, or provide a more accurate location as different techniques are used to geolocate you. &nbsp;The error callback, which is optional just as it is for <code>getCurrentPosition()</code>, is called only once, if there will never be valid results returned.</p>
<p>You can use <code>watchPosition()</code> without an initial <code>getCurrentPosition() </code>call.</p>
<pre class="brush: js">
var watchID&nbsp;= navigator.geolocation.watchPosition(function(position) {
&nbsp;&nbsp;do_something(position.coords.latitude, position.coords.longitude);
}
);</pre>
<p>The <code>watchPosition()</code> method returns an ID&nbsp;number that can be used to uniquely identify the requested position watcher; you use this value in tandem with the <code>clearWatch()</code>&nbsp;method to stop watching the user's location.</p>
<pre>
navigator.geolocation.clearWatch(watchID);
</pre>
<p><code>watchPosition() </code>accepts a success callback and error callback (like <code>getCurrentPosition</code>) and an optional <code>positionObjects</code> object, which can have three properties:</p>
<ul>
  <li><code>enableHighAccuracy</code> – 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)</li>
  <li><code>maximumAge</code> – The maximum age (in milliseconds) of the reading (this is appropriate as the device may cache readings to save power and/or bandwidth)</li>
  <li><code>timeout</code> – The maximum time (in milliseconds) for which you are prepared to allow the device to try to obtain a Geo location</li>
</ul>
<p>A call to watchPosition could look like:</p>
<pre>
var wpid = navigator.geolocation.watchPosition(geo_success, geo_error, {enableHighAccuracy:true, maximumAge:30000, timeout:27000});</pre>
<p><a id="fck_paste_padding">A demo of watchPosition in use:&nbsp;</a><a class="external" href="http://www.thedotproduct.org/experiments/geo/">http://www.thedotproduct.org/experiments/geo/</a><br />
  <a id="fck_paste_padding"></a></p>
<h2 id="Describing_a_position">Describing a position</h2>
<p>The user's location is described using a Position object, which has the following fields:</p>
<dl>
  <dt>
    timestamp</dt>
  <dd>
    The time at which the reading was taken, as a <code>DOMTimeStamp</code>.</dd>
  <dt>
    coords</dt>
  <dd>
    An <a class="internal" href="/en/XPCOM_Interface_Reference/NsIDOMGeoPositionCoords" title="En/NsIDOMGeoPositionCoords"><code>nsIDOMGeoPositionCoords</code></a> object indicating the location.</dd>
  <dt>
    address {{ gecko_minversion_inline("1.9.2") }} {{obsolete_inline("14.0")}}</dt>
  <dd>
    An {{ interface("nsIDOMGeoPositionAddress") }} object specifying the corresponding address, if available.</dd>
</dl>
<h2 id="Handling_errors">Handling errors</h2>
<p>The error callback, if provided when calling <code>getCurrentPosition()</code>&nbsp;or <code>watchPosition()</code>, has the following signature:</p>
<pre>
function errorCallback(PositionError error);
</pre>
<p>The <code>PositionError</code> structure has the following fields:</p>
<dl>
  <dt>
    code</dt>
  <dd>
    A numeric error code which much be one of the following:</dd>
  <dt>
    <dfn id="unknown_error"><code>UNKNOWN_ERROR</code></dfn> (numeric value 0)</dt>
  <dd>
    The location acquisition process failed due to an error not covered by the definition of any other error code in this interface.</dd>
  <dt>
    <dfn id="permission_denied_error"><code>PERMISSION_DENIED</code></dfn> (numeric value 1)</dt>
  <dd>
    The location acquisition process failed because the application origin does not have permission to use the Geolocation API.</dd>
  <dt>
    <dfn id="position_unavailable_error"><code>POSITION_UNAVAILABLE</code></dfn> (numeric value 2)</dt>
  <dd>
    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.</dd>
  <dt>
    <dfn id="timeout_error"><code>TIMEOUT</code></dfn> (numeric value 3)</dt>
  <dd>
    The specified maximum length of time has elapsed before the implementation could successfully acquire a new Position object.</dd>
  <dd>
    &nbsp;</dd>
  <dt>
    message</dt>
  <dd>
    A human readable error message, suitable for use in logs and debugging -- but not for display to the user.</dd>
</dl>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<table class="standard-table">
  <tbody>
    <tr>
      <th>Browser</th>
      <th>Basic support</th>
      <th><a class="external" href="http://dev.w3.org/geo/api/spec-source-v2.html">Geolocation Level 2</a></th>
    </tr>
    <tr>
      <td>Internet Explorer</td>
      <td>IE9 RC</td>
      <td>---</td>
    </tr>
    <tr>
      <td>Firefox (Gecko)</td>
      <td><strong>3.5</strong> (1.9.1)</td>
      <td>---</td>
    </tr>
    <tr>
      <td>Opera</td>
      <td><strong>10.60</strong></td>
      <td>---</td>
    </tr>
    <tr>
      <td>Safari | Chrome | WebKit</td>
      <td>5 | 5 | 533</td>
      <td>---</td>
    </tr>
  </tbody>
</table>
<h2 id="Prompting_for_permission">Prompting for permission</h2>
<p>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 <code>pref</code> parameter, if applicable. The function provided in the <code>callback</code> parameter will be called with a boolean value indicating the user's response. If <code>true</code>, the add-on may access geolocation data.</p>
<pre class="brush: js">
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); });
</pre>
<h2 id="See_also">See also</h2>
<ul>
  <li>{{ Interface("nsIGeolocationProvider") }}</li>
  <li>{{ Interface("nsIDOMGeolocation") }}</li>
  <li>{{ Interface("nsIDOMGeoPosition") }}</li>
  <li>{{ Interface("nsIDOMGeoPositionCallback") }}</li>
  <li>{{ Interface("nsIDOMGeoPositionError") }}</li>
  <li>{{ Interface("nsIDOMGeoPositionErrorCallback") }}</li>
  <li>{{ Interface("nsIDOMGeoPositionOptions") }}</li>
  <li>{{ Interface("nsIDOMNavigatorGeolocation") }}</li>
  <li><a class="external" href="http://dev.w3.org/geo/api/spec-source.html" title="http://dev.w3.org/geo/api/spec-source.html">Geolocation API on w3.org</a></li>
  <li><a href="/en-US/demos/tag/tech:geolocation" title="en-US/demos/tag/tech:geolocation/">Demos about the Geolocation API</a></li>
</ul>
<div>
  {{ HTML5ArticleTOC() }}</div>
<!-- languages({
  "es": "es/Usar_la_Geolocalización"
}) -->
Revenir à cette révision