Configurar um projeto do Flutter

Antes de configurar um projeto Flutter, conclua as etapas de pré-requisito em Antes de começar. Depois de ativar o faturamento e criar uma chave de API, você poderá configurar o projeto Flutter usado para desenvolver seu app.

Etapa 1: instalar o software necessário

Para criar um projeto usando o pacote do Google Maps para Flutter, instale o SDK do Flutter e configure seu ambiente de desenvolvimento para a plataforma segmentada. Confira o Guia de instalação do Flutter para mais detalhes.

Etapa 2: instalar o pacote do Google Maps para Flutter em um novo projeto

O Flutter oferece o pacote do Google Maps para Flutter como plug-in.

Crie o projeto Flutter e adicione o plug-in do Maps.

1. Crie um novo projeto 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!

   Seu código do aplicativo está em google_maps_in_flutter/lib/main.dart. Para executar seu aplicativo, digite:

     cd google_maps_in_flutter
     flutter run

   Este aplicativo é direcionado a iOS, Android e Web. No momento, o SDK do Google Maps não dá suporte a aplicativos de computador fora de um navegador.
2. Adicione o plug-in do Google Maps para Flutter a este projeto.

   flutter pub add google_maps_flutter
     
     Resolving dependencies...
     [Listing of dependencies elided]
   
     Changed 14 dependencies!

Etapa 3: definir a versão da plataforma

Observação: é preciso definir uma versão de plataforma para desenvolver o app para iOS, Android ou ambos. Apps da Web não exigem a definição de uma versão mínima.

Android

Defina a versão mínima do SDK para Android.

1. Abra o arquivo de configuração android/app/build.gradle em seu IDE preferido.
2. Altere o valor de android.defaultConfig.minSdkVersion para 21:

     android {
       //...
       defaultConfig {
           applicationId "com.example.google_maps_in_flutter"
           minSdkVersion 21     // Set to 21
           targetSdkVersion flutter.targetSdkVersion
           versionCode flutterVersionCode.toInteger()
           versionName flutterVersionName
       }
       //...
     }

3. Ao configurar defaultConfig, especifique um ApplicationID exclusivo.
4. Salve o arquivo e sincronize suas alterações no projeto com o Gradle.

iOS

Defina a versão mínima da plataforma iOS.

1. Abra o arquivo de configuração ios/Podfile em seu IDE preferido.
2. Adicione as seguintes linhas ao início deste Podfile:

     # Set platform to 14.0 to enable latest Google Maps SDK
     platform :ios, '14.0'

Etapa 4: adicionar sua chave de API ao projeto

Em Antes de começar, você gerou uma chave de API para seu app. Agora adicione essa chave ao projeto Flutter. No Flutter, é preciso adicionar essa chave para todas as plataformas segmentadas: iOS, Android e Web.

Nos exemplos a seguir, substitua YOUR_API_KEY pela chave de API.

Observação: recomendamos usar chaves de API separadas e restrições de aplicativo para Android, iOS e Web.

Android

Se quiser otimizar essa tarefa, use o plug-in Secrets Gradle para Android.

Observação: consulte a documentação do plug-in Secrets Gradle para Android (link em inglês) no GitHub para conferir os requisitos mais recentes do sistema e instruções de instalação.

Para instalar esse plug-in no seu projeto do Google Maps:

1. No Android Studio, abra o arquivo de nível superior build.gradle ou build.gradle.kts e adicione o seguinte código ao elemento dependencies em buildscript.

   Groovy

   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. Depois, abra o arquivo build.gradle no nível do módulo e adicione o seguinte código ao elemento plugins.

   Groovy

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

   Kotlin

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

3. No arquivo build.gradle no nível do módulo, defina targetSdk e compileSdk como 34.
4. Salve o arquivo e sincronize seu projeto com o Gradle.
5. Abra o arquivo secrets.properties no seu diretório de nível superior e adicione o código a seguir. Substitua YOUR_API_KEY pela sua chave de API. Armazene sua chave nesse arquivo porque secrets.properties não é verificado em um sistema de controle de versões.
   Observação: se o arquivo secrets.properties não existe, crie-o na mesma pasta que o arquivo local.properties.

   MAPS_API_KEY=YOUR_API_KEY

6. Salve o arquivo.

7. Crie o arquivo local.defaults.properties no seu diretório de nível superior, na mesma pasta que o arquivo secrets.properties, e depois adicione o seguinte código.

   Observação: insira o código conforme mostrado. Não substitua DEFAULT_API_KEY pela sua chave de API.

   MAPS_API_KEY=DEFAULT_API_KEY

   O objetivo desse arquivo é oferecer um local de backup para a chave da API se o arquivo secrets.properties não for encontrado, para que os builds não apresentem falha. Isso pode acontecer se você clonar o app de um sistema de controle de versões que omite secrets.properties e ainda não tiver criado um arquivo secrets.properties localmente para fornecer sua chave de API.

8. Salve o arquivo.
9. No seu arquivo AndroidManifest.xml, vá até com.google.android.geo.API_KEY e atualize android:value attribute. Se a tag <meta-data> não existe, crie-a como um elemento filho da 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.*"
}
        

Observação: conforme mostrado acima, com.google.android.geo.API_KEY é o nome de metadados recomendado para a chave de API. Uma chave com esse nome pode ser usada para autenticar várias APIs do Google Maps na plataforma Android, incluindo o SDK do Flutter. Para garantir a compatibilidade com versões anteriores, a API também aceita o nome com.google.android.maps.v2.API_KEY. Esse nome herdado permite autenticação apenas na API Android Maps v2. Um aplicativo pode especificar somente um dos nomes de metadados da chave de API. Se ambos forem especificados, a API vai gerar uma exceção.

iOS

Adicione a chave de API ao arquivo AppDelegate.swift.

1. Abra o arquivo ios/Runner/AppDelegate.swift no seu projeto Flutter com o IDE preferido.
2. Insira a instrução de importação a seguir para adicionar o pacote do Google Maps para Flutter ao seu app:

import GoogleMaps

3. Adicione a API ao método application(_:didFinishLaunchingWithOptions:), substituindo sua chave de API por YOUR_API_KEY:

   GMSServices.provideAPIKey("YOUR_API_KEY")

4. Salve e feche o arquivo AppDelegate.swift.

O arquivo AppDelegate.swift concluído será semelhante a este:

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

Adicione a chave de API ao arquivo de aplicativo index.html.

1. Abra o arquivo web/index.html no seu projeto Flutter com o IDE preferido.
2. Adicione a seguinte tag script dentro da tag <head>, substituindo YOUR_API_KEY pela chave de 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. Salve e feche o arquivo index.html.

   A seção head completa do index.html será parecida com o seguinte:

       <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>

Etapa 5: adicionar um mapa

O código a seguir demonstra como adicionar um mapa simples a um novo app Flutter.

Observação: se as etapas anteriores foram concluídas com sucesso, a seguinte função Dart principal deverá funcionar em todas as plataformas, incluindo Android, iOS e Web.

1. Abra o arquivo lib/main.dart no seu projeto Flutter com o IDE preferido.
2. Adicione ou atualize métodos no método principal padrão do app para criar e inicializar uma instância de 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. Inicie qualquer emulador ou dispositivo em que você quer executar seu aplicativo.
4. Execute o aplicativo. Será exibida uma saída parecida com esta:

     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"): 

   Digite o número da plataforma que você quer executar. Sempre que você invocar flutter run, o Flutter vai apresentar essas opções. Se o sistema de desenvolvimento não tiver um emulador em execução ou dispositivo de teste conectado, o Flutter deverá abrir o Chrome.

   Cada plataforma deve exibir um mapa centralizado em Sydney, Austrália. Se o mapa não aparecer, verifique se você adicionou a chave de API ao projeto de destino adequado.

Próximas etapas

Agora que você tem uma chave de API e um projeto Flutter, já pode criar e executar apps. O pacote do Google Maps para Flutter oferece vários tutoriais e apps de exemplo para ajudar você a começar. Para saber mais, confira os seguintes recursos:

• Tutorial Adicionar mapas com marcadores
• Codelabs para Flutter com a Plataforma Google Maps
• Exemplos de código no GitHub