---
title: "Android 시작 가이드"
slug: "naveropenapiv3-maps-android-sdk-v3-start"
tags: ["Mobile Dynamic Map"]
updated: 2026-10-22T09:13:28Z
published: 2026-10-22T09:13:28Z
canonical: "guide-gov.ncloud-docs.com/naveropenapiv3-maps-android-sdk-v3-start"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://guide-gov.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Android 시작 가이드

Classic/VPC 환경에서 이용 가능합니다.

## 시작하기

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

## 지원 OS 버전

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

## 클라이언트 ID 발급

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

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

자세한 방법은 [Application 사용 가이드](/docs/naveropenapiv3-application)를 참조하세요.

## 의존성 추가

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

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

```
allprojects {
    repositories {
        google()
        jcenter()
        maven {
            url 'https://naver.jfrog.io/artifactory/maven/'
        }
    }
}
```

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

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

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

## 클라이언트 ID 지정

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

### AndroidManifest.xml에 지정

[AndroidManifest.xml](https://developer.android.com/guide/topics/manifest/manifest-intro)의 [<meta-data>](https://developer.android.com/guide/topics/manifest/meta-data-element)로 클라이언트 ID를 지정할 수 있습니다. [<application>](https://developer.android.com/guide/topics/manifest/application-element) 아래에 두 개의 `&lt;meta-data&gt;`를 추가합니다. 첫 번째 `&lt;meta-data&gt;`에는 `name`에 `com.naver.maps.map.CLIENT_ID`를, `value`에 발급받은 클라이언트 ID를 지정하고, 두 번째 `&lt;meta-data&gt;`에는 `name`에 `com.naver.maps.map.CLIENT_TYPE`을 `value`에 `gov`를 지정합니다.

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

```
<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](https://developer.android.com/reference/android/app/Application)의 [onCreate()](https://developer.android.com/reference/android/app/Application#onCreate()) 내에서 [NaverMapSdk.setClient()](https://navermaps.github.io/android-map-sdk/reference/com/naver/maps/map/NaverMapSdk.html#setClient-com.naver.maps.map.NaverMapSdk.Client-)를 호출해 파라미터로 [NaverMapSdk.NaverCloudPlatformGovClient](https://navermaps.github.io/android-map-sdk/reference/com/naver/maps/map/NaverMapSdk.NaverCloudPlatformGovClient.html)를 전달합니다. `NaverMapSdk.NaverCloudPlatformClient`의 생성자 파라미터로 클라이언트 ID를 지정합니다. `NaverMapSdk`는 싱글턴 클래스이므로 [getInstance()](https://navermaps.github.io/android-map-sdk/reference/com/naver/maps/map/NaverMapSdk.html#getInstance-android.content.Context-)를 호출해 인스턴스를 얻어와야 합니다.

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

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

## 지도 표시

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

다음은 `&lt;fragment&gt;` 요소로 XML 레이아웃에 `MapFragment`를 추가해 지도를 화면에 나타내는 예제입니다.

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

## 인증 실패 처리

클라이언트 ID를 잘못 지정했거나 사용량이 쿼터를 초과하면 지도가 화면에 나타나지 않으며, Logcat과 토스트로 인증 오류 메시지가 출력됩니다. [NaverMapSdk.onAuthFailedListener](https://navermaps.github.io/android-map-sdk/reference/com/naver/maps/map/NaverMapSdk.html#setOnAuthFailedListener-com.naver.maps.map.NaverMapSdk.OnAuthFailedListener-) 속성에 [OnAuthFailedListener](https://navermaps.github.io/android-map-sdk/reference/com/naver/maps/map/NaverMapSdk.OnAuthFailedListener.html)를 등록하면 인증 실패 이벤트를 받을 수 있습니다. 리스너를 등록하면 인증 실패 시 [onAuthFailed()](https://navermaps.github.io/android-map-sdk/reference/com/naver/maps/map/NaverMapSdk.OnAuthFailedListener.html#onAuthFailed-com.naver.maps.map.NaverMapSdk.AuthFailedException-) 콜백 메서드가 호출되고 토스트는 노출되지 않습니다.

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

`onAuthFailed()`에는 인증 실패의 원인을 나타내는 `exception` 파라미터가 전달됩니다. `exception`의 타입과 [errorCode](https://navermaps.github.io/android-map-sdk/reference/com/naver/maps/map/NaverMapSdk.AuthFailedException.html#getErrorCode--) 속성으로 원인을 파악할 수 있습니다. 주로 발생하는 에러 코드는 다음과 같습니다.

| `errorCode` | 예외 타입 | 설명 |
| --- | --- | --- |
| 401 | [UnauthorizedClientException](https://navermaps.github.io/android-map-sdk/reference/com/naver/maps/map/NaverMapSdk.UnauthorizedClientException.html) | - 잘못된 클라이언트 ID를 지정함 - 잘못된 클라이언트 유형을 사용함 - 콘솔에서 앱 패키지 이름을 잘못 등록함 |
| 429 | [QuotaExceededException](https://navermaps.github.io/android-map-sdk/reference/com/naver/maps/map/NaverMapSdk.QuotaExceededException.html) | - 콘솔에서 Maps 서비스를 선택하지 않음 - 사용 한도가 초과됨 |
| 800 | [ClientUnspecifiedException](https://navermaps.github.io/android-map-sdk/reference/com/naver/maps/map/NaverMapSdk.ClientUnspecifiedException.html) | 클라이언트 ID를 지정하지 않음 |

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