[JAVA][Android] 카카오 지도 API Android v2 사용하기

안녕하세요.

오늘은 카카오 지도 API를 사용하는 방법에 대해 알아보겠습니다.

카카오 지도 API는 안드로이드용으로 v1과 v2 가 있는데, 이 글은 v2를 기준으로 작성되었습니다.

 

카카오 지도 API를 사용하기 전에 요구사양을 확인해 주세요.

 

1. 카카오 개발자 사이트에 앱 등록

https://developers.kakao.com/

Kakao Developers

 

카카오 API를 사용하기 위해서는 위 링크의 카카오 개발자 사이트에 로그인 후 화면 상단에 있는 [내 애플리케이션] 메뉴에서 API를 사용할 앱을 등록해야 합니다.

 

 

애플리케이션 추가하기 버튼을 클릭하면 나오는 화면에서, 필수 입력사항인 앱 이름, 사업자명, 카테고리를 입력하고 아래 체크박스에 체크한 후 저장 버튼을 클릭하여 앱을 등록해 주세요.

 

등록된 앱을 클릭하면 다음과 같이 앱 키를 확인할 수 있습니다.

 

여기서 네이티브 앱 키를 사용할 것입니다.

2.  안드로이드 플랫폼 등록하기

이제 위 이미지의 플랫폼 설정하기를 클릭하여 안드로이드 플랫폼 등록을 진행해 주세요.

 

만들고 있는 프로젝트에서 패키지명을 확인하여 입력하고, 본인의 키해시를 입력하여 저장합니다.

저는 앱을 구글 플레이에 등록하지 않았기 때문에 마켓 URL은 없음으로 설정하였습니다.

 

** 키 해시받는 법

키 해시(Key Hash)란 인증서(Certificate)의 인증서 지문 값(Certificate fingerprints)을 해시(hash)한 값으로, 악성 앱인지 판별하는 데 사용됩니다. 카카오 API를 호출하면 카카오 API 서버가 요청 헤더에 추가된 키 해시값과 카카오 플랫폼에 등록한 값이 일치하는지 확인합니다. 키 해시는 디버그 키 해시(Debug key hash)와 릴리즈 키 해시(Release key hash) 두 가지가 있습니다.

• 디버그 키 해시: 프로젝트를 처음 생성하거나 디버그 할 때, 안드로이드 스튜디오에서 개발 환경에 맞게 자동으로 생성되는 디버그 인증서에서 해시(hash)한 값입니다.
• 릴리즈 키 해시: 앱 스토어에 앱을 배포하기 위해 생성한 릴리즈 인증서로부터 해시한 값입니다.

공식 홈페이지에는 키 해시를 알아내기 위한 아래 3가지의 방법이 소개되어 있습니다. 

1. 터미널에서 디버그, 릴리즈 키 해시 생성
2. kakao SDK로 디버그, 릴리즈 키 해시 확인
3. google play console 앱 서명으로 릴리즈 키 해시 확인

이 글에서는 첫 번째 방법인 터미널을 이용해서 디버그 키 해시를 확인하였습니다. 개발 중에는 디버그 키 해시를 입력해서 사용하지만, 추후 앱을 릴리즈 한 후에는 릴리즈 키 해시를 입력해야 API가 정상 동작합니다.

 

터미널을 열고, 사용 중인 운영체제에 따라 아래 명령어를 입력하면 키 해시를 확인할 수 있습니다.

#1. Mac에서 디버그 키 해시 구하기
keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore -storepass android -keypass android | openssl sha1 -binary | openssl base64

#2. Windows에서 디버그 키 해시 구하기
keytool -exportcert -alias androiddebugkey -keystore %USERPROFILE%\.android\debug.keystore -storepass android -keypass android | openssl sha1 -binary | openssl base64

 

윈도의 경우, OpenSSL을 다운로드하여야 할 수 있습니다.

3.  프로젝트 설정

 1. 매니페스트 설정

우선 API를 사용하기 위해 매니페스트에 인터넷 사용 권한을 설정합니다.

<!-- 인터넷 사용 권한 설정-->
    <uses-permission android:name="android.permission.INTERNET" />

 

이제 매니페스트에 <applicion> 안에 앞에서 확인했던 네이티브 앱 키를 다음과 같이 추가해 줍니다.

<application
    ... 
    <meta-data
        android:name="com.kakao.vectormap.APP_KEY"
        android:value="${APP_KEY}"/>   
        // 네이티브 앱 키 넣기 ex) android:value="bd58~~~~~~~~"
</application>

2. 의존성 추가

AndroidStudio 버전에 따라 build.gradle 또는 settings.gradle 파일에 아래의 원격 저장소를 설정합니다. 저는 settings.gradle 파일을 사용하였습니다.

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url 'https://devrepo.kakao.com/nexus/content/groups/public/' }
    }
}

 

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

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

 

 

4. 레이아웃에 MapView 추가하기

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

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <com.kakao.vectormap.MapView
        android:id="@+id/map_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />
</androidx.constraintlayout.widget.ConstraintLayout>

 

5. 액티비티에서 지도 시작 및 KakaoMap 객체 가져오기

import androidx.annotation.NonNull;
import androidx.appcompat.app.AppCompatActivity;

import android.os.Bundle;
import android.util.Log;

import com.kakao.vectormap.KakaoMap;
import com.kakao.vectormap.KakaoMapReadyCallback;
import com.kakao.vectormap.MapLifeCycleCallback;
import com.kakao.vectormap.MapView;

public class MainActivity extends AppCompatActivity {
    MapView mapView;
    KakaoMap kakaoMap;

    @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가 정상적으로 종료될 때 호출
                Log.d("KakaoMap", "onMapDestroy: ");
            }

            @Override
            public void onMapError(Exception error) {
                // 인증 실패 및 지도 사용 중 에러가 발생할 때 호출
                Log.e("KakaoMap", "onMapError: ", error);
            }
        }, new KakaoMapReadyCallback() {
            @Override
            public void onMapReady(@NonNull KakaoMap map) {
                // 정상적으로 인증이 완료되었을 때 호출
                // KakaoMap 객체를 얻어 옵니다.
                kakaoMap = map;
            }
        });
    }
}

 

이렇게 하면 카카오지도 API 가 실행되는 것을 확인할 수 있습니다.

혹시 API가 정상적으로 작동하지 않는다면 Log에 찍힌 에러코드를 확인하여 문제를 해결해야 합니다.

각 에러코드에 대한 설명은 아래 카카오 지도 API 공식 문서를 통해 확인할 수 있습니다.

https://apis.map.kakao.com/android_v2/docs/getting-started/quickstart/#인증-시-에러 mapauthexception

 

오늘은 카카오 지도를 앱에 띄우는 것까지 진행해 보았습니다.

다음 주에는 기기의 현재 위치를 구하고 지도 위에 표시하는 방법에 대해 알아보겠습니다.