Как настроить проект Flutter

Перед настройкой проекта Flutter обязательно выполните предварительные шаги, описанные в руководстве по подготовке. После того как вы включите оплату и создадите ключ API, вы сможете настроить проект Flutter, который будете использовать для разработки приложения.

Шаг 1. Установите необходимое ПО

Чтобы собрать проект с помощью пакета Google Maps для Flutter, вам нужно установить Flutter SDK и настроить среду разработки для своей целевой платформы. Подробнее об этом рассказывается в руководстве по установке Flutter.

Шаг 2. Установите пакет Google Maps для Flutter в новый проект

Вам потребуется добавить плагин Google Maps для Flutter.

Создайте проект Flutter и добавьте плагин Maps.

  1. Создайте новый проект Flutter с помощью команды 
      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!
    : Код вашего приложения находится в папке google_maps_in_flutter/lib/main.dart. Чтобы запустить приложение, введите: 
      cd google_maps_in_flutter
  flutter run
    Целевые платформы приложения – iOS, Android и Веб. В настоящее время Google Maps SDK не поддерживает приложения для ПК, кроме браузерной версии.
  2. Добавьте в проект плагин Google Maps для Flutter. 
    flutter pub add google_maps_flutter
  
  Resolving dependencies...
  [Listing of dependencies elided]

  Changed 14 dependencies!

Шаг 3. Укажите версию платформы

Android

Укажите минимальную версию SDK для Android.

  1. Откройте файл конфигурации android/app/build.gradle в своей интегрированной среде разработки.
  2. Измените значение android.defaultConfig.minSdkVersion на 21: 
      android {
    //...
    defaultConfig {
        applicationId "com.example.google_maps_in_flutter"
        minSdkVersion 21     // Set to 21
        targetSdkVersion flutter.targetSdkVersion
        versionCode flutterVersionCode.toInteger()
        versionName flutterVersionName
    }
    //...
  }
  3. При настройке параметра defaultConfig укажите свой уникальный идентификатор приложения (ApplicationID).
  4. Сохраните файл и синхронизируйте проект с Gradle.

iOS

Укажите минимальную версию платформы iOS.

  1. Откройте файл конфигурации ios/Podfile в своей интегрированной среде разработки.
  2. Добавьте в начало файла Podfile следующие строки: 
      # Set platform to 14.0 to enable latest Google Maps SDK
  platform :ios, '14.0'

Шаг 4. Добавьте ключ API в проект

В процессе подготовки вы создали ключ API для своего приложения. Теперь добавьте этот ключ в проект Flutter. При работе с Flutter этот ключ API следует добавить для всех целевых платформ (iOS, Android и Веб).

Укажите свой ключ API вместо YOUR_API_KEY в следующих примерах.

Android

Чтобы упростить работу, используйте плагин Secrets Gradle для Android.

Чтобы установить плагин Secrets Gradle для Android в проект Google Карт:

  1. В Android Studio откройте файл build.gradle или build.gradle.kts верхнего уровня и добавьте в элемент dependencies, принадлежащий элементу 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. Откройте файл build.gradle уровня модуля и добавьте в элемент plugins приведенный ниже код.

    Groovy

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

    Kotlin

    plugins {
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. Убедитесь, что для targetSdk и compileSdk в файле build.gradle уровня модуля задано значение 34.
  4. Сохраните файл и синхронизируйте проект с Gradle.
  5. Откройте файл secrets.properties в каталоге верхнего уровня и добавьте приведенный ниже код. Укажите вместо YOUR_API_KEY свой ключ API. Храните свой ключ в этом файле, поскольку secrets.properties не добавляется в систему управления версиями. 
    MAPS_API_KEY=YOUR_API_KEY
  6. Сохраните файл.

  7. Создайте файл local.defaults.properties в директории верхнего уровня (там же, где хранится файл secrets.properties), а затем добавьте указанный ниже код.

    MAPS_API_KEY=DEFAULT_API_KEY

    Этот файл служит запасным хранилищем ключа API, чтобы обеспечить выполнение сборки, даже если система не обнаружит файл secrets.properties. Так может произойти, если вы скопируете приложение из системы управления версиями, игнорирующей файл secrets.properties, и не создадите secrets.properties с ключом API локально.

  8. Сохраните файл.
  9. В файле AndroidManifest.xml найдите раздел com.google.android.geo.API_KEY и обновите android:value attribute. Если тег <meta-data> не существует, создайте его как дочерний элемент для тега <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.*"
}

Примечание. Как показано выше, рекомендуемое имя метаданных для ключа API – com.google.android.geo.API_KEY. С ним ключ можно будет использовать для аутентификации в нескольких API Google Карт для Android, включая Flutter SDK. Для обеспечения обратной совместимости API также поддерживает имя com.google.android.maps.v2.API_KEY. Это устаревшее имя обеспечивает аутентификацию только для Android Maps API версии 2. В приложении можно указать только одно из имен в метаданных ключа API. Если указаны оба имени, API вызывает исключение.

iOS

Добавьте ключ API в файл AppDelegate.swift.

  1. Откройте файл ios/Runner/AppDelegate.swift в проекте Flutter в своей интегрированной среде разработки.
  2. Добавьте следующую команду, чтобы импортировать в приложение пакет Google Maps для Flutter:
    3. import GoogleMaps
  3. Добавьте API в метод application(_:didFinishLaunchingWithOptions:), указав свой ключ API вместо YOUR_API_KEY: 
    GMSServices.provideAPIKey("YOUR_API_KEY")
  4. Сохраните и закройте файл AppDelegate.swift.

Готовый файл AppDelegate.swift должен выглядеть следующим образом:

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

Веб

Добавьте ключ API в файл index.html приложения.

  1. Откройте файл web/index.html в проекте Flutter в своей интегрированной среде разработки.
  2. Добавьте следующий тег скрипта внутри тега <head>, указав свой ключ API вместо 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. Сохраните и закройте файл index.html.

    Полностью раздел head в index.html должен выглядеть так: 

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

Шаг 5. Добавьте карту

Ниже приведены примеры кода, который позволяет добавить простую карту в новое приложение Flutter.

  1. Откройте файл lib/main.dart в проекте Flutter в своей интегрированной среде разработки.
  2. В методе main вашего приложения добавьте или измените методы, которые будут создавать и инициализировать экземпляр 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. Запустите все эмуляторы и/или устройства, на которых будет выполняться приложение.
  4. Запустите приложение. Вы должны получить примерно такой результат: 
      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"):

    Введите номер платформы, на которой будет выполняться приложение. Этот выбор будет предлагаться при каждом вызове flutter run. Если на вашей системе не запущен эмулятор и не подключено тестовое устройство, Flutter автоматически запустит Chrome.

    На всех платформах должна отобразиться карта, центрированная по городу Сидней (Австралия). Если вы не видите карту, проверьте, добавлен ли ключ API в нужный целевой проект.

Дальнейшие действия

Теперь, когда у вас есть ключ API и проект Flutter, вы можете создавать и запускать приложения. Вместе с пакетом Google Maps для Flutter доступно множество руководств и примеров приложений, которые помогут вам начать работу. Подробную информацию можно найти в следующих источниках: