[Flutter] 플러터에서 Google Maps 연동하는 방법 정리

Flutter 앱에서 지도 기능을 구현하는 것은 생각보다 간단합니다. 오늘은 Google Maps API 키 설정부터 실제 지도 구현까지 차근차근 알아보겠습니다.

직접 구현한 플러터 UI에서의 지도 화면!

1. Google Cloud Console에서 API 키 발급받기

1-1. Google Cloud Console 접속

1. Google Cloud Console에 접속합니다
2. 새 프로젝트를 생성하거나 기존 프로젝트를 선택합니다

1-2. Maps API 활성화

1. 좌측 메뉴에서 "API 및 서비스" → "라이브러리" 클릭
2. "Maps SDK for Android" 검색 후 활성화
3. "Maps JavaScript API"도 함께 활성화 (웹에서도 사용할 경우)

1-3. API 키 생성

1. "API 및 서비스" → "사용자 인증 정보" 클릭
2. "+ 사용자 인증 정보 만들기" → "API 키" 선택
3. 생성된 API 키를 복사해 둡니다

1-4. API 키 제한 설정 (선택사항)

보안을 위해 API 키 사용을 제한할 수 있습니다.

1. 생성된 API 키 클릭
2. "애플리케이션 제한사항"에서 "Android 앱" 선택
3. 패키지 이름과 SHA-1 인증서 지문 추가

 

2. Flutter 프로젝트 설정

2-1. 의존성 추가

pubspec.yaml 파일에 필요한 패키지를 추가합니다.

dependencies:
  flutter:
    sdk: flutter
  google_maps_flutter: ^2.5.0
  geolocator: ^10.1.0
  permission_handler: ^11.0.1

 

2-2. Android 권한 설정

android/app/src/main/AndroidManifest.xml 파일을 수정합니다.

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- 위치 권한 추가 -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
    
    <application
        android:label="your_app_name"
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher">
        
        <activity>
            <!-- 기존 activity 설정 -->
        </activity>
        
        <!-- Google Maps API 키 추가 - 중요! -->
        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="YOUR_API_KEY_HERE" />
            
        <meta-data
            android:name="flutterEmbedding"
            android:value="2" />
    </application>
</manifest>

 

3. 기본 지도 화면 구현

3-1. 기본 MapScreen 작성

import 'package:flutter/material.dart';
import 'package:geolocator/geolocator.dart';
import 'package:google_maps_flutter/google_maps_flutter.dart';

class MapScreen extends StatefulWidget {
  const MapScreen({super.key});

  @override
  State<MapScreen> createState() => _MapScreenState();
}

class _MapScreenState extends State<MapScreen> {
  CameraPosition? _userPosition;
  Set<Marker> _storeMarkers = {};
  GoogleMapController? _mapController;
  bool _isLoading = true;

  @override
  void initState() {
    super.initState();
    _initializeMap();
  }

  Future<void> _initializeMap() async {
    try {
      // 위치 권한 확인
      LocationPermission permission = await Geolocator.checkPermission();
      if (permission == LocationPermission.denied) {
        permission = await Geolocator.requestPermission();
      }

      // 현재 위치 가져오기
      CameraPosition userPosition = await _getUserLocation();
      Set<Marker> storeMarkers = await _getStoreMarkers(userPosition);

      setState(() {
        _userPosition = userPosition;
        _storeMarkers = storeMarkers;
        _isLoading = false;
      });
    } catch (e) {
      setState(() {
        _isLoading = false;
      });
      print('지도 초기화 실패: $e');
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('지도로 찾기'),
      ),
      body: _isLoading
          ? const Center(child: CircularProgressIndicator())
          : _userPosition == null
              ? const Center(child: Text('위치를 가져올 수 없습니다'))
              : GoogleMap(
                  initialCameraPosition: _userPosition!,
                  mapType: MapType.normal,
                  myLocationEnabled: true,
                  myLocationButtonEnabled: true,
                  markers: _storeMarkers,
                  onMapCreated: (GoogleMapController controller) {
                    _mapController = controller;
                  },
                ),
    );
  }

  Future<CameraPosition> _getUserLocation() async {
    Position position = await Geolocator.getCurrentPosition(
      desiredAccuracy: LocationAccuracy.high,
    );

    return CameraPosition(
      target: LatLng(position.latitude, position.longitude),
      zoom: 15,
    );
  }

  Future<Set<Marker>> _getStoreMarkers(CameraPosition position) async {
    Set<Marker> markers = {};

    // 테스트용 마커들 추가
    for (int i = 0; i < 5; i++) {
      markers.add(
        Marker(
          markerId: MarkerId('store_$i'),
          position: LatLng(
            position.target.latitude + i * 0.001,
            position.target.longitude + i * 0.001,
          ),
          infoWindow: InfoWindow(
            title: '가게 ${i + 1}',
            snippet: '맛있는 음식점',
          ),
        ),
      );
    }

    return markers;
  }
}

 

4. 지도 디자인 페이지 구현

4-1. MapScreen 작성

import 'package:flutter/material.dart';
import 'package:geolocator/geolocator.dart';
import 'package:google_maps_flutter/google_maps_flutter.dart';
import 'package:google_fonts/google_fonts.dart';

class MapScreen extends StatefulWidget {
  const MapScreen({super.key});

  @override
  State<MapScreen> createState() => _MapScreenState();
}

class _MapScreenState extends State<MapScreen> with TickerProviderStateMixin {
  CameraPosition? _userPosition;
  Set<Marker> _storeMarkers = {};
  GoogleMapController? _mapController;
  bool _isLoading = true;
  String _statusMessage = '현재 위치를 찾는 중...';
  
  late AnimationController _animationController;
  late Animation<double> _fadeAnimation;

  @override
  void initState() {
    super.initState();
    
    _animationController = AnimationController(
      duration: const Duration(milliseconds: 800),
      vsync: this,
    );
    
    _fadeAnimation = Tween<double>(
      begin: 0.0,
      end: 1.0,
    ).animate(CurvedAnimation(
      parent: _animationController,
      curve: Curves.easeOut,
    ));

    _initializeMap();
  }

  Future<void> _initializeMap() async {
    try {
      setState(() {
        _statusMessage = '위치 권한을 확인하는 중...';
      });

      LocationPermission permission = await Geolocator.checkPermission();
      if (permission == LocationPermission.denied) {
        permission = await Geolocator.requestPermission();
        if (permission == LocationPermission.denied) {
          throw '위치 권한이 거부되었습니다';
        }
      }

      setState(() {
        _statusMessage = '현재 위치를 가져오는 중...';
      });

      CameraPosition userPosition = await _getUserLocation();
      Set<Marker> storeMarkers = await _getStoreMarkers(userPosition);

      setState(() {
        _userPosition = userPosition;
        _storeMarkers = storeMarkers;
        _isLoading = false;
      });

      _animationController.forward();

    } catch (e) {
      setState(() {
        _isLoading = false;
        _statusMessage = '오류: $e';
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      backgroundColor: const Color(0xFFFFF8F0),
      body: Container(
        decoration: const BoxDecoration(
          gradient: LinearGradient(
            begin: Alignment.topLeft,
            end: Alignment.bottomRight,
            colors: [
              Color(0xFFFFF3E0),
              Color(0xFFFFE0B2),
              Color(0xFFFFCC80),
            ],
          ),
        ),
        child: SafeArea(
          child: Column(
            children: [
              _buildCustomAppBar(),
              Expanded(child: _buildMapContent()),
            ],
          ),
        ),
      ),
      floatingActionButton: _buildFloatingButtons(),
    );
  }

  Widget _buildCustomAppBar() {
    return Container(
      padding: const EdgeInsets.all(20),
      child: Row(
        children: [
          Container(
            width: 44,
            height: 44,
            decoration: BoxDecoration(
              color: Colors.white,
              borderRadius: BorderRadius.circular(12),
              boxShadow: [
                BoxShadow(
                  color: Colors.grey.withOpacity(0.1),
                  blurRadius: 8,
                  offset: const Offset(0, 2),
                ),
              ],
            ),
            child: IconButton(
              onPressed: () => Navigator.of(context).pop(),
              icon: const Icon(Icons.arrow_back_ios_new, size: 20),
            ),
          ),
          const SizedBox(width: 16),
          Expanded(
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Text(
                  '지도로 찾기',
                  style: GoogleFonts.jua(
                    fontSize: 24,
                    fontWeight: FontWeight.bold,
                    color: Colors.brown[700],
                  ),
                ),
                if (!_isLoading)
                  Text(
                    '주변 ${_storeMarkers.length}개 매장',
                    style: TextStyle(
                      fontSize: 14,
                      color: Colors.grey[600],
                    ),
                  ),
              ],
            ),
          ),
        ],
      ),
    );
  }

  Widget _buildMapContent() {
    if (_isLoading) {
      return Container(
        margin: const EdgeInsets.symmetric(horizontal: 20),
        decoration: BoxDecoration(
          color: Colors.white,
          borderRadius: BorderRadius.circular(20),
          boxShadow: [
            BoxShadow(
              color: Colors.grey.withOpacity(0.1),
              blurRadius: 20,
              offset: const Offset(0, 10),
            ),
          ],
        ),
        child: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              const CircularProgressIndicator(),
              const SizedBox(height: 16),
              Text(_statusMessage),
            ],
          ),
        ),
      );
    }

    return FadeTransition(
      opacity: _fadeAnimation,
      child: Container(
        margin: const EdgeInsets.symmetric(horizontal: 20),
        decoration: BoxDecoration(
          borderRadius: BorderRadius.circular(20),
          boxShadow: [
            BoxShadow(
              color: Colors.black.withOpacity(0.1),
              blurRadius: 20,
              offset: const Offset(0, 10),
            ),
          ],
        ),
        child: ClipRRect(
          borderRadius: BorderRadius.circular(20),
          child: GoogleMap(
            initialCameraPosition: _userPosition!,
            mapType: MapType.normal,
            myLocationEnabled: true,
            myLocationButtonEnabled: false,
            markers: _storeMarkers,
            onMapCreated: (GoogleMapController controller) {
              _mapController = controller;
            },
          ),
        ),
      ),
    );
  }

  Widget _buildFloatingButtons() {
    return Column(
      mainAxisSize: MainAxisSize.min,
      children: [
        FloatingActionButton(
          heroTag: "location",
          onPressed: _moveToUserLocation,
          backgroundColor: Colors.white,
          child: const Icon(Icons.my_location),
        ),
        const SizedBox(height: 8),
        FloatingActionButton(
          heroTag: "zoom_in",
          onPressed: () => _mapController?.animateCamera(CameraUpdate.zoomIn()),
          backgroundColor: Colors.white,
          mini: true,
          child: const Icon(Icons.add),
        ),
        const SizedBox(height: 8),
        FloatingActionButton(
          heroTag: "zoom_out",
          onPressed: () => _mapController?.animateCamera(CameraUpdate.zoomOut()),
          backgroundColor: Colors.white,
          mini: true,
          child: const Icon(Icons.remove),
        ),
      ],
    );
  }

  Future<CameraPosition> _getUserLocation() async {
    Position position = await Geolocator.getCurrentPosition(
      desiredAccuracy: LocationAccuracy.high,
    );

    return CameraPosition(
      target: LatLng(position.latitude, position.longitude),
      zoom: 15,
    );
  }

  Future<Set<Marker>> _getStoreMarkers(CameraPosition position) async {
    Set<Marker> markers = {};

    for (int i = 0; i < 5; i++) {
      markers.add(
        Marker(
          markerId: MarkerId('store_$i'),
          position: LatLng(
            position.target.latitude + i * 0.001,
            position.target.longitude + i * 0.001,
          ),
          infoWindow: InfoWindow(
            title: '가게 ${i + 1}',
            snippet: '맛있는 음식점',
          ),
        ),
      );
    }

    return markers;
  }

  void _moveToUserLocation() {
    if (_userPosition != null && _mapController != null) {
      _mapController!.animateCamera(
        CameraUpdate.newCameraPosition(_userPosition!),
      );
    }
  }

  @override
  void dispose() {
    _animationController.dispose();
    _mapController?.dispose();
    super.dispose();
  }
}

 

5. 추가 기능 구현

5-1. 커스텀 마커 아이콘

Future<BitmapDescriptor> _getCustomMarkerIcon() async {
  return BitmapDescriptor.defaultMarkerWithHue(BitmapDescriptor.hueOrange);
}

 

5-2. 지도 스타일 적용

// Google Maps 스타일 JSON을 적용하여 지도 색상을 커스터마이징할 수 있습니다
String _mapStyle = '''
[
  {
    "elementType": "geometry",
    "stylers": [{"color": "#f5f5f5"}]
  }
]
''';

// GoogleMap 위젯에 적용
GoogleMap(
  style: _mapStyle,
  // 다른 설정들...
)

 

6. 문제 해결 팁

6-1. 권한 처리

위치 권한을 안전하게 처리하는 방법

Future<bool> _handleLocationPermission() async {
  bool serviceEnabled;
  LocationPermission permission;

  serviceEnabled = await Geolocator.isLocationServiceEnabled();
  if (!serviceEnabled) {
    ScaffoldMessenger.of(context).showSnackBar(const SnackBar(
        content: Text('위치 서비스가 비활성화되어 있습니다. 위치 서비스를 활성화해주세요.')));
    return false;
  }

  permission = await Geolocator.checkPermission();
  if (permission == LocationPermission.denied) {
    permission = await Geolocator.requestPermission();
    if (permission == LocationPermission.denied) {
      ScaffoldMessenger.of(context).showSnackBar(
          const SnackBar(content: Text('위치 권한이 거부되었습니다')));
      return false;
    }
  }

  if (permission == LocationPermission.deniedForever) {
    ScaffoldMessenger.of(context).showSnackBar(const SnackBar(
        content: Text('위치 권한이 영구적으로 거부되어 설정에서 직접 허용해야 합니다.')));
    return false;
  }

  return true;
}

 

6-2. 디버깅 로그 활용

개발 중에 유용한 디버깅 코드

if (kDebugMode) {
  print('지도 초기화 시작');
  print('현재 위치: ${position.latitude}, ${position.longitude}');
  print('마커 수: ${markers.length}');
}

 

7. 성능 최적화

7-1. 메모리 관리

@override
void dispose() {
  _mapController?.dispose();
  _animationController.dispose();
  super.dispose();
}

 

7-2. 마커 최적화

많은 마커를 표시할 때는 클러스터링을 고려하는게 좋다고 합니다.

// google_maps_cluster_manager 패키지 사용
dependencies:
  google_maps_cluster_manager: ^3.0.0

 

마무리

Flutter에서 Google Maps를 연동하는 과정을 단계별로 살펴보았습니다. 핵심은 다음과 같습니다.

1. Google Cloud Console에서 올바른 API 키 설정
2. AndroidManifest.xml에 API 키와 권한 추가
3. 적절한 패키지 설치 및 권한 처리
4. 사용자 친화적인 UI/UX 구현

 

이 가이드를 따라하면 기본적인 지도 기능부터 모던한 디자인까지 모두 구현할 수 있습니다. 지도 기능은 배달앱, 위치 기반 서비스 등 다양한 앱에서 핵심적인 역할을 하므로, 한 번 익혀두면 매우 유용할 것 같습니다!