kakao_map_sdk 1.2.2 copy "kakao_map_sdk: ^1.2.2" to clipboard
kakao_map_sdk: ^1.2.2 copied to clipboard

Published 3 days ago • verified publisheryhs.kr
SDKFlutter
PlatformAndroidiOSweb
→

Metadata

A Flutter plugin that provides a native platform-based Kakao Map(Korean Map Service).

More...

kakao_map_sdk #

Pub Version Pub Monthly Downloads Pub Points Pub Popularity

Kakao Map SDK는 Flutter 환경에서 카카오 지도을 사용할 수 있도록 하는 패키지입니다!

Android iOS Web(Experimental)
SDK 6.0(API 23) 이상 iOS 13 이상 Flutter Web과 동일 환경
armeabi-v7a, arm64-v8a 아키텍쳐 지원
(x86, x64 아키텍쳐 미호환)
OpenGL ES 2.0 이상
인터넷 권한 필요

1. Getting Started #

Flutter에서 카카오 지도를 이용하기 위해 카카오 개발자 사이트에서 앱 등록을 해야합니다.
앱 등록을 마치면 카카오 지도를 사용할 수 있는 네이티브 앱 키(App Key) 를 발급받을 수 있습니다.

앱 키는 아래와 같이 KakaoMapSdk.instance.initialize 함수를 호출하여 클라이언트를 인증하실 수 있습니다.

import 'package:kakao_map_sdk/kakao_map_sdk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await KakaoMapSdk.instance.initialize('KAKAO_API_KEY');
  runApp( ... )
}

Android Platform #

안드로이드 환경에서 카카오맵을 이용하기 위해서는 아래에 서술된 추가 설정이 필요합니다.

  1. AndroidManifest.xml에 아래와 같이 인터넷 권한과 위치 권한을 제공해야 합니다.

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

  2. 애플리케이션을 배포하는 경우, Kakao Map SDK는 코드 축소, 난독화, 최적화 대상에서 제외해야 합니다.
    android > app > proguard-rules.pro 파일을 아래와 같이 설정주십시요.

    -keep class com.kakao.vectormap.** { *; }
-keep interface com.kakao.vectormap.**

  3. 안드로이드에서 카카오지도를 이용하려면 키해시 인증 과정이 필요합니다.
    자세한 내용은 플랫폼 등록과 키 해시을 읽어주세요.

    Flutter Kakao Maps 플러그인은 디버깅, 릴리즈 해시키를 제공받을 수 있는 함수를 제공하고 있습니다.

    await KakaoMapSdk.instance.hashKey();

    안드로이드 플랫폼 외 다른 플랫폼에서 함수를 호출하면 null을 반환합니다.

Web Environment #

웹 환경에서 카카오맵을 이용하기 위해서는 아래에 서술된 추가 설정이 필요합니다.
아래에 기재된 소스코드를 web/index.html에 추가해주세요.

...
<head>
  ...
  <script type="text/javascript" src="https://dapi.kakao.com/v2/maps/sdk.js?appkey=<JavaScript 키>"></script>
  ...
</head>
...

<JavaScript 키> 는 <네이티브 키>와 다른 키로 카카오 개발자 사이트에서 앱 등록을 마치면 발급받을 수 있습니다.

2. Add MapView Widget #

지도를 담고 있는 위젯(Widget)은 아래와 같이 KakaoMap 함수를 호출하여 사용할 수 있습니다.

Widget build(BuildContext context) {
  return Scaffold(
    body: KakaoMap(
      option: const KakaoMapOption(
        position: LatLng(기본 위치),
        zoomLevel: 16,
        mapType: MapType.normal,
      ),
      onMapReady: (KakaoMapController controller) {
        print("카카오 지도가 정상적으로 불러와졌습니다.");
      },
    ),
  );
}

option 매게변수에는 초기화 과정에서 기본 값(KakaoMapOption)을 설정할 수 있습니다.
아무 문제 없이 지도를 불러온다면, onMapReady 매개변수에 담긴 함수가 호출됩니다.
함수 매개변수에는 지도를 관리하기 위한 컨트롤러(KakaoMapController)가 입력됩니다.

3. Move the Camera to show the map #

Kakao Map SDK는 컨트롤러(KakaoMapController)를 이용하여 카메라의 위치를 조회하거나, 카메라의 위치를 이동할 수 있습니다. 카메라의 위치는 getCameraPosition 함수를 이용하여 불러올 수 있습니다.

Future<void> getCameraPosition(KakaoMapController controller) async {
  final cameraPosition = await kakaoMap.getCameraPosition();
  print(cameraPosition.zoomLevel); // 카메라의 축적비입니다. 값이 높을 수록 지도에 보여지는 건물은 줄어들지만, 건물을 상세히 확인하실 수 있습니다.  
  print(cameraPosition.position); // 카메라의 위치입니다. WGS84(위도, 경도) 형식으로 불러옵니다. 
  print(cameraPosition.rotationAngle); // 카메라의 회전 각도를 불러옵니다.
}

카메라의 위치는 moveCamera 함수와 CameraUpdate 객체를 이용하여 움직일 수 있습니다. 자세한 내용은 CameraUpdate Reference를 참고해주세요.

Future<void> setCameraPosition(KakaoMapController controller) async {
  final location = LatLng(37.394776, 127.11116);
  final cameraUpdate = CameraUpdate.newCenterPosition(location);
  await controller.moveCamera(cameraUpdate);
}

moveCamera 함수에는 animation 인수를 제공할 수 있으며 지정된 밀리초(ms)동안 지도를 비추는 카메라가 이동합니다.

Future<void> setCameraPositionWithAnimation(KakaoMapController controller) async {
  final location = LatLng(37.394776, 127.11116);
  final cameraAnimation = const CameraAnimation(5000); // 5초
  final cameraUpdate = CameraUpdate.newCenterPosition(location);
  await controller.moveCamera(cameraUpdate, animation: cameraAnimation);
}

4. Write Overlay(Grapic Element) to map #

Kakao Map SDK는 사용자에게 표현하기 위한 다양한 그래픽 요소(오버레이 기능)를 제공하고 있습니다.
다양한 그래픽 요소는 KakaoMapController를 통해 제어하실 수 있습니다.

4-1. Poi (Label) #

특정 위치에 정보를 제공하기 위한 이미지 또는 텍스트를 제공합니다.
Poi에는 사용하는 방법에 따라 3가지로 구분할 수 있습니다.

  • Poi: 특정 위치에 이미지나 텍스트로 정보를 표시 할 수 있습니다.
  • Lod-Poi: LOD(Level of Detail)이 적용되어 한 번에 많은 양의 Poi를 지도에 표시할 수 있습니다. Lod-Poi에는 회전, 이동 기능이 없습니다.
  • PolylineText: 선형으로 된 텍스트를 표현할 때 사용합니다.
// Poi
controller.labelLayer.addPoi(
  const LatLng(위도, 경도),
  style: PoiStyle(
    icon: KImage.fromAsset("assets/image/location.png", 68, 100),
  )
)

// Lod Poi
controller.lodLabelLayer.addLodPoi(
  const LatLng(위도, 경도),
  style: PoiStyle(
    icon: KImage.fromAsset("assets/image/location.png", 68, 100),
  )
)

// Polyline Text
// "휘어지는 글씨"라는 문구를 담고 있는 선형 텍스트를 만듭니다.
controller.labelLayer.addPolylineText(
  "휘어지는 글씨",
  const [
    LatLng(위도, 경도),
    ...
  ],
  style: PolylineTextStyle(28, Colors.blue)
);

4-2. Shape #

Android iOS
지도에 선분이 담긴 도형을 제공합니다.
Kakao Map SDK에서 제공하는 도형은 두 가지가 있습니다. * PolylineShape: 선형으로 된 도형입니다. * PolygonShape: 선형 안에 내용물이 채워진 형태의 도형입니다.

도형을 구성하는 모델좌표계를 구성하는 방법은 2가지 형태가 있습니다.

  • DotPoints: 특정 좌표(LatLng)을 기준으로 하여 상대 좌표를 이용하여 도형을 구성하는 방식
  • MapPoints: 지도의 위도, 경도(LatLng)를 이용하여 좌표들의 꼭지점을 이어서 도형을 구성하는 방식
// DotPoints (RectanglePoint)를 이용하여 가로, 세로 300 크기의 선형(굵기: 10)이 있는 사각형
controller.shapeLayer.addPolylineShape(
  RectanglePoint(300, 300, const LatLng(위도, 경도)),
  PolylineStyle(Colors.green, 10.0),
  PolylineCap.round
);

// DotPoints (CirclePoint)를 이용하여 반지름이 200 크기인 원형
controller.shapeLayer.addPolygonShape(
  CirclePoint(200, const LatLng(위도, 경도)),
  PolygonStyle(Colors.green)
);

4-3. Route #

Android iOS
지도에 다양한 선분이 담긴 길찾기 경로 모양의 도형을 제공합니다. 
// 두께가 10이고, 색상은 노란색인 경로 도형을 그립니다.
controller.routeLayer.addRoute(const [
    LatLng(위도, 경도),
    ...
  ],
 RouteStyle(
    Colors.yellow, 10,
  )
);

Route 기능에는 일정 간격마다 이미지를 삽입하는 패턴 효과를 제공할 수 있습니다. 패턴 효과는 RouteStyle.withPattern 생성자를 이용하거나, pattern 인수를 제공하여 정의할 수 있습니다.

// 6px 마다 원형의 도형의 패턴을 가지고 있는 스타일을 정의합니다.
RouteStyle.withPattern(
  RoutePattern(
    KImage.fromAsset("assets/image/circle.png", 30, 30), 6
  )
)

4-4. DimScreen #

DimScreen은 지도 전체를 특정 색으로 가리는 객체입니다. Polygon 도형을 추가하여 특정 부분을 지정된 색상으로 출력할 수 있습니다.

// 지도를 투명도 80%를 가지고 있는 회색으로 덮습니다.
await controller.dimScreen.setColor(Colors.grey.withAlpha(80));
await controller.dimScreen.setVisible(true);

// 특정 좌표에 있는 도형은 파란 색상의 테두리를 강조하고, 도형 안 색상을 걷어냅니다.
final polygonStyle = PolygonStyle(
  Colors.white.withAlpha(0), 
  strokeWidth = 3.0,
  strokeColor = Colors.blue
);
await controller.dimScreen.addPolygonShape(
  MapPoint(...), polygonStyle
)

4-5. Tracking #

Tracking은 지도에 나타난 Poi가 Poi.move() 함수 등에 의해 이동하게 되었을 때, 지도를 바라보고 있는 카메라가 이동하는 Poi를 이동하도록 하는 기능입니다. 한 번에 하나의 Poi만 추적을 할 수 있으며, 다른 Poi를 추적하려면 stop 함수를 호출하여 추적을 멈춘 후 다른 Poi를 설정해주시면 됩니다.

// Label Controller를 이용하여 추적시킬 Poi를 하나 만든 다음, Tracking Controller에 추적할 Poi를 설정합니다.
final poi = await controller.labelLayer.addPoi(...);
controller.tracking.poi = poi;

// start 함수를 이용하여 Poi를 추적할 수 있습니다. 
// 반대로 멈추고 싶다면 stop 함수를 이용하시면 됩니다.
await controller.tracking.start();

5. Detect event on map. #

지도에서 발생한 이벤트는 대부분 KakaoMap 위젯 객체에 전달되며 함수 이벤트는 각 인수로 호출됩니다. 각 인수별 이벤트 용도는 KakaoMap Widget API Reference를 확인해주세요.

예를 들어 onCameraMoveEnd 인수에 함수를 제공하여 카메라가 이동을 마칠 때 메시지를 호출받을 수 있습니다.

KakaoMap(
  option: const KakaoMapOption(...),
  onMapReady: ... // 지도를 불러오면 함수가 호출됩니다.
  onPoiClick: (LabelController labelController, Poi poi) {
    print("Poi (${poi.id})가 눌렸습니다!");
  },
  onCameraMoveEnd: (CameraPosition position, GestureType gestureType) {
    print("카메라가 위도 ${position.position.latitude}도, 경도 ${position.position.longitude}도로 이동하였습니다.");
  },
);

6. Sample Project #

아래의 샘플 프로젝트을 확인하여 카카오맵을 Flutter에 구현한 애플리케이션을 확인해보세요!

7. (Expermential) Web #


Kakao Map SDK는 Web 플랫폼을 지원합니다.
본 플러그인은 네이티브를 중심으로 개발되었기 때문에 웹 SDK도 네이티브 환경에 알맞게 포팅 작업을 진행하였습니다.

네이티브에 있는 기능과 달리 아래에 서술한 기능은 웹 환경에서 다르게 작동하거나 지원하지 않습니다.

  • 카메라 회전, 틸트: Kakao Map Web SDK는 카메라 회전 또는 틸트 기능을 제공하지 않습니다.
    따라서 카메라 회전 각도, 틸트 각도를 주어져도 무시됩니다.
  • LOD(Level Of Detail) 기능: 웹 환경에서 LOD 기능은 적용되지 않은 상태로 작동합니다.
    예를 들어 웹 환경에서 LOD Poi는 LOD가 적용되지 않은 Poi와 동일하게 작동합니다.
  • 각 컨트롤러(Layer) 기능: 웹 환경에서 Layer에 적용한 설정은 적용되지 않습니다.
  • Dim Screen: 웹 환경에서 지도 전체를 특정 색상으로 덮는 Dim Screen 기능은 제공하지 않습니다.
  • Polyline Text: 웹 환경에서 휘어진 텍스트 오버레이는 지원하지 않습니다.
  • Route Pattern: 웹 환경에서 경로에 패턴을 찍는 기능은 지원하지 않습니다.
    RouteStyle 객체에 pattern가 입력되면 카카오맵 웹 환경과 동일한 점선으로 대체됩니다.
    웹 환경 내 경로에 패턴이 적용된 이미지
  • 웹 환경에서 canShowPosition 함수의 zoomLevel 매개변수는 작동하지 않습니다.
    사용자에게 보여주는 시점에서 주어진 배열의 좌표만 보여지는 여부를 반환합니다.
  • 웹 환경에서 buildingHeightScale 개체는 항상 0.0이며 수정할 수 없습니다.
  • 웹 환경에서 Poi와 다른 도형 간 위치를 공유하는 Poi.addShareTransfromWithShape, Poi.removeShareTransfromWithShape는 지원하지 않습니다.

기재한 기능 외에도 일부 기능은 지원하지 않을 수도 있습니다.
네이티브 환경을 중점으로 개발된 플러그인이므로 양해부탁드립니다.

웹 환경 내 사용 방법은 첫 번째 섹션(Getting Started) 부분을 확인해주세요.

8. Collaboration / Report Issue #

Kakao Map SDK 패키지의 기여는 항상 환영합니다.
기능 개선, 버그 해결 등의 작업하신 내용은 Pull Reuqest(PR) 해주시면, 최대한 빠른 시간 내에 검증을 진행하고 병합 해드리겠습니다.

질문, 버그 제보도 언제든지 환영합니다.
이용 중에 문제를 겪으셨다면 Issue를 열어주세요. 내용을 확인하는 대로 도움드리도록 하겠습니다

← Metadata

7
likes
155
points
688
downloads

Publisher

verified publisheryhs.kr

Weekly Downloads

Metadata

A Flutter plugin that provides a native platform-based Kakao Map(Korean Map Service).

Repository (GitHub)
View/report issues

Documentation

API reference

License

BSD-3-Clause (license)

Dependencies

collection, flutter, flutter_web_plugins, plugin_platform_interface, uuid, web

More

Packages that depend on kakao_map_sdk

Packages that implement kakao_map_sdk

Back