Obtém a localização geográfica atual de um dispositivo móvel quando uma mudança de posição é detectada ou em um intervalo de tempo definido. 

Figura 1 - Bloco Observar Posição

Compatibilidade

• Bloco cliente mobile: cronapi.cordova.geolocation.watchPosition()

Retorno

Retorna um valor string contendo um ID que representa a mudança de posição observada. Esse ID pode ser utilizado como parâmetro da função Parar Observador de Posição para fazer com que a contínua observação da posição do dispositivo seja interrompida.

Parâmetros

Sucesso

Caso a geolocalização seja obtida com sucesso o fluxo de execução é direcionado para os comandos contidos no parâmetro Sucesso, atribuindo a variável definida neste um objeto contendo a localização geográfica do dipositivo.

• Posição: 1
• Inglês: Success
• Tipo: Comando com retorno ("item") / Command with return ("item")
• Exemplo: é possível utilizar um bloco de programação Exibir Notificação para exibir uma mensagem.

Erro

Caso a obtenção da geolocalização seja mal sucedida, os comandos em Erro são executados.

• Posição: 2
• Inglês: Error
• Tipo: Comando com retorno ("item") / Command with return ("item")
• Exemplo: é possível utilizar um bloco de programação Exibir Notificação para exibir uma mensagem.

Tempo Máximo 

Parâmetro opcional; Aceita uma posição armazenada em cache cujo tempo não seja maior do que o tempo especificado em milissegundos.

• Posição: 3
• Inglês: Maximum Age
  
• Tipo: Inteiro / Integer 
• Exemplo: 3000

Intervalo

Parâmetro opcional. Período máximo de tempo, em milissegundos, para que a localização atual do dispositivo seja atualizada.

• Posição: 4
• Inglês: Time Out
  
• Tipo: Inteiro / Integer 
• Exemplo: 5000

Habilitar Alta Precisão

Parâmetro opcional. Por padrão, o dispositivo tenta recuperar uma posição usando métodos baseados em rede. Definir esta propriedade como verdadeira diz a função para usar métodos mais precisos, como o posicionamento via satélite.

• Posição: 5
• Inglês: Enable High Accuracy
  
• Tipo: Boleano / Boolean 
• Exemplo: Verdadeiro, Falso.

Características do bloco

A função Observar Posição retorna um objeto contendo propriedades relacionadas as coordenadas geográficas do dispositivo. Considerando o objeto chamado Item, tem-se:

• Item.coords.latitude: Distância de qualquer ponto da terra ao Equador medida em grau no meridiano desse ponto (Número);
• Item.coords.longitude: Distância, medida em graus, entre um ponto qualquer da superfície terrestre e o meridiano de Greenwich (Número);
• Item.coords.altitude: Distância vertical medida entre um ponto e uma uma superfície de referência, geralmente o nível médio do mar (Número); 
• Item.coords.accuracy: Nível de precisão das coordenadas de latitude e longitude em metros (Número);
• Item.coords.altitudeAccuracy: Nível de precisão da coordenada de altitude em metros (Número);
• Item.coords.heading: Direção de viagem, especificada em graus contada no sentido horário em relação ao norte verdadeiro (Número);
• Item.coords.speed: Velocidade atual do dispositivo no solo, especificada em metros por segundo (Número);
• Item.coords.timestamp: Hora atual local

Exemplo

A função abaixo em destaque obtém do dispositivo a localização geográfica a cada 3000 milissegundos. Essa localização é obtida através de métodos mais precisos já que o parâmetro "Habilitar Alta Precisão" recebe o valor booleando Verdadeiro. Essas coordenadas geográficas são atribuídas a variável Item, que passa a ter todas as propriedades contidas no objeto retornado pela função e que podem ser utilizadas pela aplicação, como por exemplo coords.latitude, coords.longitude.

Figura 1 - Função que exibe a latitude e longitude de uma posição