terrain_monitor_app/GOOGLE_MAPS_SETUP.md

Google Maps API Key Setup

⚠️ IMPORTANTE

Per usare le mappe nell'app, devi configurare la Google Maps API Key.

📋 Come Ottenere la API Key

1. Vai alla Google Cloud Console

Apri: https://console.cloud.google.com/

2. Crea o Seleziona un Progetto

• Se hai già un progetto, selezionalo
• Altrimenti crea un nuovo progetto:
  • Click su "Select a project" in alto
  • Click su "NEW PROJECT"
  • Nome: "Terrain Monitor" (o come preferisci)
  • Click "CREATE"

3. Abilita le API necessarie

Nel tuo progetto:

1. Vai su APIs & Services → Library
2. Cerca e abilita queste API:
   • Maps SDK for Android
   • Maps SDK for iOS (se userai iOS)
   • Geocoding API (opzionale, per reverse geocoding)

4. Crea la API Key

1. Vai su APIs & Services → Credentials
2. Click su + CREATE CREDENTIALS → API key
3. Verrà creata una chiave (es. AIzaSyA...)
4. COPIA questa chiave

5. (Consigliato) Restrizioni di Sicurezza

Per proteggere la tua API key:

1. Click sulla chiave appena creata
2. In Application restrictions:
   • Seleziona "Android apps"
   • Click "+ Add an item"
   • Package name: eu.aseltd.terrain_monitor_app
   • SHA-1 certificate fingerprint:

     # Debug (per sviluppo)
     keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
     
     # Copia il valore SHA1 e incollalo
     

3. In API restrictions:
   • Seleziona "Restrict key"
   • Seleziona solo: "Maps SDK for Android"
4. Click SAVE

🔧 Configura l'App

Android

Modifica il file:

android/app/src/main/AndroidManifest.xml

Trova questa riga:

<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="YOUR_GOOGLE_MAPS_API_KEY_HERE"/>

Sostituisci YOUR_GOOGLE_MAPS_API_KEY_HERE con la tua chiave:

<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="AIzaSyA..."/> <!-- La tua chiave qui -->

iOS (se necessario)

Modifica il file:

ios/Runner/AppDelegate.swift

Aggiungi:

import GoogleMaps

@main
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GMSServices.provideAPIKey("YOUR_GOOGLE_MAPS_API_KEY_HERE")
    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

💰 Costi

Google Maps offre un credito gratuito mensile di $200:

• Fino a 28.500 caricamenti mappe al mese GRATIS
• Per un'app con pochi utenti, rimarrai sotto il limite gratuito

Monitora l'uso su: https://console.cloud.google.com/google/maps-apis/metrics

✅ Verifica

Dopo aver configurato:

1. Ricompila l'app:

   flutter clean
   flutter build apk --debug
   flutter install
   

2. Apri l'app e naviga a:

   • Allarmi → Tap su un allarme → Dovrebbe vedere la mappa
   • Siti → Tap su un sito → Tab "Informazioni" → Dovrebbe vedere la mappa

3. Se vedi la mappa con il marker, tutto funziona! ✅

🔒 Sicurezza

IMPORTANTE:

• ✅ NON committare la API key nel repository pubblico
• ✅ Usa le restrizioni (Android app + API restrictions)
• ✅ Monitora l'uso nel dashboard Google Cloud
• ✅ Per produzione, considera di usare variabili d'ambiente

🛠️ Troubleshooting

Problema: Mappa grigia

• Verifica che la API key sia corretta
• Verifica che "Maps SDK for Android" sia abilitato
• Verifica le restrizioni (potrebbero essere troppo strette)

Problema: "API key not found"

• Verifica che la <meta-data> sia dentro <application> nel Manifest
• Ricompila l'app con flutter clean

Problema: "This API project is not authorized"

• Verifica le restrizioni della key
• Prova a rimuovere temporaneamente le restrizioni per testare
• Verifica che il package name sia corretto

📚 Risorse

• Google Maps Platform
• Maps SDK for Android
• google_maps_flutter package

---

Fatto? Dopo aver configurato la chiave, l'app funzionerà perfettamente con le mappe! 🗺️