Kakao Map SDK는 Flutter 환경에서 카카오 지도을 사용할 수 있도록 하는 패키지입니다!
시작하기 · 플랫폼 지원 범위 · API Reference · 변경 이력
| Android | iOS | Web(Experimental) |
|---|---|---|
SDK 6.0(API 23) 이상 |
iOS 13 이상 |
Flutter Web과 동일 환경 |
armeabi-v7a, arm64-v8a 아키텍쳐 지원( x86, x64 아키텍쳐 미호환) |
||
OpenGL ES 2.0 이상 |
||
| 인터넷 권한 필요 |
Flutter에서 카카오 지도를 이용하기 위해 카카오 개발자 사이트에서 앱 등록을 해야합니다.
앱 등록을 마치면 카카오 지도를 사용할 수 있는 네이티브 앱 키(App Key) 를 발급받을 수 있습니다.
먼저 프로젝트에 패키지를 추가합니다.
flutter pub add kakao_map_sdk앱 키는 아래와 같이 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( ... )
}안드로이드 환경에서 카카오맵을 이용하기 위해서는 아래에 서술된 추가 설정이 필요합니다.
-
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" />
-
애플리케이션을 배포하는 경우, Kakao Map SDK는 코드 축소, 난독화, 최적화 대상에서 제외해야 합니다.
android > app > proguard-rules.pro파일을 아래와 같이 설정주십시요.-keep class com.kakao.vectormap.** { *; } -keep interface com.kakao.vectormap.**
-
안드로이드에서 카카오지도를 이용하려면 키해시 인증 과정이 필요합니다.
자세한 내용은 플랫폼 등록과 키 해시을 읽어주세요.Flutter Kakao Maps 플러그인은 디버깅, 릴리즈 해시키를 제공받을 수 있는 함수를 제공하고 있습니다.
await KakaoMapSdk.instance.hashKey();
안드로이드 플랫폼 외 다른 플랫폼에서 함수를 호출하면
null을 반환합니다.
웹 환경에서 카카오맵을 이용하기 위해서는 아래에 서술된 추가 설정이 필요합니다.
아래에 기재된 소스코드를 web/index.html에 추가해주세요.
...
<head>
...
<script type="text/javascript" src="https://dapi.kakao.com/v2/maps/sdk.js?appkey=<JavaScript 키>"></script>
...
</head>
...<JavaScript 키> 는 <네이티브 키>와 다른 키로 카카오 개발자 사이트에서 앱 등록을 마치면 발급받을 수 있습니다.
지도를 담고 있는 위젯(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)가 입력됩니다.
Kakao Map SDK는 컨트롤러(KakaoMapController)를 이용하여 카메라의 위치를 조회하거나, 카메라의 위치를 이동할 수 있습니다.
카메라의 위치는 getCameraPosition 함수를 이용하여 불러올 수 있습니다.
Future<void> getCameraPosition(KakaoMapController controller) async {
final cameraPosition = await controller.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);
}Kakao Map SDK는 사용자에게 표현하기 위한 다양한 그래픽 요소(오버레이 기능)를 제공하고 있습니다.
다양한 그래픽 요소는 KakaoMapController를 통해 제어하실 수 있습니다.
특정 위치에 정보를 제공하기 위한 이미지 또는 텍스트를 제공합니다.
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)
);| 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)
);| 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
)
)DimScreen은 지도 전체를 특정 색으로 가리는 객체입니다.
Polygon 도형을 추가하여 특정 부분을 지정된 색상으로 출력할 수 있습니다.
// 지도를 투명도 80%를 가지고 있는 회색으로 덮습니다.
await controller.dimScreen.setColor(Colors.grey.withAlpha(80));
await controller.dimScreen.setVisible(true);
// 특정 좌표에 있는 도형은 파란 색상의 테두리를 강조하고, 도형 안 색상을 걷어냅니다.
final polygonStyle = PolygonStyle(
Colors.transparent,
strokeWidth: 3.0,
strokeColor: Colors.blue,
);
await controller.dimScreen.addPolygonShape(
MapPoint(...),
polygonStyle,
);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();지도에서 발생한 이벤트는 대부분 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}도로 이동하였습니다.");
},
);아래의 샘플 프로젝트을 확인하여 카카오맵을 Flutter에 구현한 애플리케이션을 확인해보세요!
Kakao Map SDK는 Web 플랫폼을 지원합니다. v1.3.0부터 PolylineText와 DimScreen도 동일한 Dart API로 사용할 수 있습니다.
Web 구현은 Kakao Maps JavaScript SDK가 제공하는 기능 안에서 네이티브 API의 구조를 맞춥니다.
네이티브에 있는 기능과 달리 아래에 서술한 기능은 웹 환경에서 다르게 작동하거나 지원하지 않습니다.
- 카메라 회전, 틸트: Kakao Map Web SDK는 카메라 회전 또는 틸트 기능을 제공하지 않습니다.
따라서 카메라 회전 각도, 틸트 각도를 주어져도 무시됩니다. - LOD(Level Of Detail) 기능: 웹 환경에서 LOD 기능은 적용되지 않은 상태로 작동합니다.
예를 들어 웹 환경에서LOD Poi는 LOD가 적용되지 않은Poi와 동일하게 작동합니다. - 레이어와 LOD 설정: 일부 레이어 경쟁·정렬 설정은 네이티브와 동일하게 적용되지 않으며, LodPoi는 일반 Poi처럼 동작합니다.
- Route Pattern: 웹 환경에서 경로에 패턴을 찍는 기능은 지원하지 않습니다.
RouteStyle객체에pattern가 입력되면 카카오맵 웹 환경과 동일한 점선으로 대체됩니다.웹 환경 내 경로에 패턴이 적용된 이미지
- 웹 환경에서
canShowPosition함수의zoomLevel매개변수는 작동하지 않습니다.
사용자에게 보여주는 시점에서 주어진 배열의 좌표만 보여지는 여부를 반환합니다. - 웹 환경에서
buildingHeightScale개체는 항상0.0이며 수정할 수 없습니다. - 웹 환경에서 Poi와 다른 도형 간 위치를 공유하는
Poi.addShareTransfromWithShape,Poi.removeShareTransfromWithShape는 지원하지 않습니다.
플랫폼별 세부 차이와 검증 결과는 플랫폼 지원 범위에서 확인하세요.
기능 개선이나 버그 수정은 Pull Request로 제안할 수 있습니다. 변경 사항에는 적용 대상 플랫폼과 검증 방법을 함께 작성하고, 가능하면 관련 테스트를 포함해 주세요.
패키지 사용 중 문제가 발생했다면 Issue tracker에 양식을 준수하여 등록해주십시요.
보안상 민감한 정보는 공개 이슈와 로그에 포함하지 말고 gunyu1019@yhs.kr로 보내주세요. 앱 키처럼 재발급 가능한 비밀값은 이메일에서도 원문을 보내기보다 필요한 부분만 마스킹하여 전달해 주세요.