시작하기 · 네이버 지도 안드로이드 SDK

시작하기

네이버 지도 SDK를 사용하기 위해서는 네이버 클라우드 플랫폼에서 클라이언트 ID를 발급받고, 발급받은 ID를 SDK에 지정해야 합니다.

지원 OS 버전

네이버 지도 SDK는 안드로이드 OS 버전 5.0(API 레벨 21) 이상에서 사용할 수 있습니다.

클라이언트 ID 발급

네이버 지도 SDK를 사용하려면 다음과 같이 애플리케이션을 등록하고 클라이언트 ID를 발급받아야 합니다.

1. 네이버 클라우드 플랫폼에 로그인한 후 콘솔에 들어갑니다.
2. Products & Services에서 AI-Application Service 하위의 AI·NAVER API를 선택합니다.
3. Application 등록을 선택하고 Maps 하위의 Mobile Dynamic Map을 체크합니다.
   • 선택하지 않으면 인증 실패 오류(429)가 발생합니다.
4. Android 앱 패키지 이름에 네이버 지도 SDK를 사용하고자 하는 앱의 패키지명을 추가하고 등록합니다.
   • 올바르게 입력하지 않으면 인증 실패 오류(401)가 발생합니다.
5. 등록한 애플리케이션의 인증 정보를 선택해 Client ID를 확인합니다.

자세한 방법은 Application 사용 가이드를 참조하세요.

의존성 추가

네이버 지도 SDK는 https://repository.map.naver.com/archive/maven Maven 저장소에서 배포됩니다. 루트 프로젝트의 build.gradle에 저장소 설정을 추가합니다.

다음은 저장소 설정을 추가한 예제입니다.

Groovy Kotlin allprojects { repositories { google() mavenCentral() maven { url 'https://repository.map.naver.com/archive/maven' } } }

Groovy

allprojects { repositories { google() mavenCentral() maven { url 'https://repository.map.naver.com/archive/maven' } } }

Kotlin

allprojects { repositories { google() mavenCentral() maven("https://repository.map.naver.com/archive/maven") } }

그리고 앱 모듈의 build.gradle에 네이버 지도 SDK에 대한 의존성을 선언합니다.

다음은 네이버 지도 SDK에 대한 의존성을 선언한 예제입니다.

Groovy Kotlin dependencies { // 네이버 지도 SDK implementation 'com.naver.maps:map-sdk:3.20.0' }

Groovy

dependencies { // 네이버 지도 SDK implementation 'com.naver.maps:map-sdk:3.20.0' }

Kotlin

dependencies { // 네이버 지도 SDK implementation("com.naver.maps:map-sdk:3.20.0") }

클라이언트 ID 지정

발급받은 클라이언트 ID를 SDK에 지정하면 지도 API를 사용할 수 있습니다. 클라이언트 ID는 두 가지 방식으로 지정할 수 있습니다.

AndroidManifest.xml에 지정

AndroidManifest.xml의 <meta-data>로 클라이언트 ID를 지정할 수 있습니다. <application> 아래에 <meta-data> 요소를 추가하고, name으로 com.naver.maps.map.CLIENT_ID를, value로 발급받은 클라이언트 ID를 지정합니다.

다음은 AndroidManifext.xml에 클라이언트 ID를 지정하는 예제입니다.

<manifest> <application> <meta-data android:name="com.naver.maps.map.CLIENT_ID" android:value="YOUR_CLIENT_ID_HERE" /> </application> </manifest>

공공기관용 클라이언트는 추가로 name이 com.naver.maps.map.CLIENT_TYPE, value가 gov인 <meta-data>를 지정해야 합니다.

다음은 AndroidManifext.xml에 공공기관용 클라이언트를 지정하는 예제입니다.

<manifest> <application> <meta-data android:name="com.naver.maps.map.CLIENT_ID" android:value="YOUR_CLIENT_ID_HERE" /> <meta-data android:name="com.naver.maps.map.CLIENT_TYPE" android:value="gov" /> </application> </manifest>

API를 호출해 지정

AndroidManifest.xml을 수정하지 않고 API를 호출해 클라이언트 ID를 지정할 수도 있습니다. Application의 onCreate() 내에서 NaverMapSdk.setClient()를 호출해 NaverCloudPlatformClient를 지정합니다. NaverMapSdk는 싱글톤 클래스이므로 getInstance()를 사용해 인스턴스를 얻어와야 합니다.

다음은 API를 호출해 클라이언트 ID를 지정하는 예제입니다.

Java Kotlin public class YourApplication extends Application { @Override public void onCreate() { super.onCreate(); NaverMapSdk.getInstance(this).setClient( new NaverMapSdk.NaverCloudPlatformClient("YOUR_CLIENT_ID_HERE")); } }

Java

public class YourApplication extends Application { @Override public void onCreate() { super.onCreate(); NaverMapSdk.getInstance(this).setClient( new NaverMapSdk.NaverCloudPlatformClient("YOUR_CLIENT_ID_HERE")); } }

Kotlin

class YourApplication : Application() { fun onCreate() { super.onCreate() NaverMapSdk.getInstance(this).client = NaverMapSdk.NaverCloudPlatformClient("YOUR_CLIENT_ID_HERE") } }

공공기관용 클라이언트는 NaverCloudPlatformClient 대신 NaverCloudPlatformGovClient를 사용합니다.

다음은 API를 호출해 공공기관용 클라이언트를 지정하는 예제입니다.

Java Kotlin public class YourApplication extends Application { @Override public void onCreate() { super.onCreate(); NaverMapSdk.getInstance(this).setClient( new NaverMapSdk.NaverCloudPlatformGovClient("YOUR_CLIENT_ID_HERE")); } }

Java

public class YourApplication extends Application { @Override public void onCreate() { super.onCreate(); NaverMapSdk.getInstance(this).setClient( new NaverMapSdk.NaverCloudPlatformGovClient("YOUR_CLIENT_ID_HERE")); } }

Kotlin

class YourApplication : Application() { fun onCreate() { super.onCreate() NaverMapSdk.getInstance(this).client = NaverMapSdk.NaverCloudPlatformGovClient("YOUR_CLIENT_ID_HERE") } }

지도 표시

클라이언트 ID를 지정하고 MapFragment를 앱의 레이아웃에 추가하면 지도가 화면에 나타납니다.

다음은 <FragmentContainerView> 요소로 XML 레이아웃에 MapFragment를 추가해 지도를 화면에 나타내는 예제입니다.

<androidx.fragment.app.FragmentContainerView android:id="@+id/map_fragment" android:layout_width="match_parent" android:layout_height="match_parent" android:name="com.naver.maps.map.MapFragment" />

인증 실패 처리

클라이언트 ID 또는 유형을 잘못 지정했거나 사용량이 쿼터를 초과하면 지도가 화면에 나타나지 않으며, Logcat과 토스트로 인증 오류 메시지가 출력됩니다. NaverMapSdk.onAuthFailedListener 속성에 OnAuthFailedListener를 등록하면 인증 실패 이벤트를 받을 수 있습니다. 리스너를 등록하면 인증 실패 시 onAuthFailed() 콜백 메서드가 호출되고 토스트는 노출되지 않습니다.

인증 실패 이벤트는 명백하게 인증에 실패했음이 확인된 경우에만 발생합니다. 따라서 인터넷 연결이 불가능할 경우 이벤트가 발생하지 않습니다. 캐시된 데이터로 지도를 로딩한 후 인터넷 연결이 재개되면 다시 인증을 시도하고, 이 때 인증에 실패하면 이벤트가 발생합니다.

onAuthFailed()에는 인증 실패의 원인을 나타내는 exception 파라미터가 전달됩니다. exception의 타입과 errorCode 속성으로 원인을 파악할 수 있습니다. 주로 발생하는 에러 코드는 다음과 같습니다.

errorCode	예외 타입	설명
401	UnauthorizedClientException	- 잘못된 클라이언트 ID를 지정함- 잘못된 클라이언트 유형을 사용함- 콘솔에서 앱 패키지 이름을 잘못 등록함
429	QuotaExceededException	- 콘솔에서 Maps 서비스를 선택하지 않음- 사용 한도가 초과됨
800	ClientUnspecifiedException	클라이언트 ID를 지정하지 않음

그 외의 원인으로 인증에 실패하면 AuthFailedException이 발생합니다.