1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
|
---
title: Usando geolocation
slug: Web/API/Geolocation_API
tags:
- Geolocation API
- Guia(2)
translation_of: Web/API/Geolocation_API
original_slug: Using_geolocation
---
<p>A <strong>API geolocation</strong> permite que o usuário forneça sua localização a aplicativos web se ele desejar. Por questões de privacidade, o usuário é perguntado se permite fornecer informações de localização.</p>
<h2 id="O_objeto_geolocation">O objeto geolocation</h2>
<p>O aplicativo de geolocalização é utilizado através de um objeto filho chamado <code>geolocation </code>localizado dentro do objeto <code>navigator</code>. Se o objeto existe, os serviços de geolocalização estarão disponíveis. Você pode adicionalmente testar a presença da geolocalização:</p>
<pre class="brush: js">if ("geolocation" in navigator) {
/* geolocation is available */
} else {
alert("I'm sorry, but geolocation services are not supported by your browser.");
}
</pre>
<p>{{ gecko_minversion_header("1.9.2") }}</p>
<p>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:</p>
<pre class="brush: js">var geolocation = Components.classes["@mozilla.org/geolocation;1"]
.getService(Components.interfaces.nsIDOMGeoGeolocation);
</pre>
<h3 id="Obtendo_a_posição_atual">Obtendo a posição atual</h3>
<p>Para obter a localização atual do usuário, você pode utiliza o método <code>getCurrentPosition().</code> Isto inicia uma requisição assíncrona para identificar a posição do usuário, e consulta o hardware de localização para 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.</p>
<p>Use <code>getCurrentPosition()</code> 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 (localização do IP location ou rede wifi) podem retornar do método <code>getCurrentPosition()</code>.</p>
<pre class="brush: js">navigator.geolocation.getCurrentPosition(function(position) {
do_something(position.coords.latitude, position.coords.longitude);
});</pre>
<p>O exemplo acima irá fazer a função the <code>do_something()</code> executar quando a localização for obtida.</p>
<h3 id="Verificando_a_posição_atual">Verificando a posição atual</h3>
<div class="syntaxbox">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 <code>watchPosition(), </code>a qual tem os mesmos parâmetros de entrada da função <code>getCurrentPosition()</code>. 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 <code>getCurrentPosition()</code>, é chamado uma única vez, se nenhum resultado válido retornar.</div>
<p>O <code>watchPosition()</code> pode ser usado sem que não haja a chamada inicial de <code>getCurrentPosition()</code>.</p>
<pre class="brush: js">var watchID = navigator.geolocation.watchPosition(function(position) {
do_something(position.coords.latitude, position.coords.longitude);
}
);</pre>
<p>O método <code>watchPosition()</code> retorna um número de ID que pode ser usado para identificar a <code>posição</code> solicitada; você pode usar esse valor em conjunto com o método <code>clearWatch()</code>, parando a localização do usuário.</p>
<pre>navigator.geolocation.clearWatch(watchID);
</pre>
<p><code>watchPosition()</code>retorna um callback sucesso e erro (como <code>getCurrentPosition</code>) e um objeto <code>positionObjects</code>, que pode ter três propriedades:</p>
<ul>
<li><code>enableHighAccuracy</code> – Um booleano que indica ao dispositivo que você deseja obter leituras mais precisas (este parâmetro pode ou não pode fazer a diferença, dependendo do seu hardware)</li>
<li><code>maximumAge</code> – Idade máxima (em milissegundos) da leitura (opção adequada, pois o dispositivo pode armazenar em cache leituras para poupar energia e / ou largura de banda)</li>
<li><code>timeout</code> – O tempo máximo (em milissegundos) que está preparado para permitir que o dispositivo para tentar obter uma Geo Location</li>
</ul>
<p>Segue uma chamada para watchPosition:</p>
<pre>var wpid = navigator.geolocation.watchPosition(geo_success, geo_error, {enableHighAccuracy:true, maximumAge:30000, timeout:27000});</pre>
<p>Exemplo de watchPosition em uso: <a href="https://www.thedotproduct.org/posts/a-simple-example-of-navigatorgeolocationwatchposition.html">thedotproduct.org/posts/a-simple-example-of-navigatorgeolocationwatchposition</a><br>
<a id="fck_paste_padding"></a></p>
<h2 id="Imprimindo_uma_posição">Imprimindo uma posição</h2>
<p>A localização do usuário é impressa usando o objeto Position, que tem os seguintes campos:</p>
<dl>
<dt>timestamp</dt>
<dd>Momento em que a leitura foi feita, como <code>DOMTimeStamp</code>.</dd>
<dt>coords</dt>
<dd>Objecto <a class="internal" href="/en/XPCOM_Interface_Reference/NsIDOMGeoPositionCoords" title="En/NsIDOMGeoPositionCoords"><code>nsIDOMGeoPositionCoords</code></a> indicando a localização.</dd>
<dt>address {{ gecko_minversion_inline("1.9.2") }} {{obsolete_inline("14.0")}}</dt>
<dd>{{ interface("nsIDOMGeoPositionAddress") }} objeto especificando o endereço correspondente, se disponível.</dd>
</dl>
<h2 id="Manipulação_de_erros"><br>
Manipulação de erros</h2>
<p>Retornando o callback de erro, se fornecido, chamar <code>getCurrentPosition()</code> e <code>watchPosition()</code>, tem a seguinte assinatura:</p>
<pre>function errorCallback(PositionError error);
</pre>
<p>O <code>PositionError</code> tem a seguinte estrutura de campos:</p>
<dl>
<dt>code</dt>
<dd>Um código de erro numérico dos seguintes procedimentos:</dd>
<dt><dfn><code>UNKNOWN_ERROR</code></dfn> (valor numérico 0)</dt>
<dd>O processo de aquisição de localização falhou devido a um erro de qualquer outro código nesta interface.</dd>
<dt><dfn><code>PERMISSION_DENIED</code></dfn> (valor numérico 1)</dt>
<dd>O processo de aquisição da localização falhou porque a origem aplicativo não tem permissão para usar a API de Geolocalização.</dd>
<dt><dfn><code>POSITION_UNAVAILABLE</code></dfn> (valor numérico 2)</dt>
<dd>A posição do dispositivo não pôde ser determinada. Um ou mais provedores de localização utilizados no processo de aquisição local gerou um erro interno que falou o processo completamente.</dd>
<dt><dfn><code>TIMEOUT</code></dfn> (numeric value 3)</dt>
<dd>O comprimento máximo de tempo especificado.</dd>
<dt>message</dt>
<dd>Uma mensagem de erro legível para uso em registros e depuração, mas não para exibir para o usuário.</dd>
</dl>
<h2 id="Browser_compatibility">Compatibilidade com navegadores</h2>
<table class="standard-table">
<tbody>
<tr>
<th>Navegador</th>
<th>Suporte Básico</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="Solicitando_permissão">Solicitando permissão</h2>
<p>Qualquer add-on hospedado em addons.mozilla.org, que faz uso de dados de geolocalização, deve solicitar antes uma permissão. A função a seguir vai solicitar a permissão de um modo semelhante ao prompt. A resposta do usuário será salva no parâmetro <code>pref</code>. A função fornecida no parâmetro de <code>callback</code> será chamado com um valor booleano que indica a resposta do usuário. Se for <code>true</code>, o add-on poderá retornar dados de geolocalização.</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="Veja_também">Veja também</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>
|
