Flutter 프로젝트 설정

Flutter 프로젝트를 설정하기 전, 시작하기 전에 페이지에 설명된 필수 단계를 완료했는지 확인하세요. 결제를 활성화하고 API 키를 생성한 후 앱 개발에 사용할 Flutter 프로젝트를 설정할 수 있습니다.

1단계: 필수 소프트웨어 설치하기

Flutter용 Google 지도 패키지를 사용하여 프로젝트를 빌드하려면 Flutter SDK를 설치하고 대상 플랫폼에 맞춰 개발 환경을 설정해야 합니다. 자세한 내용은 Flutter 설치 가이드에서 확인하세요.

2단계: 새 프로젝트에 Flutter용 Google 지도 패키지 설치하기

Flutter는 Flutter 플러그인으로 Flutter용 Google 지도 패키지를 제공합니다.

Flutter 프로젝트를 생성하고 지도 플러그인을 추가하세요.

1. 'flutter create'를 사용하여 새로운 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 지도 SDK는 브라우저 외부의 데스크톱 애플리케이션을 지원하지 않습니다.
2. 이 프로젝트에 Flutter용 Google 지도 패키지 플러그인을 추가하세요.

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

3단계: 플랫폼 버전 설정하기

참고: iOS, Android 또는 둘 다에 앱을 배포하려면 플랫폼 버전을 설정해야 합니다. 웹 앱은 최소 버전을 설정하지 않아도 됩니다.

Android

Android용 최소 SDK 버전을 설정합니다.

1. 원하는 IDE에서 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. 원하는 IDE에서 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, 웹)에 추가해야 합니다.

다음 예에서 YOUR_API_KEY를 이 API 키로 바꾸세요.

참고: Android, iOS, 웹에 대해 별도의 API 키를 사용하고 애플리케이션 제한을 두는 것이 좋습니다.

Android

이 작업을 간소화하려면 Android용 Secrets Gradle 플러그인을 사용하는 것이 좋습니다.

참고: 최신 시스템 요구사항 및 설치 안내는 GitHub의 Android용 Secrets Gradle 플러그인 문서를 참고하세요.

Google 지도 프로젝트에 Android용 Secrets Gradle 플러그인을 설치하려면 다음 단계를 따르세요.

1. Android 스튜디오에서 최상위 수준 build.gradle 또는 build.gradle.kts 파일을 열고 다음 코드를 buildscript 아래 dependencies 요소에 추가합니다.

   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. 모듈 수준 build.gradle 파일에서 targetSdk 및 compileSdk를 34로 설정해야 합니다.
4. 파일을 저장하고 프로젝트를 Gradle과 동기화합니다.
5. 최상위 수준 디렉터리에서 secrets.properties 파일을 연 후 다음 코드를 추가합니다. YOUR_API_KEY를 직접 생성한 API 키로 변경합니다. secrets.properties가 버전 제어 시스템에 체크인되는 데서 제외되었으므로 키를 이 파일에 저장합니다.
   참고: secrets.properties 파일이 존재하지 않으면 local.properties 파일과 동일한 폴더에 파일을 만듭니다.

   MAPS_API_KEY=YOUR_API_KEY

6. 파일을 저장합니다.

7. 최상위 수준 디렉터리에서 secrets.properties 파일과 동일한 폴더에 local.defaults.properties 파일을 만든 후 다음 코드를 추가합니다.

   참고: 아래에 표시된 대로 코드를 입력하세요. DEFAULT_API_KEY를 API 키로 바꾸지 마세요.

   MAPS_API_KEY=DEFAULT_API_KEY

   이 파일의 목적은 secrets.properties 파일이 없는 경우 빌드에 실패하지 않도록 API 키의 백업 위치를 제공하는 것입니다. 이는 버전 제어 시스템에서 secrets.properties가 빠진 앱을 복제하거나 API 키를 제공하는 secrets.properties 파일을 아직 로컬에서 생성하지 않은 경우 발생할 수 있습니다.

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.*"
}
        

참고: 위의 내용처럼, com.google.android.geo.API_KEY는 API 키의 권장되는 메타데이터 이름입니다. 이 이름의 키는 Android 플랫폼에서 Flutter SDK 등 여러 Google 지도 기반 API에 대한 인증에 사용할 수 있습니다. 이전 버전과의 호환성을 위해 API에서는 com.google.android.maps.v2.API_KEY 이름도 지원합니다. 이 기존 이름을 사용하면 Android 지도 API v2에 대한 인증만 가능합니다. 애플리케이션에서는 API 키 메타데이터 이름을 하나만 지정할 수 있습니다. 두 개가 모두 지정되면 API에서 예외가 발생합니다.

iOS

AppDelegate.swift 파일에 직접 생성한 API 키를 추가합니다.

1. 원하는 IDE로 Flutter 프로젝트에서 ios/Runner/AppDelegate.swift 파일을 엽니다.
2. 다음 가져오기 문을 추가하여 Flutter용 Google 지도 패키지를 앱에 추가합니다.

import GoogleMaps

3. application(_:didFinishLaunchingWithOptions:) 메서드에 API를 추가하여 YOUR_API_KEY를 직접 생성한 API 키로 대체합니다.

   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. 원하는 IDE로 Flutter 프로젝트에서 web/index.html 파일을 엽니다.
2. <head> 태그 안에 다음 스크립트 태그를 추가하여 YOUR_API_KEY를 직접 생성한 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. index.html 파일을 저장하고 닫습니다.

   index.html의 전체 head 섹션은 다음과 유사합니다.

       <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 앱에 간단한 지도를 추가하는 방법을 보여줍니다.

참고: 이전 단계를 완료했다고 가정하면 Android, iOS, 웹을 포함한 모든 플랫폼에서 다음 주요 Dart 기능이 작동합니다.

1. 원하는 IDE로 Flutter 프로젝트에서 lib/main.dart 파일을 엽니다.
2. 앱의 기본 메인 메서드에서 메서드를 추가하거나 업데이트하여 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는 위와 같은 선택 항목을 표시합니다. 개발 시스템에 실행 중인 에뮬레이터가 없거나 테스트 기기가 연결되어 있지 않은 경우 Flutter에서 Chrome을 열도록 선택합니다.

   각 플랫폼에는 오스트레일리아 시드니를 중심으로 한 지도가 표시됩니다. 지도가 표시되지 않는다면 적절한 대상 프로젝트에 직접 생성한 API 키를 추가했는지 확인하세요.

다음 단계

이제 API 키와 Flutter 프로젝트를 만들었으므로 앱을 만들고 실행할 수 있습니다. Flutter용 Google 지도 패키지는 시작하는 데 도움이 되는 다양한 튜토리얼과 샘플 앱을 제공합니다. 자세히 알아보려면 다음 리소스를 확인해 보세요.

• 마커가 표시되는 지도 추가 튜토리얼
• Google Maps Platform을 사용한 Flutter용 Codelab
• GitHub의 코드 샘플