Workshop: localização, mapas e permissões

No fim desta aula consegues

• Explicar como GPS, Wi-Fi e redes móveis produzem uma posição e o compromisso entre precisão e bateria.
• Distinguir permissão em uso, sempre, precisa e aproximada, e o que as lojas exigem para localização em segundo plano.
• Comparar Google Maps, Apple Maps e OpenStreetMap em custos, licenças e integração com Flutter.
• Pedir a permissão de localização e tratar todos os resultados, incluindo a negação permanente.
• Obter a posição atual, calcular a localidade mais próxima e mostrar um mapa com marcadores que abrem o detalhe.

De onde vem a posição

Para os testes: a app nunca fala com o GPS; pede ao sistema uma precisão, e o sistema escolhe as fontes.

Precisão vs bateria: uma posição ou um stream

• Níveis de precisão (LocationAccuracy no geolocator): lowest/low usam redes, quilómetros, quase sem bateria; medium usa Wi-Fi, cerca de 100 m; high/best/bestForNavigation ligam o GPS, metros, consumo de bateria elevado.
• Uma posição (getCurrentPosition): "onde estou agora". Liga as fontes, obtém um fix, desliga. É o que uma app de tempo precisa.
• Um stream (getPositionStream): posições contínuas enquanto o utilizador se move. Navegação, corrida, entregas. Com distanceFilter para não emitir a cada metro.
• Plano B: timeLimit para não esperar para sempre, e getLastKnownPosition para usar a última posição que o sistema tem em cache.
• No Tempo Açores a localidade mais próxima está a quilómetros: medium chega e poupa bateria.
• Exemplos: a Uber usa stream de alta precisão só durante a viagem; o Instagram pede uma posição quando tocas em "adicionar localização".

Para os testes: pede a precisão mínima que o caso de uso aguenta; precisão alta é GPS e GPS é bateria.

Permissões de localização (1 de 2): que tipos há

Para os testes: "sempre" e "precisa" são pedidos separados e posteriores; começa por "em uso", e por aproximada se te chegar.

Permissões de localização (2 de 2): justificar, negar, recuperar

• Justificação obrigatória. No iOS, sem NSLocationWhenInUseUsageDescription no Info.plist o diálogo nem aparece. O texto é lido pelo utilizador e pela revisão da Apple: "Para mostrar a previsão da localidade mais próxima", não "Precisamos da sua localização".
• Serviço desligado ≠ permissão negada. O utilizador pode ter a localização desligada no sistema inteiro. Resolve-se nas definições de localização, não nas da app.
• Negação permanente. iOS: uma negação é permanente. Android: "Não voltar a perguntar", ou duas negações seguidas no 11+. A partir daí request() devolve logo negado, sem diálogo.
• Recuperar: explica o que perde e oferece um botão para abrir as definições da app (openAppSettings). Nunca fiques em loop a pedir.
• Pedir em contexto: quando o utilizador toca em "Usar a minha posição", não no arranque. A taxa de aceitação duplica.

Para os testes: uma app tem de tratar quatro casos: serviço desligado, negada, negada para sempre, concedida.

Localização em segundo plano

• É continuar a receber posições com a app fora do ecrã. Quem precisa mesmo: navegação, Strava, entregas, Find My. Uma app de tempo não precisa.
• Android: permissão de background mais um foreground service do tipo location, com notificação permanente visível. O Google Play exige um formulário de declaração, um vídeo da funcionalidade, e que seja central para a app. Senão, rejeição.
• iOS: permissão "Sempre" mais UIBackgroundModes: location. Indicador azul na barra de estado. Periodicamente o iOS mostra "a app X usou a tua localização 34 vezes em segundo plano", com um mapa. Muita gente desinstala nesse momento.
• Custo: GPS contínuo esgota a bateria em horas. O utilizador nota, e culpa a app com razão.
• Alternativas: geofencing (a seguir), significant location changes no iOS (só quando mudas de célula), atualizar quando a app abre.

Para os testes: localização em segundo plano só para funcionalidades centrais, com declaração nas lojas, e o utilizador vê que está a acontecer.

Geofencing

• Uma cerca virtual: centro e raio. O sistema acorda a app quando o utilizador entra, sai ou permanece. A app não precisa de estar a correr.
• É o sistema que vigia, com Wi-Fi e redes móveis: pouca bateria, mas latência de minutos e raio mínimo prático de 100 m.
• Limites: 100 cercas por app no Android, 20 regiões por app no iOS. Ambos exigem permissão em segundo plano.
• Casos: "aviso vermelho para a zona onde acabaste de entrar", lembretes por local, retalho ("estás a 200 m da loja"), check-in automático no trabalho.
• No Flutter há packages comunitários (geofence_service) ou código nativo por plataforma. Não entra no projeto.

Para os testes: geofencing é feito pelo sistema operativo, poupa bateria, tem latência de minutos e limites de 100 (Android) e 20 (iOS).

Mapas (1 de 2): as opções

Mapas (2 de 2): qual usar e porquê

• No Tempo Açores: flutter_map com tiles do OpenStreetMap. Sem chave, sem cartão, corre em qualquer portátil, sem platform view, funciona na web para a demo.
• Regras dos tiles públicos do OSM: atribuição visível "© OpenStreetMap contributors", user agent que identifique a app, nada de descarregar tiles em massa, e tráfego de produção pesado vai para um fornecedor pago.
• Google Maps quando precisas de tráfego, Street View, autocomplete de moradas, ou o aspeto que os utilizadores Android conhecem. E quando tens quem pague a conta se a app crescer.
• Apple Maps quando a app é só iOS e a privacidade é argumento de venda.
• Licenças: os dados do OSM são ODbL (abertos, com atribuição). Google e Apple têm termos de serviço: não podes guardar tiles, nem mostrar os dados deles noutro mapa.

Para os testes: o OSM é grátis mas tem política de uso e atribuição obrigatória; o Google Maps exige chave e conta de faturação mesmo quando não cobra.

Workshop: clonar e correr

git clone https://github.com/pdm-daw-2026/pdm-aula-21.git
cd pdm-aula-21/starter
flutter pub get
flutter run

• starter/ tem a app das aulas anteriores (lista, detalhe, favoritos) com TODOs numerados de 1 a 11 e testes a falhar em test/localizacao_test.dart. Os packages já estão no pubspec.yaml.
• solucao/ tem o estado final. Só se abre quando se está preso mais de 10 minutos.
• Telemóvel físico com localização ligada, ou emulador com posição definida em Extended controls → Location (Ponta Delgada: 37.74, -25.67).

Passo 1: packages e requisitos de plataforma

No projeto do grupo, os mesmos packages entram com um comando:

flutter pub add geolocator permission_handler flutter_map latlong2 url_launcher

• geolocator: posição, serviço ligado, distância entre pontos. permission_handler: pedir e consultar permissões de forma uniforme.
• flutter_map desenha o mapa em Dart; latlong2 dá o tipo LatLng. url_launcher para o link da atribuição.
• Android: minSdk 21 e compileSdk 34 ou superior em android/app/build.gradle. O template do Flutter atual já cumpre.
• iOS: platform :ios, '13.0' no Podfile, e uma macro para o permission_handler (passo 3).

Passo 2: permissões no Android

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Rede: tiles do mapa e API do curso -->
    <uses-permission android:name="android.permission.INTERNET" />

    <!-- Localização em uso. Declara as duas: o Android 12+ deixa
         o utilizador escolher "aproximada", e a app recebe coarse. -->
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

    <!-- NÃO acrescentar sem razão: obriga a declaração no Google Play.
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
    -->

    <application
        android:label="Tempo Açores"
        android:icon="@mipmap/ic_launcher">
        ...
    </application>
</manifest>

Sem INTERNET o mapa fica cinzento em release: em debug o Flutter acrescenta-a por ti, e o erro só aparece no build final.

Passo 3: permissões no iOS

<key>NSLocationWhenInUseUsageDescription</key>
<string>Usamos a tua posição para mostrar a previsão da localidade mais próxima.</string>
<!-- Só se um dia pedires "sempre": -->
<!-- <key>NSLocationAlwaysAndWhenInUseUsageDescription</key> -->

O permission_handler só compila o código de cada permissão que ativares, para a revisão da Apple não ver permissões que não usas:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
        '$(inherited)',
        'PERMISSION_LOCATION=1',
      ]
    end
  end
end

Depois: cd ios && pod install. Quem não tem Mac salta este passo e testa só em Android.

Passo 4: pedir a permissão e tratar todos os resultados

import 'package:geolocator/geolocator.dart';
import 'package:permission_handler/permission_handler.dart';

enum EstadoLocalizacao { pronta, servicoDesligado, negada, negadaParaSempre }

class ServicoLocalizacao {
  /// Garante que podemos pedir uma posição. Nunca lança; devolve o estado.
  Future<EstadoLocalizacao> prepararPermissao() async {
    if (!await Geolocator.isLocationServiceEnabled()) {
      return EstadoLocalizacao.servicoDesligado; // localização desligada no sistema
    }
    var estado = await Permission.locationWhenInUse.status;
    if (estado.isDenied) {
      estado = await Permission.locationWhenInUse.request(); // diálogo do sistema
    }
    return switch (estado) {
      PermissionStatus.granted || PermissionStatus.limited => EstadoLocalizacao.pronta,
      PermissionStatus.permanentlyDenied || PermissionStatus.restricted =>
        EstadoLocalizacao.negadaParaSempre,
      _ => EstadoLocalizacao.negada,
    };
  }
}

Passo 5: o ecrã reage a cada estado

Future<void> _pedirLocalizacao(BuildContext context) async {
  final estado = await context.read<ServicoLocalizacao>().prepararPermissao();
  if (!context.mounted) return; // o utilizador pode ter saído do ecrã

  switch (estado) {
    case EstadoLocalizacao.pronta:
      await context.read<LocalizacaoNotifier>().atualizar();
    case EstadoLocalizacao.servicoDesligado:
      _aviso(context, 'A localização está desligada no telemóvel.',
          acao: 'Ligar', aoTocar: Geolocator.openLocationSettings);
    case EstadoLocalizacao.negadaParaSempre:
      _aviso(context, 'Sem permissão. Podes mudar isso nas definições da app.',
          acao: 'Definições', aoTocar: openAppSettings);
    case EstadoLocalizacao.negada:
      _aviso(context, 'Sem a tua posição, mostramos Ponta Delgada.');
  }
}

void _aviso(BuildContext context, String texto,
    {String? acao, Future<bool> Function()? aoTocar}) {
  ScaffoldMessenger.of(context).showSnackBar(SnackBar(
    content: Text(texto),
    action: acao == null ? null : SnackBarAction(label: acao, onPressed: () => aoTocar?.call()),
  ));
}

Permissões: o que interessa

• Quatro estados, quatro reações. O switch é exaustivo: se acrescentares um estado ao enum, o compilador obriga-te a tratá-lo.
• Serviço desligado abre as definições de localização do sistema; negada para sempre abre as definições da app. São ecrãs diferentes.
• A app continua útil sem permissão: mostra uma localidade por defeito. Nunca bloqueies o ecrã atrás de um pedido.
• context.mounted depois de cada await: o diálogo do sistema demora, e o utilizador pode ter navegado.
• Pede quando o utilizador toca no botão "A minha posição", não em initState.

Passo 6: a posição atual (e um stream para depois)

import 'dart:async'; // TimeoutException

// ...dentro de ServicoLocalizacao
Future<Position> posicaoAtual() async {
  try {
    return await Geolocator.getCurrentPosition(
      locationSettings: const LocationSettings(
        accuracy: LocationAccuracy.medium, // Wi-Fi chega: ~100 m
        timeLimit: Duration(seconds: 10),
      ),
    );
  } on TimeoutException {
    // Sem fix em 10 s (garagem, interior): a última conhecida serve
    final ultima = await Geolocator.getLastKnownPosition();
    if (ultima != null) return ultima;
    rethrow;
  }
}

/// Para navegação, ou para atualizar enquanto o utilizador anda.
Stream<Position> posicoes() => Geolocator.getPositionStream(
      locationSettings: const LocationSettings(
        accuracy: LocationAccuracy.high,
        distanceFilter: 50, // só emite depois de 50 m percorridos
      ),
    );

Passo 7: a localidade mais próxima

import 'package:geolocator/geolocator.dart';

typedef Proximidade = ({Localidade localidade, double metros});

Proximidade maisProxima(Position pos, List<Localidade> localidades) {
  assert(localidades.isNotEmpty, 'a lista vem de GET /v1/locations');
  var melhor = localidades.first;
  var menor = double.infinity;
  for (final l in localidades) {
    final d = Geolocator.distanceBetween(
      pos.latitude, pos.longitude, l.latitude, l.longitude,
    );
    if (d < menor) {
      menor = d;
      melhor = l;
    }
  }
  return (localidade: melhor, metros: menor);
}

String formataDistancia(double metros) => metros < 1000
    ? '${metros.round()} m'
    : '${(metros / 1000).toStringAsFixed(1)} km';

Posição e distância: o que interessa

• Position traz latitude, longitude, accuracy (raio de erro em metros), timestamp e isMocked. Mostra a precisão ao utilizador quando for grande: "a cerca de 2 km".
• distanceBetween devolve metros em linha reta sobre a esfera (Haversine). Não é distância por estrada, e para os Açores chega.
• O record ({Localidade localidade, double metros}) devolve dois valores sem criar uma classe. É Dart 3.
• timeLimit mais getLastKnownPosition: a app responde sempre em 10 s, com a melhor informação que houver.
• Uma posição fora dos Açores (emulador na Califórnia, aluno em férias) dá uma localidade "mais próxima" a 2000 km. Se metros > 100 000, diz "fora dos Açores" e usa a localidade por defeito.

Passo 8: o mapa com tiles do OpenStreetMap

Dentro de _MapaLocalidadesState, o State de um widget que recebe a lista de localidades. Imports: flutter_map e latlong2.

final _controlador = MapController();
static final _acores = LatLngBounds(
  const LatLng(36.7, -31.5), // sudoeste: a sul das Flores
  const LatLng(39.9, -24.6), // nordeste: a leste de Santa Maria
);

@override
Widget build(BuildContext context) {
  return FlutterMap(
    mapController: _controlador,
    options: MapOptions(
      initialCenter: const LatLng(38.4, -28.0),
      initialZoom: 6.5,
      minZoom: 5,
      maxZoom: 15,
      cameraConstraint: CameraConstraint.contain(bounds: _acores),
    ),
    children: [
      TileLayer(
        urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
        userAgentPackageName: 'pt.uac.tempoacores',
      ),
      _marcadores(context), // passo 9
      _atribuicao(),
    ],
  );
}

Passo 9: marcadores com o estado do tempo e atribuição

Widget _marcadores(BuildContext context) {
  final previsoes = context.watch<PrevisaoNotifier>().porLocalidade; // Map<int, Previsao>
  return MarkerLayer(
    markers: [
      for (final l in widget.localidades)
        Marker(
          point: LatLng(l.latitude, l.longitude),
          width: 44,
          height: 44,
          child: GestureDetector(
            onTap: () => context.push('/localidade/${l.id}'),
            child: Tooltip(
              message: l.nome,
              child: Icon(iconePara(previsoes[l.id]?.tipo), size: 36),
            ),
          ),
        ),
    ],
  );
}

Widget _atribuicao() => RichAttributionWidget(attributions: [
      TextSourceAttribution('OpenStreetMap contributors',
          onTap: () => launchUrl(Uri.parse('https://openstreetmap.org/copyright'))),
    ]);

Mapa: o que interessa

• Um FlutterMap é uma pilha de children: tiles em baixo, marcadores em cima, atribuição no canto. A ordem importa.
• urlTemplate com {z}/{x}/{y}: o mapa é feito de imagens de 256 px por nível de zoom. Trocar de fornecedor é trocar o URL (e acrescentar a chave).
• userAgentPackageName é obrigatório para os tiles públicos do OSM; sem ele, bloqueiam-te. A atribuição também é obrigatória, e o RichAttributionWidget resolve isso.
• cameraConstraint prende a câmara aos Açores: o utilizador não se perde no Atlântico. minZoom e maxZoom evitam pedir tiles inúteis.
• Um Marker é um widget qualquer: ícone, texto com a temperatura, um Card. O GestureDetector leva ao detalhe com a rota que já existe.
• iconePara é o helper das aulas anteriores que traduz TipoTempo em IconData; o starter já o tem.

Passo 10: centrar no utilizador

LatLng? _minhaPosicao;

Future<void> _irParaMim() async {
  final servico = context.read<ServicoLocalizacao>();
  final estado = await servico.prepararPermissao();
  if (!mounted) return;
  if (estado != EstadoLocalizacao.pronta) {
    ScaffoldMessenger.of(context).showSnackBar(SnackBar(
      content: const Text('Sem permissão de localização.'),
      action: SnackBarAction(label: 'Definições', onPressed: () => openAppSettings()),
    ));
    return;
  }
  final pos = await servico.posicaoAtual();
  final aqui = LatLng(pos.latitude, pos.longitude);
  setState(() => _minhaPosicao = aqui);
  _controlador.move(aqui, 10); // fora dos Açores? o cameraConstraint segura
}

// No MarkerLayer, um marcador para o utilizador (if-case do Dart 3):
//   if (_minhaPosicao case final eu?)
//     Marker(point: eu, child: const Icon(Icons.person_pin_circle, size: 40)),
// No Scaffold do ecrã:
//   floatingActionButton: FloatingActionButton(
//     onPressed: _irParaMim, child: const Icon(Icons.my_location)),

Passo 11: integrar no projeto como separador Mapa

// Dentro do ShellRoute que tem a NavigationBar (aula 9):
GoRoute(path: '/mapa', builder: (context, state) => const MapaEcra()),

// Na NavigationBar, um destino novo entre Previsão e Avisos:
NavigationDestination(icon: Icon(Icons.map_outlined), label: 'Mapa'),
// e no onDestinationSelected: context.go(['/', '/mapa', '/avisos', '/definicoes'][i])

// Em main.dart, os providers que os ecrãs vão ler:
MultiProvider(
  providers: [
    Provider(create: (_) => ServicoLocalizacao()),
    ChangeNotifierProvider(
      create: (c) => LocalizacaoNotifier(c.read(), c.read()), // serviço + repositório
    ),
  ],
  child: const TempoApp(),
)

• MapaEcra lê as localidades do repositório da aula 13 e passa-as ao MapaLocalidades. O mapa não sabe de HTTP.
• LocalizacaoNotifier guarda posicao, proximidade e erro, e tem o método atualizar() do passo 5. O ecrã inicial e o mapa observam-no.

Problemas frequentes

Até segunda