Configura un progetto Flutter

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

Passaggio 1: installa il software richiesto

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

Passaggio 2: installa il pacchetto Google Maps for 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 di Maps.

  1. Crea un nuovo progetto Flutter usando "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 ha come target iOS, Android e Web. Al momento, l'SDK di Google Maps non supporta applicazioni desktop al di fuori di un browser.
  2. Aggiungi il plug-in del pacchetto Google Maps for 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. Cambia 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 nel tuo IDE preferito.
  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 aggiungi la chiave al tuo progetto Flutter. Per Flutter, dovresti 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 o build.gradle.kts di primo livello e aggiungi il seguente codice all'elemento dependencies in buildscript.

    Trendy

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

    Kotlin

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

    Trendy

    plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}

    Kotlin

    plugins {
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. Nel file 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 e aggiungi il codice seguente. Sostituisci YOUR_API_KEY con la tua chiave API. Archivia la chiave in questo file perché secrets.properties è escluso dal check-in 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, la 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 nel caso in cui il file secrets.properties non venga trovato, in modo che le build non generino errori. Questo può accadere se cloni l'app da un sistema di controllo della versione che omette secrets.properties e non hai ancora creato un file secrets.properties in locale 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, crealo come elemento secondario del tag <application>. 
    <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

    Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Flutter SDK. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

  10. In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

    Groovy

    secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    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.*"
}

Kotlin

secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    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 l'autenticazione su più API basate su Google Maps sulla piattaforma Android, incluso 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 precedente consente l'autenticazione solo con l'API 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 chiave API al file AppDelegate.swift.

  1. Apri il file ios/Runner/AppDelegate.swift nel tuo progetto Flutter con il tuo IDE preferito.
  2. Aggiungi la seguente istruzione di importazione per aggiungere il pacchetto Google Maps for 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 la chiave API con YOUR_API_KEY. 
    <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 di 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 la tua 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 richiami flutter run, Flutter ti mostrerà queste opzioni. Se il tuo sistema di sviluppo non ha un emulatore in esecuzione o un dispositivo di test collegato, Flutter dovrebbe scegliere di aprire Chrome.

    Ogni piattaforma deve mostrare una mappa centrata su Sydney, Australia. Se non hai visualizzato 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 saperne di più, consulta le seguenti risorse: