Configura un proyecto de Flutter

Antes de configurar un proyecto de Flutter, asegúrate de cumplir con los requisitos previos que se indican en Antes de comenzar. Una vez que habilites la facturación y crees una clave de API, podrás configurar el proyecto de Flutter que usarás para desarrollar tu app.

Paso 1: Instala el software requerido

Para crear un proyecto con el paquete de Google Maps para Flutter, debes instalar el SDK de Flutter y configurar el entorno de desarrollo para tu plataforma de destino. Consulta la Guía de instalación de Flutter para obtener más detalles.

Paso 2: Instala el paquete de Google Maps para Flutter en un proyecto nuevo

El paquete de Google Maps para Flutter se ofrece como un complemento.

Crea el proyecto de Flutter y agrega el complemento de Maps.

1. Crea un nuevo proyecto de Flutter con el comando "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!

   El código de la aplicación se encuentra en google_maps_in_flutter/lib/main.dart. Para ejecutar la aplicación, escribe lo siguiente:

     cd google_maps_in_flutter
     flutter run

   Esta aplicación está diseñada para iOS, Android y la Web. Por el momento, el SDK de Google Maps no admite las aplicaciones para computadoras que se ejecutan fuera de un navegador.
2. Agrega a este proyecto el complemento del paquete de Google Maps para Flutter.

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

Paso 3: Establece la versión de la plataforma

Nota: Se requiere establecer la versión de la plataforma para implementar la app en iOS, Android o ambos. Las apps web no requieren que se establezca una versión mínima.

Android

Establece la versión mínima del SDK para Android.

1. Abre el archivo de configuración android/app/build.gradle en tu IDE preferido.
2. Cambia el valor de android.defaultConfig.minSdkVersion a 21:

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

3. Cuando configures defaultConfig, especifica tu ApplicationID único.
4. Guarda el archivo y sincroniza los cambios de tu proyecto con Gradle.

iOS

Establece la versión mínima de la plataforma para iOS.

1. Abre el archivo de configuración ios/Podfile en tu IDE preferido.
2. Agrega las siguientes líneas al comienzo de este Podfile:

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

Paso 4: Agrega tu clave de API al proyecto

En Antes de comenzar, generaste una clave de API para tu app. Ahora agrega esa clave a tu proyecto de Flutter. Para ejecutar tu proyecto de Flutter, deberías agregar esta clave de API a todas las plataformas de destino: iOS, Android y la Web.

En los siguientes ejemplos, reemplaza YOUR_API_KEY por tu clave de API.

Nota: Te recomendamos que uses claves de API diferentes y que implementes restricciones de aplicaciones para Android, iOS y la Web.

Android

Para optimizar esta tarea, te recomendamos que uses el complemento Secrets Gradle para Android.

Nota: Consulta la documentación del complemento Secrets Gradle para Android en GitHub para conocer los requisitos del sistema y las instrucciones de instalación más recientes.

Si deseas instalar el complemento Secrets Gradle para Android en tu proyecto de Google Maps, haz lo siguiente:

1. En Android Studio, abre tu archivo build.gradle o build.gradle.kts de nivel superior y agrega el siguiente código al elemento dependencies en 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. Abre el archivo build.gradle a nivel del módulo y agrega el siguiente código al 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. En tu archivo build.gradle a nivel del módulo, asegúrate de que targetSdk y compileSdk estén establecidos en 34.
4. Guarda el archivo y sincroniza tu proyecto con Gradle.
5. Abre el archivo secrets.properties en tu directorio de nivel superior y agrega el siguiente código. Reemplaza YOUR_API_KEY por tu clave de API. Almacena tu clave en este archivo, ya que secrets.properties no se registra en un sistema de control de versión.
   Nota: Si el archivo secrets.properties no existe, créalo en la misma carpeta en la que se encuentra el archivo local.properties.

   MAPS_API_KEY=YOUR_API_KEY

6. Guarda el archivo.

7. Crea el archivo local.defaults.properties en tu directorio de nivel superior, en la misma carpeta en la que se encuentra el archivo secrets.properties, y agrega el siguiente código.

   Nota: Ingresa el código como se muestra. No reemplaces DEFAULT_API_KEY por tu clave de API.

   MAPS_API_KEY=DEFAULT_API_KEY

   El propósito de este archivo es proporcionar una ubicación de copia de seguridad de la clave de API si no se encuentra el archivo secrets.properties, de modo que no fallen las compilaciones. Esto puede ocurrir si clonas la app desde un sistema de control de versión que omite secrets.properties y aún no creaste un archivo secrets.properties localmente para proporcionar tu clave de API.

8. Guarda el archivo.
9. En tu archivo AndroidManifest.xml, ve a com.google.android.geo.API_KEY y actualiza android:value attribute. Si la etiqueta <meta-data> no existe, créala como un elemento secundario de la etiqueta <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: Como se mostró anteriormente, com.google.android.geo.API_KEY es el nombre de metadatos recomendado para la clave de API. Se puede utilizar una clave con este nombre para la autenticación con varias APIs basadas en Google Maps en la plataforma de Android, incluido el SDK de Flutter. Respecto de la retrocompatibilidad, la API también admite el nombre com.google.android.maps.v2.API_KEY. Este nombre heredado solo permite la autenticación con la versión 2 de la API de Google Maps para Android. Una aplicación puede especificar solo uno de los nombres de metadatos de la clave de API. Si se especifican ambos, la API arrojará una excepción.

iOS

Agrega tu clave de API al archivo AppDelegate.swift.

1. Abre el archivo ios/Runner/AppDelegate.swift en tu proyecto de Flutter con tu IDE preferido.
2. Escribe la siguiente sentencia de importación para agregar el paquete de Google Maps para Flutter a tu app:

import GoogleMaps

3. Agrega tu API al método application(_:didFinishLaunchingWithOptions:) y reemplaza YOUR_API_KEY por tu clave de API:

   GMSServices.provideAPIKey("YOUR_API_KEY")

4. Guarda y cierra el archivo AppDelegate.swift.

El archivo AppDelegate.swift completado debería verse de la siguiente manera:

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

Agrega tu clave de API al archivo de aplicación index.html.

1. Abre el archivo web/index.html en tu proyecto de Flutter con tu IDE preferido.
2. Agrega la siguiente etiqueta de secuencia de comandos dentro de la etiqueta <head> y reemplaza YOUR_API_KEY por tu clave 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. Guarda y cierra el archivo index.html.

   La sección head completa de index.html debería verse de la siguiente manera:

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

Paso 5: Agrega un mapa

El siguiente código muestra cómo agregar un mapa simple a una app nueva creada con Flutter.

Nota: Si los pasos anteriores se completaron correctamente, la función principal en Dart debería funcionar en todas las plataformas, incluidas Android, iOS y la Web.

1. Abre el archivo lib/main.dart en tu proyecto de Flutter con tu IDE preferido.
2. En el método principal predeterminado de tu app, agrega o actualiza métodos para crear e inicializar una instancia 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. Arranca los emuladores o dispositivos en los que desees ejecutar tu aplicación.
4. Ejecuta tu aplicación. Deberías ver un resultado como el siguiente:

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

   Escribe el número de la plataforma que deseas ejecutar. Cada vez que invoques flutter run, Flutter te mostrará esas opciones. Si tu sistema de desarrollo no tiene ningún emulador en ejecución ni ningún dispositivo de prueba conectado, Flutter debería abrir Chrome.

   Cada plataforma debería mostrar un mapa centrado en Sídney, Australia. Si esto no ocurre, asegúrate de haber agregado tu clave de API al proyecto de destino adecuado.

Próximos pasos

Ahora que cuentas con una clave de API y un proyecto de Flutter, puedes crear y ejecutar apps. El paquete de Google Maps para Flutter proporciona muchos instructivos y apps de ejemplo que pueden ayudarte a comenzar. Para obtener más información, consulta los siguientes recursos:

• Instructivo Agrega un mapa con un marcador
• Codelabs para Flutter con Google Maps Platform
• Muestras de código en GitHub