Google Maps Android API v2 사용하기

2012년 12월 4일, Google Play Services가 업데이트되면서 새 버전의 안드로이드용 API가 공개되었습니다.

주요 변경사항은 다음과 같습니다.

• MapFragment 지원으로 다양한 해상도의 단말 지원 용이 (MapActivity가 아닌 일반 액티비티에서도 MapView 사용가능)
  
• 3D맵 지원
• 한층 편리해진 마커 사용법

이와 함께, 구글맵 API를 사용하기 위한 인증 및 사용 절차가 다소 변경되었습니다. 이 포스트에서는 새로운 구글맵 API를 사용하는 방법에 대해 자세히 알아보도록 하겠습니다.

구글맵 API를 사용하기 위한 단계를 간략히 요약하면 다음과 같습니다.

1. Android SDK Manager를 통해 Google Play Services SDK 다운로드 (Rev.3 이상)

2. 새 프로젝트 생성 및 구글맵 라이브러리 프로젝트를 Workspace로 가져오기

3. 구글맵 인증키(API Key) 획득에 필요한 keystore/key fingerprint 획득

4. 구글맵 인증키 발급

5. 구글맵을 사용할 프로젝트의 매니페스트 설정

6. 레이아웃에 구글맵 추가하기

1. Google Play Services SDK 다운로드

Android SDK Manager를 실행한 후, 아래의 Extra 카테고리에서 Google Play Services 패키지를 설치합니다.

Revision(Rev.) 3 이상이여야 하며, 설치가 완료되면 다음과 같이 Installed로 표시됩니다.

2. 새 프로젝트 생성 및 구글맵 라이브러리 프로젝트 가져오기

기존의 구글맵 라이브러리가 시스템 이미지(Android X.X / Google APis로 구분)에 포함되어 있었던 것과 달리, 이번 버전부터는 별도의 라이브러리 프로젝트로 제공됩니다. 때문에 이를 사용하려면 이클립스 내 자신의 Workspace로 구글맵 라이브러리 프로젝트를 불러와야 합니다.

이클립스의 메뉴에서 File > New > Other...를 선택한 후, Android Project from Existing Code를 선택합니다.

다음, Root Directory에 구글맵 라이브러리 프로젝트가 있는 폴더를 지정해줍니다. 구글맵 라이브러리 프로젝트는 다음 경로에 저장되어 있습니다.

[안드로이드 SDK경로]/extras/google/google/google_play_services/libproject/google-play-services_lib

여러 사람과 함께 작업해야 하는 프로젝트일 경우, 라이브러리 프로젝트를 참조할 때 Workspace에 상대적인 경로를 사용하여 참조하도록 해야 하므로 Copy project into workspace에 체크해줍니다. 

다음과 같이 Workspace에 Google Play Services 라이브러리 프로젝트가 추가됩니다.

이제 새 프로젝트를 생성한 후, 위에서 추가한 라이브러리 프로젝트를 참조하도록 설정할 차례입니다. 프로젝트를 생성한 후, 프로젝트 속성 창(프로젝트 이름 오른쪽클릭 - Properties)을 열어 왼쪽 탭에서 'Android' 항목을 선택한 후 우측 하단의 'Library' 영역에서 'Add...' 버튼을 눌러 google-play-services_lib를 선택합니다.

다음과 같이 표시되면 제대로 설정된 것입니다.

이것으로 기본적인 프로젝트 설정은 끝났습니다.

3. 구글맵 인증키 발급에 필요한 keystore/key fingerprint 획득

구글맵을 사용하려면 인증키(API Key)를 발급받아야 합니다. 애플리케이션 패키지 (*.apk)생성시 사용하는 서명 정보(key)를 사용하여 인증을 수행하게 되며, 버전1에서는 MD5 지문을 사용했는데 이번 버전부터는 SHA1 지문을 사용하도록 변경되었습니다.

용어정리

애플리케이션 서명 : 

애플리케이션을 배포할 때, 개발자는 애플리케이션을 패키지(*.apk) 형태로 만들게 됩니다. 이 때, 이 패키지를 '누가' 패키징했는지 정보를 기록하게 되는데, 이를 '애플리케이션 서명' 이라 합니다. 이는 애플리케이션이 배포된 이후 악의적인 목적으로 리패키징(애플리케이션 내용물을 변조한 후 다시 패키징하는 것)했을 때, 이를 원본과 구분하기 위해 사용합니다.

keystore/key : 

애플리케이션 서명을 위해 사용하는 수단으로, 자신의 '서명' 이라 할 수 있습니다. 서명은 'key'로 하게 되며, keystore는 서명을 할 수 있는 key들을 담을 수 있는 파일을 뜻합니다. 이클립스를 통한 개발시 기본으로 디버그용 키를 사용하여 애플리케이션 패키지를 서명하게 되며, 안드로이드 마켓 등 외부로 애플리케이션을 배포할 때는 자신의 키를 사용하여 서명한 후 배포해야 합니다. (안드로이드 마켓의 경우 최초 애플리케이션 업로드시 사용한 키를 잃어버리면 더 이상 애플리케이션을 업데이트할 수 없습니다)

(MD5/SHA1)지문 : 

각 서명을 고유하게 식별할 수 있는 고유한 문자열로, 문자열을 생성하는 알고리즘에 따라 MD5, SHA1 지문으로 구분됩니다.

이클립스를 통해 개발을 하게되면, 기본값으로 디버그용 키를 통해 애플리케이션 패키지를 서명하게 됩니다. 때문에, 구글맵을 사용하는 애플리케이션을 테스트하려면 배포시 사용할 키 뿐만 아니라 디버그용 키 또한 등록해 주어야 합니다.

먼저, 디버그용 키의 지문을 얻기 위해 디버그용 키가 저장되어 있는 곳으로 이동합니다. 명령 프롬프트/터미널을 실행한 후, 운영체제에 따라 각각 다음의 경로로 이동합니다.

Windows XP : C:\Documents And Settings\[사용자 계정]\.android

Windows Vista/7 : C:\Users\[사용자 계정]\.android

OSX/Linux : ~/.android

다음, 아래의 명령을 입력하여 디버그용 키의 지문을 조회합니다.

keytool -list -v -keystore debug.keystore -alias androiddebugkey -storepass android -keypass android

다음과 같이 인증서 지문이 표시됩니다. 여기에서 우리가 필요한 것은 인증 지문 항목 중 SHA1 항목입니다. 이 정보를 복사해둡니다.

4. 구글맵 인증키 발급받기

이제 구글지도 API 키를 발급받기 위해 Google APis Console(https://code.google.com/apis/console/)로 이동합니다. Google APIs Console에서는 프로젝트별로 사용하는 구글 API를 관리할 수 있도록 되어있습니다. 아직 프로젝트가 없다면 왼쪽의 드롭다운 메뉴에서 Create...를 눌러 새 프로젝트를 생성합니다. 저는 'AndroidMapsV2'라는 이름으로 프로젝트를 생성해 보겠습니다.

프로젝트를 생성하면 활성화할 서비스 목록이 표시됩니다. 목록에서 Google Maps Android API v2를 찾아 활성화해줍니다.

다음, 왼쪽 탭에서 API Access를 선택한 후 Simple API Access 항목에 Create new Android key...를 선택합니다.

이제 여기에 이전에 조회한 SHA1 지문과 애플리케이션의 패키지 이름을 다음과 같은 형식에 맞춰 입력합니다.

[SHA1지문];[애플리케이션 패키지 이름]

여기에서는 com.androidhuman.example.mapsv2example 이라는 애플리케이션에서 구글맵을 사용하도록 하는 것을 가정하여 입력해 보았습니다.

Create 버튼을 누르면 다음과 같이 API Key가 발급됩니다.

5. 구글맵 사용을 위한 매니페스트 설정

매니페스트에서 추가해야 할 항목들은 다음과 같습니다.

- OpenGL 2.0 이상을 지원하는 단말기에서 실행되도록 하기 (Uses feature)

- 애플리케이션의 Meta-data에 구글맵 API Key 추가

- 구글맵의 정상적인 사용을 위한 권한 추가

OpenGL 2.0 이상을 지원하는 단말기에서 실행되도록 하기

이번 버전의 구글맵이 OpenGL 2.0을 사용하게 됨에 따라, 이를 이원하지 않는 단말기에서는 구동할 수 없습니다. 때문에 매니페스트에 이를 지원하는 단말기에서는 설치가 되지 않도록 별도의 설정을 해 주어야 합니다.

AndroidManifest.xml을 연 후, Manifest 탭 하단의 Manifest Extras 영역을 찾아봅니다.

다음, Add...를 눌러 Uses Feature를 선태한 후, 다음과 같이 입력합니다.

Meta data로 구글맵 API 및 Play Services 버전 추가하기

매니페스트의 'Application' 탭을 선택한 후, Application Nodes 항목에서 Add...버튼을 누른 후 Meta Data를 선택합니다.

그 다음, Name과 Data에 다음과 같이 입력합니다.

Name : com.google.android.maps.v2.API_KEY

Value : 발급받은 구글맵 API Key

같은 방법으로, 사용하는 Play Services의 버전도 추가해주어야 합니다. 다음 값을 추가해줍니다.

Name : com.google.android.gms.version

Value : @integer/google_play_services_version

권한 추가하기

구글맵 데이터를 받아오기 위해 필요한 권한을 추가합니다. 먼저, API Key와 연동하여 구글맵 데이터를 받아올 수 있는 권한을 생성하고 추가해야 합니다.

다음의 권한들을 Uses Permission 으로 추가해줍니다.

• android.permission.INTERNET
• android.permission.ACCESS_NETWORK_STATE
• android.permission.WRITE_EXTERNAL_STORAGE
• com.google.android.providers.gsf.permission.READ_GSERVICES
• android.permission.ACCESS_COARSE_LOCATION
• android.permission.ACCESS_FINE_LOCATION

6. 레이아웃에 구글맵 추가하기

이제 레이아웃에 구글맵을 추가할 차례입니다. 이전 버전의 구글맵에서는 구글맵을 표시하려면 MapActivity를 사용해야 했지만, 이번 버전부터는 Fragment 형태로 구글맵이 지원되어 어느 곳에서나 쉽게 구글맵을 사용할 수 있습니다.

프래그먼트 형태로 제공되는 구글맵을 사용하려면 레이아웃에 다음과 같이 선언해주면 됩니다.

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical" >
    
    <fragment 
        android:id="@+id/map"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        class="com.google.android.gms.maps.MapFragment" />
    

</LinearLayout>

애플리케이션을 실행하면 다음과 같이 지도가 표시되는 것을 확인할 수 있습니다.

강좌에서 사용한 예제 프로젝트 파일을 첨부하였으니 자세한 사항은 프로젝트 파일을 참고하시면 됩니다. ;)

예제 프로젝트를 테스트할 때, API Key를 꼭 자신이 발급받은 것으로 교체하고, 애플리케이션을 Google APIs Console에 등록했는지 확인 후 진행해주세요!