Configura un progetto Flutter

Prima di configurare un progetto Flutter, assicurati di aver completato i passaggi preliminari descritti in Prima di iniziare. Dopo aver attivato la fatturazione e creato una chiave API, puoi configurare il progetto Flutter che utilizzi per sviluppare la tua app.

Passaggio 1: installa il software necessario

Per creare un progetto utilizzando il pacchetto Google Maps per Flutter, devi installare l'SDK Flutter e configurare l'ambiente di sviluppo per la tua piattaforma di destinazione. Per i dettagli, consulta la guida all'installazione di Flutter.

Passaggio 2: installa il pacchetto Google Maps per Flutter in un nuovo progetto

Flutter offre il pacchetto Google Maps per Flutter come plug-in Flutter.

Crea il progetto Flutter e aggiungi il plug-in Maps.

  1. Crea un nuovo progetto Flutter utilizzando "flutter create": 
      flutter create google_maps_in_flutter --platforms=android,ios,web
  
  Creating project google_maps_in_flutter...
  [Listing of created files elided]
  Wrote 127 files.

  All done!
     Il codice della tua applicazione è in google_maps_in_flutter/lib/main.dart. Per eseguire l'applicazione, digita: 
      cd google_maps_in_flutter
  flutter run
     Questa applicazione è destinata a iOS, Android e Web. Al momento Google Maps SDK non supporta le applicazioni desktop al di fuori di un browser.
  2. Aggiungi il plug-in del pacchetto Google Maps per Flutter a questo progetto. 
    flutter pub add google_maps_flutter
  
  Resolving dependencies...
  [Listing of dependencies elided]

  Changed 14 dependencies!

Passaggio 3: imposta la versione della piattaforma

Android

Imposta la versione minima dell'SDK per Android.

  1. Apri il file di configurazione android/app/build.gradle nel tuo IDE preferito.
  2. Modifica il valore di android.defaultConfig.minSdkVersion in 21: 
      android {
    //...
    defaultConfig {
        applicationId "com.example.google_maps_in_flutter"
        minSdkVersion 21     // Set to 21
        targetSdkVersion flutter.targetSdkVersion
        versionCode flutterVersionCode.toInteger()
        versionName flutterVersionName
    }
    //...
  }
  3. Quando configuri defaultConfig, specifica il tuo ApplicationID univoco.
  4. Salva il file e sincronizza le modifiche del progetto con Gradle.

iOS

Imposta la versione minima della piattaforma iOS.

  1. Apri il file di configurazione ios/Podfile nell'IDE che preferisci.
  2. Aggiungi le seguenti righe all'inizio di questo Podfile: 
      # Set platform to 14.0 to enable latest Google Maps SDK
  platform :ios, '14.0'

Passaggio 4: aggiungi la chiave API al progetto

Nella sezione Prima di iniziare, hai generato una chiave API per la tua app. Ora aggiungila al progetto Flutter. Per Flutter, devi aggiungere questa chiave API a tutte le piattaforme di destinazione: iOS, Android e web.

Negli esempi seguenti, sostituisci YOUR_API_KEY con la tua chiave API.

Android

Per semplificare questa attività, ti consigliamo di utilizzare il plug-in Secrets Gradle per Android.

Per installare il plug-in Secrets Gradle per Android nel tuo progetto Google Maps:

  1. In Android Studio, apri il file build.gradle.kts o build.gradle di primo livello e aggiungi il seguente codice all'elemento dependencies in buildscript.

    Kotlin

    buildscript {
    dependencies {
        classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
    }
}

    Trendy

    buildscript {
    dependencies {
        classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
    }
}
  2. Apri il file build.gradle.kts o build.gradle a livello di modulo e aggiungi il seguente codice all'elemento plugins.

    Kotlin

    plugins {
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}

    Trendy

    plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}
  3. Nel file build.gradle.kts o build.gradle a livello di modulo, assicurati che targetSdk e compileSdk siano impostati su 34.
  4. Salva il file e sincronizza il progetto con Gradle.
  5. Apri il file secrets.properties nella directory di primo livello, quindi aggiungi il codice seguente. Sostituisci YOUR_API_KEY con la tua chiave API. Archivia la chiave in questo file perché secrets.properties è escluso dall'archiviazione in un sistema di controllo della versione. 
    MAPS_API_KEY=YOUR_API_KEY
  6. Salva il file.

  7. Crea il file local.defaults.properties nella directory di primo livello, nella stessa cartella del file secrets.properties, quindi aggiungi il codice seguente.

    MAPS_API_KEY=DEFAULT_API_KEY

    Lo scopo di questo file è fornire un percorso di backup per la chiave API se non viene trovato il file secrets.properties, in modo da evitare errori di build. Questo può accadere se cloni l'app da un sistema di controllo della versione che omette secrets.properties e non hai ancora creato in locale un file secrets.properties per fornire la tua chiave API.

  8. Salva il file.
  9. Nel file AndroidManifest.xml, vai a com.google.android.geo.API_KEY e aggiorna android:value attribute. Se il tag <meta-data> non esiste, creane uno come elemento secondario del tag <application>. 
    <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

    Nota: com.google.android.geo.API_KEY è il nome dei metadati consigliato per la chiave API. Una chiave con questo nome può essere utilizzata per autenticarsi a più API basate su Google Maps sulla piattaforma Android, incluso lo SDK Flutter. Per garantire la compatibilità con le versioni precedenti, l'API supporta anche il nome com.google.android.maps.v2.API_KEY. Questo nome legacy consente l'autenticazione solo all'API Android Maps v2. Un'applicazione può specificare solo uno dei nomi dei metadati della chiave API. Se sono specificati entrambi, l'API genera un'eccezione.

  10. In Android Studio, apri il file build.gradle.kts o build.gradle a livello di modulo e modifica la proprietà secrets. Se la proprietà secrets non esiste, aggiungila.

    Modifica le proprietà del plug-in impostando propertiesFileName su secrets.properties, imposta defaultPropertiesFileName su local.defaults.properties e imposta eventuali altre proprietà.

    Kotlin

    secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
    // 2. Add this line, where YOUR_API_KEY is your API key:
    //        MAPS_API_KEY=YOUR_API_KEY
    propertiesFileName = "secrets.properties"

    // A properties file containing default secret values. This file can be
    // checked in version control.
    defaultPropertiesFileName = "local.defaults.properties"

    // Configure which keys should be ignored by the plugin by providing regular expressions.
    // "sdk.dir" is ignored by default.
    ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
    ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
}

    Trendy

    secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
    // 2. Add this line, where YOUR_API_KEY is your API key:
    //        MAPS_API_KEY=YOUR_API_KEY
    propertiesFileName = "secrets.properties"

    // A properties file containing default secret values. This file can be
    // checked in version control.
    defaultPropertiesFileName = "local.defaults.properties"

    // Configure which keys should be ignored by the plugin by providing regular expressions.
    // "sdk.dir" is ignored by default.
    ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
    ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
}

Nota: come mostrato sopra, com.google.android.geo.API_KEY è il nome dei metadati consigliato per la chiave API. Una chiave con questo nome può essere utilizzata per eseguire l'autenticazione su più API basate su Google Maps sulla piattaforma Android, tra cui l'SDK Flutter. Per la compatibilità con le versioni precedenti, l'API supporta anche il nome com.google.android.maps.v2.API_KEY. Questo nome legacy consente l'autenticazione solo nell'API di Android Maps v2. Un'applicazione può specificare solo uno dei nomi dei metadati della chiave API. Se vengono specificati entrambi, l'API genera un'eccezione.

iOS

Aggiungi la tua chiave API al file AppDelegate.swift.

  1. Apri il file ios/Runner/AppDelegate.swift nel progetto Flutter con l'IDE che preferisci.
  2. Aggiungi la seguente istruzione di importazione per aggiungere il pacchetto Google Maps per Flutter alla tua app:
    3. import GoogleMaps
  3. Aggiungi l'API al metodo application(_:didFinishLaunchingWithOptions:), sostituendo la chiave API con YOUR_API_KEY: 
    GMSServices.provideAPIKey("YOUR_API_KEY")
  4. Salva e chiudi il file AppDelegate.swift.

Il file AppDelegate.swift completato dovrebbe essere simile al seguente:

import UIKit
import Flutter
import GoogleMaps  // Add this import

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)

    // TODO: Add your Google Maps API key
    GMSServices.provideAPIKey("YOUR_API_KEY")

    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

Web

Aggiungi la chiave API al file dell'applicazione index.html.

  1. Apri il file web/index.html nel tuo progetto Flutter con il tuo IDE preferito.
  2. Aggiungi il seguente tag script all'interno del tag <head>, sostituendo YOUR_API_KEY con la tua chiave API. 
    <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>
  3. Salva e chiudi il file index.html.

    La sezione head completa del index.html dovrebbe essere simile alla seguente:

        <head>
      <base href="/">
      
      <meta charset="UTF-8">
      <meta content="IE=Edge" http-equiv="X-UA-Compatible">
      <meta name="description" content="A new Flutter project.">
      
      <!-- iOS meta tags & icons -->
      <meta name="apple-mobile-web-app-capable" content="yes">
      <meta name="apple-mobile-web-app-status-bar-style" content="black">
      <meta name="apple-mobile-web-app-title" content="google_maps_in_flutter">
      <link rel="apple-touch-icon" href="icons/Icon-192.png">
      
      <script>
        (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
          key: "YOUR_API_KEY",
          v: "weekly",
          // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
          // Add other bootstrap parameters as needed, using camel case.
          });
      </script>
      
      <title>google_maps_in_flutter</title>
      <link rel="manifest" href="manifest.json">
    </head>

Passaggio 5: aggiungi una mappa

Il seguente codice mostra come aggiungere una mappa semplice a una nuova app Flutter.

  1. Apri il file lib/main.dart nel tuo progetto Flutter con il tuo IDE preferito.
  2. Aggiungi o aggiorna i metodi nel metodo principale predefinito dell'app per creare e inizializzare un'istanza di mapController. 
          import 'package:flutter/material.dart';
      import 'package:google_maps_flutter/google_maps_flutter.dart';
      
      void main() => runApp(const MyApp());
      
      class MyApp extends StatefulWidget {
        const MyApp({super.key});
      
        @override
        State<MyApp> createState() => _MyAppState();
      }
      
      class _MyAppState extends State<MyApp> {
        late GoogleMapController mapController;
      
        final LatLng _center = const LatLng(-33.86, 151.20);
      
        void _onMapCreated(GoogleMapController controller) {
          mapController = controller;
        }
      
        @override
        Widget build(BuildContext context) {
          return MaterialApp(
            home: Scaffold(
              appBar: AppBar(
                title: const Text('Maps Sample App'),
                backgroundColor: Colors.green[700],
              ),
              body: GoogleMap(
                onMapCreated: _onMapCreated,
                initialCameraPosition: CameraPosition(
                  target: _center,
                  zoom: 11.0,
                ),
              ),
            ),
          );
        }
      }
  3. Avvia gli emulatori o i dispositivi su cui vuoi eseguire l'applicazione.
  4. Esegui l'applicazione. Dovresti vedere un output simile al seguente: 
      flutter run

   
    Multiple devices found:
    Android phone (mobile) • emulator-5554 • android-arm64  • Android 13 (API 33) (emulator)
    iPhone (mobile)  • ios • com.apple.CoreSimulator.SimRuntime.iOS-16-2 (simulator)
    Chrome (web) • chrome • web-javascript • Google Chrome 108.0.5359.124
    [1]: Android phone
    [2]: iPhone
    [3]: Chrome
    
    Please choose one (To quit, press "q/Q"):

    Digita il numero della piattaforma che vuoi eseguire. Ogni volta che chiami flutter run, Flutter ti presenterà queste opzioni. Se nel sistema di sviluppo non è in esecuzione un emulatore o non è collegato un dispositivo di test, Flutter dovrebbe scegliere di aprire Chrome.

    Ogni piattaforma deve mostrare una mappa centrata su Sydney, in Australia. Se non hai visto la mappa, verifica di aver aggiunto la chiave API al progetto di destinazione appropriato.

Passaggi successivi

Ora che hai una chiave API e un progetto Flutter, puoi creare ed eseguire app. Il pacchetto Google Maps per Flutter fornisce molti tutorial e app di esempio che possono aiutarti a iniziare. Per scoprire di più, consulta le seguenti risorse: