A Barreira entre a Web e o Hardware Nativo
Por padrão, o código JavaScript que executa na WebView de um aplicativo híbrido não tem permissão nem acesso direto às antenas de GPS do smartphone por questões de segurança. O plugin @capacitor/geolocation atua como uma Ponte Nativa (Native Bridge), traduzindo requisições assíncronas do React para chamadas Java/Kotlin no Android.
Fluxo de Funcionamento da Native Bridge (Capacitor Geolocation)
Ambiente React (JS)
Executa Geolocation.getCurrentPosition()
Capacitor Native Bridge
Tradução de JS para chamadas nativas em Kotlin/Java
Sistema Android OS
Verifica o AndroidManifest.xml e dispara o modal de permissão
Hardware GPS / Satélite
Ativa o chip GPS, calcula triangulação e devolve JSON de coordenadas
Matriz de Permissões Android
| Característica | ACCESS_COARSE_LOCATION | ACCESS_FINE_LOCATION |
|---|---|---|
| Fonte de Dados | Torres Celulares / Wi-Fi | Chip GPS + Satélites |
| Precisão Real | Aproximada (100m - 2km) | Exata (3m - 10m) |
| Impacto de Bateria | Baixo consumo | Alto consumo de energia |
| Casos de Uso | Previsão do tempo, Notícias | Uber, Strava, Navegação |
* Nota: No Android 12+, o usuário pode optar por conceder apenas a localização aproximada mesmo que o app solicite a precisa. Declare sempre ambas no manifesto.
Anatomia da Resposta JSON de Posição
Objeto retornado ao resolver a Promise da função getCurrentPosition():
{
"coords": {
"latitude": -23.550520, // Latitude em graus decimais
"longitude": -46.633308, // Longitude em graus decimais
"accuracy": 12.5, // Margem de erro em metros
"altitude": 760.2, // Altitude acima do nível do mar
"speed": 0.0, // Velocidade em m/s
"heading": null // Direção de movimento (graus)
},
"timestamp": 1698754000000 // Timestamp da leitura
}