inavi_map_flutter

iNavi Maps SDK를 Flutter에서 사용할 수 있게 해주는 플러그인입니다. 단일 Dart API로 Android(Kotlin)·iOS(Swift) 네이티브 지도를 표시하고 제어합니다.

APP KEY 필요 — SDK 인증을 위해 iNavi에서 발급한 APP KEY를 양 플랫폼에 설정해야 합니다. iMPS Console에서 APP 생성 후 키를 발급받으세요.

Features

InaviMapsView를 통한 네이티브 지도 렌더링 (Android PlatformView / iOS UiKitView)
이벤트 기반 인증 결과 스트림 (InaviMapsSdk.instance.onInit)
카메라 제어: animateCamera · moveCamera · getCameraPosition · bounds fit
선언형 도형 API: 마커 · 폴리라인 · 폴리곤 · 원 · InfoWindow · 클러스터 · 경로(Route)
지도 이벤트: 클릭 · 롱클릭 · 더블클릭 · 카메라 이동 · 도형/마커 탭
사용자 위치 추적(UserTrackingMode)과 현위치 아이콘 커스터마이징
좌표계 변환(WGS84 · KATEC · UTM-K · TM · GRS80)과 화면↔지도 좌표 Projection
지도 옵션: 제스처 · UI 컨트롤 · 실내지도 · 라벨 다국어 · 커스텀 스타일

Requirements

Platform	Minimum version
Android	API 23 (Android 6.0)
iOS	15.0
Flutter	>= 3.3.0
Dart	^3.11.5

Installation

pubspec.yaml에 의존성을 추가합니다.

dependencies:
  inavi_map_flutter: ^1.0.0

설치:

flutter pub get

Platform Setup

Android

1. Maven repository 등록

프로젝트의 android/settings.gradle.kts(또는 project-level build.gradle)에 iNavi Maven repository를 추가합니다.

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://repo.inavi.com/artifactory/maps") }
    }
}

2. APP KEY 설정

android/app/src/main/AndroidManifest.xml의 <application> 요소 안에 추가합니다.

<application ...>
    <meta-data
        android:name="com.inavi.mapsdk.AppKey"
        android:value="YOUR_INAVI_APP_KEY" />
</application>

위치 기능을 사용하는 경우 권한을 함께 선언합니다.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

iOS

1. APP KEY 설정

ios/Runner/Info.plist에 추가합니다.

<key>iNaviAppKey</key>
<string>YOUR_INAVI_APP_KEY</string>

위치 기능을 사용하는 경우 사용 목적 설명을 추가합니다.

<key>NSLocationWhenInUseUsageDescription</key>
<string>지도에서 현재 위치를 표시하기 위해 위치 권한이 필요합니다.</string>

2. CocoaPods 설치

inavi-maps-sdk는 CocoaPods 공식 trunk에서 다운로드됩니다. 별도 source 선언이 필요 없습니다.

cd ios
pod install --repo-update

Usage

1. 패키지 import

import 'package:inavi_map_flutter/inavi_map_flutter.dart';

2. 인증 이벤트 구독

인증은 InaviMapsView가 처음 렌더링될 때 자동으로 시작됩니다. 지도 표시 전에 root 위젯에서 onInit을 구독하세요.

class _MyAppState extends State<MyApp> {
  StreamSubscription<InitEvent>? _initSub;

  @override
  void initState() {
    super.initState();
    _initSub = InaviMapsSdk.instance.onInit.listen((event) {
      switch (event) {
        case AuthSuccess():
          // SDK 인증 성공 — 지도 API 호출 가능
          break;
        case AuthFailure(:final errorCode, :final errorMessage):
          debugPrint('인증 실패: $errorCode / $errorMessage');
        case MapReady(:final viewId):
          debugPrint('지도 $viewId 표출 준비 완료');
      }
    });
  }

  @override
  void dispose() {
    _initSub?.cancel();
    super.dispose();
  }
}

3. 지도 표시

InaviMapsView(
  onMapCreated: (InaviMapsController controller) {
    // 지도 준비 완료 — controller로 카메라·도형 제어
  },
)

4. 카메라 제어

await controller.animateCamera(
  CameraUpdate.newCameraPosition(
    const CameraPosition(
      target: Coordinate(wgsLat: 37.5665, wgsLon: 126.9780),
      zoom: 14,
    ),
  ),
  duration: const Duration(milliseconds: 500),
  animation: CameraAnimation.easing,
);

5. 마커 추가

await controller.updateMarkers({
  const Marker(
    markerId: 'marker_1',
    position: Coordinate(wgsLat: 37.5665, wgsLon: 126.9780),
  ),
});

// 마커 탭 이벤트 구독
controller.onMarkerTap.listen((event) {
  debugPrint('marker tapped: ${event.markerId}');
});

6. 지도 클릭 이벤트

controller.onMapClick.listen((event) {
  debugPrint('tapped at ${event.coordinate}');
});

공식 iNavi Maps SDK 가이드에 문서화된 API만 사용하세요. 문서화되지 않은 내부 심볼은 예고 없이 변경될 수 있으며 지원되지 않습니다.

Example App

example/ 디렉터리에 APP KEY 설정, 인증, 지도 표시, 카메라, 도형, 위치 추적, 좌표계 변환 등을 다루는 전체 통합 예제가 포함되어 있습니다.

cd example
flutter pub get
flutter run

Documentation

iNavi Maps SDK 가이드 — Android / iOS
iNavi Maps SDK API references — Android / iOS

License

자세한 내용은 LICENSE를 참고하세요.