top of page
  • 작성자 사진jin-author

Android KakaoMap SDK V2 연동 가이드


카카오맵 SDK 이미지


안녕하세요! 오늘은 Android 앱에서 카카오맵 SDK V2를 연동하는 방법을 알려드릴게요. 😊 카카오맵 SDK는 멋진 지도 기능을 쉽게 구현할 수 있게 도와줘요. 아래 내용을 따라 해보세요!


1. SDK 요구 사양


카카오맵 SDK를 사용하기 전에 몇 가지 요구 사양을 확인해야 해요:

  • 안드로이드 플랫폼 버전: 6.0(API level 23) 이상 지원

  • 아키텍쳐: armeabi-v7a, arm64-v8a 지원

  • OpenGL: ES 2.0 이상 지원


2. 카카오 개발자 사이트에서 등록 절차


카카오맵 SDK를 사용하려면 먼저 카카오 개발자 사이트에 앱을 등록해야 해요. 다음 절차를 따라 주세요:

  • 플랫폼 등록: 패키지명, 마켓 URL, 키 해시를 입력해요.

  • 앱 키 발급: 필요한 앱 키를 발급받아요.


카카오 개발자 사이트의 자세한 등록 방법은 여기에서 확인할 수 있어요.


3. 키 해시 추출 방법


카카오맵 SDK를 사용하기 위해서는 디버그 키와 릴리즈 키 해시를 추출하여 등록해야 해요. 등록된 키 해시가 다르면 카카오맵 로딩이 되지 않아요. 플레이스토어에서 서명 키를 관리하는 경우, 빌드할 때 사용하던 키 해시와 달라질 수 있으니, 플레이스토어 서명 키에 대한 키 해시도 발급하여 등록해야 합니다.


터미널에서 디버그, 릴리즈 키 해시 생성

터미널에서 키 해시를 생성하려면 키 해시를 관리하는 키툴(keytool)이 필요합니다. Windows의 경우, Windows 라이브러리를 위한 OpenSSL을 다운로드해야 합니다.

사용 중인 운영체제에 따라 아래 명령어를 입력합니다.


디버그 키 해시

  • Mac:

keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore -storepass android -keypass android | openssl sha1 -binary | openssl base64
  • Windows:

keytool -exportcert -alias androiddebugkey -keystore %USERPROFILE%\.android\debug.keystore -storepass android -keypass android | openssl sha1 -binary | openssl base64

릴리즈 키 해시

  • Mac:

keytool -exportcert -alias <RELEASE_KEY_ALIAS> -keystore <RELEASE_KEY_PATH> | openssl sha1 -binary | openssl base64
  • Windows:

keytool -exportcert -alias <RELEASE_KEY_ALIAS> -keystore <RELEASE_KEY_PATH> | openssl sha1 -binary | PATH_TO_OPENSSL_LIBRARY\bin\openssl base64

Kakao SDK로 디버그, 릴리즈 키 해시 확인

Android SDK의 Utility에서 제공하는 편의 기능 중 getKeyHash() 함수를 사용하여 키 해시 값을 문자열(String)로 구할 수 있습니다.

import com.kakao.sdk.common.util.Utility var keyHash = Utility.getKeyHash(this)

Google Play Console 앱 서명으로 릴리즈 키 해시 확인

Google Play 앱 서명(App Signing)을 사용한다면 직접 릴리즈 키 해시를 생성하지 않고, Google Play Console에서 얻은 SHA-1 인증서 지문(SHA-1 certificate fingerprint)을 Base64로 인코딩하여 사용해야 합니다. 자세한 내용은 앱 서명 사용하기를 참고합니다.

[Google Play Console] > [설정] > [앱 무결성] 메뉴의 [앱 서명키 인증서] 항목에서 [SHA-1 인증서 지문] 값을 복사합니다. 만약 Google Play Console에 접근 권한이 없고 인증서 파일(deployment_cert.der)만 가지고 있다면 터미널에 다음과 같이 입력합니다.

keytool -printcert -file ./deployment_cert.der

SHA-1 인증서 지문 값을 터미널에 다음과 같이 입력합니다.

echo "${PRINTCERT}" | xxd -r -p | openssl base64

4. SDK 설치 및 초기 설정


  • 프로젝트의 build.gradle 파일에 SDK 추가하기:

allprojects {
    repositories {
        mavenCentral()
        jcenter()
        google()
        maven {
            url 'https://devrepo.kakao.com/nexus/content/groups/public/'
        }
    }
}

  • 앱의 build.gradle 파일에 의존성 추가하기:

dependencies { implementation 'com.kakao.maps.open:android:2.9.5' }

  • 앱 키 초기화: 앱 키를 초기화하려면 Application 클래스에서 다음과 같이 설정해야 해요.

MyApplication.java 파일 생성 또는 수정:

import android.app.Application;
import net.daum.mf.map.api.KakaoMapSdk;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        KakaoMapSdk.init(this, "YOUR_APP_KEY");
    }
}

5. 기본적인 카카오맵 사용법

이제 실제로 카카오맵을 사용해 볼게요. 먼저 지도를 초기화하는 코드를 작성해야 해요.


  • activity_main.xml 파일 수정:

<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <net.daum.mf.map.api.MapView
        android:id="@+id/map_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

</RelativeLayout>

import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
import net.daum.mf.map.api.MapView;
import net.daum.mf.map.api.MapPoint;
import net.daum.mf.map.api.MapPOIItem;
import net.daum.mf.map.api.MapLifeCycleCallback;
import net.daum.mf.map.api.KakaoMap;
import net.daum.mf.map.api.KakaoMapReadyCallback;
import net.daum.mf.map.api.LatLng;
import net.daum.mf.map.api.MapViewInfo;
import net.daum.mf.map.api.MapType;

public class MainActivity extends AppCompatActivity {

    private MapView mapView;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        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가 정상적으로 실행될 때 호출됨
                addMarker(kakaoMap);
            }
            
            @Override
            public LatLng getPosition() {
                // 지도 시작 시 위치 좌표를 설정
                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";
            }
        });
    }

    private void addMarker(KakaoMap kakaoMap) {
        MapPOIItem marker = new MapPOIItem();
        marker.setItemName("Default Marker");
        marker.setTag(0);
        marker.setMapPoint(MapPoint.mapPointWithGeoCoord(37.537229, 127.005515));
        marker.setMarkerType(MapPOIItem.MarkerType.BluePin); // 마커타입 설정
        marker.setSelectedMarkerType(MapPOIItem.MarkerType.RedPin); // 선택 시 마커타입 설정
        kakaoMap.addPOIItem(marker);
    }

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

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

이제 앱을 실행하면 카카오맵이 보일 거예요! 🎉


6. ProGuard 설정 추가(선택)


프로가드를 사용할 때 ProGuard 설정을 추가해 줘야 해요. ProGuard를 사용하여 앱의 크기를 줄이고 보안을 강화할 수 있어요.

ProGuard 설정 파일에 다음을 추가해 주세요:

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

7. 개발 주의사항


지도 API 의 라이프사이클

  1. 지도 API 의 라이프사이클은 start, resume, pause, finish 단계가 있고 MapView 의 함수로 되어 있습니다. 지도를 시작하는 시점에 start() 를 호출하면 인증과정을 거친 뒤 지도가 실행됩니다.

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

  3. 기본적으로 종료는, MapView 가 포함 된 Activity 가 종료될 때 finish 가 동작합니다. 그 외 지도 종료가 필요할 때는, 사용자가 필요한 특정 시점에는 명시적으로 finish 를 꼭 호출해줘야 합니다.

  4. Activity 가 종료되면서 지도가 finish 되는 것을 막을 때는, setFinishManually() 를 true 로 설정하고 사용자가 원하는 시점에 finish() 를 호출합니다.


로고 표시 정책

카카오지도 API 사용 시 기본적으로 지도의 우하단에 로고가 표시 됩니다. 이에 대한 변경이나 가려짐은 허용되지 않습니다. 앱의 UI 구성상 로고가 지속적으로 가려지는 경우, 아래와 같이 로고의 위치를 옮길 수 있습니다.

kakaoMap.getLogo().setPosition(MapGravity, xPx, yPx);

이제 카카오맵 SDK를 사용할 수 있어요.

여기까지 따라 오시느라 수고 많으셨어요! 혹시 더 궁금한 점이 있으면 언제든지 질문해 주세요.


조회수 44회

Comments


bottom of page