Configura un progetto Flutter

Prima di configurare un progetto Flutter, assicurati di aver completato il prerequisito passaggi nella sezione Prima di iniziare. Dopo aver attivato fatturazione e creare una chiave API, puoi configurare il progetto Flutter che utilizzi sviluppare la tua app.

Passaggio 1: installa il software richiesto

Per creare un progetto utilizzando il pacchetto Google Maps per Flutter, devi installare l'SDK Flutter e configura l'ambiente di sviluppo per la piattaforma di destinazione. Dai un'occhiata alla sezione sull'installazione Google Cloud.

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 di 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 ha come target iOS, Android e il 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

Nota: è necessario impostare una versione della piattaforma per eseguire il deployment dell'app su iOS, Android o entrambi. Per le app web non è necessario impostare una versione minima.

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 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 l'app. Ora aggiungi la chiave per il tuo 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.

Nota: ti consigliamo di utilizzare chiavi API separate e di utilizzare le limitazioni delle applicazioni per Android, iOS e web.

Android

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

Nota: consulta le Plug-in Secrets Gradle per Android documentazione su GitHub per i requisiti di sistema e le istruzioni di installazione più recenti.

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

1. In Android Studio, apri l'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 sono impostati a 34.
4. Salva il file e sincronizzare il progetto con Gradle.
5. Apri il file secrets.properties nella directory di primo livello, quindi aggiungi seguire il codice. Sostituisci YOUR_API_KEY con la tua chiave API. Memorizza la chiave in questo file perché secrets.properties è escluso dall'archiviazione in un controllo della versione di un sistema operativo completo.
   Nota: se il file secrets.properties non esiste, crealo nella stessa cartella del file local.properties.

   MAPS_API_KEY=YOUR_API_KEY

6. Salva il file.

7. Crea il file local.defaults.properties nella directory di primo livello, uguale cartella come file secrets.properties, quindi aggiungi il codice riportato di seguito.

   Nota: inserisci il codice come mostrato. Non sostituire DEFAULT_API_KEY con la tua chiave API.

   MAPS_API_KEY=DEFAULT_API_KEY

   Lo scopo di questo file è fornire un percorso di backup per la chiave API se Impossibile trovare il file secrets.properties per evitare errori di build. Ciò può verificarsi 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 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}" />

   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 eseguire l'autenticazione API basate su Google Maps sulla piattaforma Android, tra cui l'SDK Flutter. Per garantire la compatibilità con le versioni precedenti, l'API supporta 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 delle chiavi API. Se sono specificati entrambi, l'API genera un'eccezione.

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

    Modifica le proprietà del plug-in per impostare 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 API basate su Google Maps sulla piattaforma Android, tra cui l'SDK Flutter. Per garantire la compatibilità con le versioni precedenti, l'API supporta il nome com.google.android.maps.v2.API_KEY. Questa eredità permette l'autenticazione solo all'API di Android Maps v2. Un'applicazione può specificare solo uno dei nomi dei metadati delle chiavi API. Se sono 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 tuo progetto Flutter con il tuo IDE preferito.
2. Aggiungi la seguente istruzione di importazione per aggiungere il pacchetto Google Maps per Flutter alla tua app:

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 completa head di index.html deve 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.

Nota: se i passaggi precedenti sono stati eseguiti correttamente, la seguente funzione principale di Dart dovrebbe funzionare su tutte le piattaforme, tra cui Android, iOS e Web.

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 della tua 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 richiami flutter run, Flutter ti mostrerà 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 le app. Il pacchetto Google Maps per Flutter offre molti tutorial e app di esempio può aiutarti a iniziare. Per saperne di più, consulta le seguenti risorse:

• Tutorial sull'aggiunta di una mappa con un indicatore
• Codelab per Flutter con Google Maps Platform
• Esempi di codice su GitHub