지도 시작하기

카카오지도 SDK 를 사용하기 위해서는 카카오 개발자 사이트 을 통해 인증이 필요합니다.

인증 절차

1. 앱 등록

먼저, 카카오 개발자 사이트 에서 지도를 사용 할 앱 등록을 합니다. 자세한 안내는 앱 등록 을 참고합니다.

2. 네이티브 앱 키 추가

카카오 개발자 사이트를 통해 앱 등록을 하면 네이티브 앱 키(App Key) 가 발급됩니다. 발급받은 네이티브 앱 키를 안드로이드의 Application 위치에 아래와 같이 앱키를 추가해서 KakaoMapSdk.init 을 호출합니다. 앱 키 관련 자세한 안내는 앱 키 를 참고합니다. (Application 위치는 권장)

KakaoMapSdk.init(this, "your_app_key");

3. 키 해시 추가

마지막으로, 플랫폼 등록 후 키 해시(Key Hash) 를 추가하면 인증을 위한 절차가 끝납니다. 이와 관련 자세한 안내는 플랫폼 등록 과 키 해시 부분을 참고합니다.


프로젝트 설정

1. 의존성 추가

카카오지도 SDK 는 Maven 저장소에 배포됩니다. AndroidStudio 버전에 따라 build.gradle 또는 settings.gradle 파일에 아래의 원격 저장소를 설정합니다.

repositories {
    maven { url 'https://devrepo.kakao.com/nexus/repository/kakaomap-releases/' }
}

앱 프로젝트 모듈의 build.gradle 에 카카오지도 SDK 에 대한 의존성을 추가합니다.

implementation 'com.kakao.maps.open:android:2.9.5'

2. MapView 추가

지도는 MapView 라는 뷰에서 보여집니다. 지도가 나와야 하는 곳에 MapView 를 아래와 같이 선언합니다.

<com.kakao.vectormap.MapView
    android:id="@+id/map_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

3. 지도 시작 및 KakaoMap 객체 가져오기

MapView.start() 를 호출하여 지도를 시작합니다. Activity 나 Fragment 의 onResume/onPause 시점에 맞춰 MapView.resume(), MapView.pause() 를 꼭 호출해줘야 합니다. 그렇지 않으면 지도의 라이프사이클에 문제가 생겨 알 수 없는 크래쉬가 발생 할 수 있습니다.

정상적으로 인증이 완료되었다면 onMapReady 를 통해 이벤트가 불리며 KakaoMap 객체를 얻어옵니다.

MapView mapView = findViewById(R.id.map_view);
mapView.start(new MapLifeCycleCallback() {
    @Override
    public void onMapDestroy() {
        // 지도 API 가 정상적으로 종료될 때 호출됨 
    }

    @Override
    public void onMapError(Exception error) {
        // 인증 실패 및 지도 사용 중 에러가 발생할 때 호출됨
    }
}, new KakaoMapReadyCallback() {
    @Override
    public void onMapReady(KakaoMap kakaoMap) {
        // 인증 후 API 가 정상적으로 실행될 때 호출됨
    }
});


... (코드생략)

@Override
public void onResume() {
    super.onResume();
    mapView.resume();     // MapView 의 resume 호출
}

@Override
public void onPause() {
    super.onPause();
    mapView.pause();    // MapView 의 pause 호출
}

4. 프로가드 설정(선택)

앱 배포 시, 코드 축소, 난독화, 최적화 를 하는 경우, 카카오지도 SDK를 제외하고 진행하기 위하여 ProGuard 규칙 파일에 다음 코드를 추가합니다.

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

인증 시 에러(MapAuthException)

지도 초기화 과정에서 인증 에러가 발생하면 MapLifeCycleCallback.onMapError() 로 MapAuthException 에러 이벤트가 호출됩니다. 자세한 에러 코드 설명은 여기 에서 확인합니다.

Code Descrption
-1 인증 과정 중 원인을 알 수 없는 에러가 발생한 상태
-2 통신 연결 시도 중 발생하는 에러
-3 통신 연결 중 SocketTimeoutException 에러가 발생한 경우
-4 통신 시도 중 ConnectTimeoutException 에러가 발생한 경우
401 인증 오류. 해당 리소스에 유효한 인증 자격 증명이 없어 요청에 실패한 상태
400 일반적인 오류. 주로 API에 필요한 필수 파라미터와 관련하여 서버가 클라이언트 오류를 감지해 요청을 처리하지 못한 상태입니다.
401 인증 오류. 해당 리소스에 유효한 인증 자격 증명이 없어 요청에 실패한 상태
403 권한 오류. 서버에 요청이 전달되었지만, 권한 때문에 거절된 상태
429 쿼터 초과. 정해진 사용량이나 초당 요청 한도를 초과한 경우
499 통신 실패 오류. 인터넷 연결 상태 확인이 필요한 경우

지도 초기화 시 다양한 설정

지도 초기화 시, KakaoMapReadyCallback 의 아래 함수들을 override 해서 지도의 시작 위치, 지도의 시작 줌 레벨, 지도의 visible 여부, 지도의 MapViewInfo 등을 설정 할 수 있습니다.

MapView mapView = findViewById(R.id.map_view);
mapView.start(new KakaoMapReadyCallback() {
    @Override
    public void onMapReady(KakaoMap kakaoMap) {
        // 인증 후 API 가 정상적으로 실행될 때 호출됨
    }
    
    @Override
    public LatLng getPosition() {
        // 지도 시작 시 위치 좌표를 설정
        return return LatLng.from(37.406960, 127.115587);
    }

    @Override
    public int getZoomLevel() {
        // 지도 시작 시 확대/축소 줌 레벨 설정
        return 15;
    }

    @Override
    public MapViewInfo getMapViewInfo() {
        // 지도 시작 시 App 및 MapType 설정
        return MapViewInfo.from(MapType.NORMAL);
    }

    @Override
    public String getViewName() {
        // KakaoMap 의 고유한 이름을 설정
        return "MyFirstMap";
    }

    @Override
    public boolean isVisible() {
        // 지도 시작 시 visible 여부를 설정
        return true;
    }

    @Override
    public String getTag() {
        // KakaoMap 의 tag 을 설정
        return "FirstMapTag";
    }
});