Navigation SDK는 현재 일부 고객만 사용할 수 있습니다. 자세한 내용은 영업팀에 문의하세요.

새로운 지도 스타일 지정 기능이 곧 Google Maps Platform에 도입될 예정입니다. 이번 지도 스타일 지정 업데이트에는 새로운 기본 색상 팔레트가 추가되었으며 지도 환경 및 사용성이 개선되었습니다. 모든 지도 스타일은 2025년 3월에 자동으로 업데이트됩니다. 사용 가능 여부 및 이전에 선택한 방법에 대한 자세한 내용은 Google Maps Platform의 새 지도 스타일을 참고하세요.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Android 스튜디오 프로젝트 설정

Navigation SDK는 Maven을 통해 사용할 수 있습니다. 개발 프로젝트를 만든 후 다음 방법 중 하나를 사용하여 SDK를 프로젝트에 통합할 수 있습니다.

Navigation SDK에 Maven 사용 (권장)

다음은 프로젝트에 Navigation SDK를 추가하는 가장 간단하고 권장되는 방법인 google() Maven 저장소를 사용합니다.

Gradle 또는 Maven 구성에 다음 종속 항목을 추가하고 VERSION_NUMBER 자리표시자를 원하는 Android용 Navigation SDK 버전으로 대체합니다.

Gradle

모듈 수준 build.gradle에 다음을 추가합니다.

dependencies {
...
implementation 'com.google.android.libraries.navigation:navigation:VERSION_NUMBER'
}

원래 Maven 저장소에서 업그레이드하는 경우 그룹과 아티팩트 이름이 변경되었으며 com.google.cloud.artifactregistry.gradle-plugin 플러그인은 더 이상 필요하지 않습니다.

최상위 수준 build.gradle에 다음을 추가합니다.

allprojects {
...
// Required: you must exclude the Google Play service Maps SDK from
// your transitive dependencies. This is to ensure there won't be
// multiple copies of Google Maps SDK in your binary, as the Navigation
// SDK already bundles the Google Maps SDK.
configurations {
        implementation {
            exclude group: 'com.google.android.gms', module: 'play-services-maps'
        }
}
}

Maven

pom.xml에 다음을 추가합니다.

<dependencies>
  ...
  <dependency>
    <groupId>com.google.android.libraries.navigation</groupId>
    <artifactId>navigation</artifactId>
    <version>VERSION_NUMBER</version>
  </dependency>
</dependencies>

Maps SDK를 사용하는 종속 항목이 있는 경우 Maps SDK를 사용하는 선언된 각 종속 항목에서 종속 항목을 제외해야 합니다.

<dependencies>
  <dependency>
  <groupId>project.that.brings.in.maps</groupId>
  <artifactId>MapsConsumer</artifactId>
  <version>1.0</version>
    <exclusions>
      <!-- Navigation SDK already bundles Maps SDK. You must exclude it to prevent duplication-->
      <exclusion>  <!-- declare the exclusion here -->
        <groupId>com.google.android.gms</groupId>
        <artifactId>play-services-maps</artifactId>
      </exclusion>
    </exclusions>
  </dependency>
</dependencies>

빌드 구성

프로젝트를 만든 후에는 성공적인 빌드와 Navigation SDK 사용을 위한 설정을 구성할 수 있습니다.

로컬 숙박 시설 업데이트

Gradle Scripts 폴더에서 local.properties 파일을 열고 android.useDeprecatedNdk=true를 추가합니다.

Gradle 빌드 스크립트 업데이트

build.gradle (Module:app) 파일을 열고 다음 가이드라인에 따라 Navigation SDK의 요구사항을 충족하도록 설정을 업데이트하고 최적화 옵션 설정도 고려합니다.

Navigation SDK의 필수 설정
1. minSdkVersion를 23 이상으로 설정합니다.
2. targetSdkVersion을 33 이상으로 설정합니다.
3. javaMaxHeapSize를 늘리는 dexOptions 설정을 추가합니다.
4. 추가 라이브러리의 위치를 설정합니다.
5. Navigation SDK의 repositories 및 dependencies를 추가합니다.
6. 종속 항목의 버전 번호를 사용 가능한 최신 버전으로 바꿉니다.
빌드 시간을 줄이기 위한 선택적 설정
- R8/ProGuard를 사용하여 코드 축소 및 리소스 축소를 사용 설정하여 사용되지 않는 코드와 리소스를 종속 항목에서 삭제합니다. R8/ProGuard 단계를 실행하는 데 시간이 너무 오래 걸리면 개발 작업에 multidex를 사용 설정해 보세요.
- 빌드에 포함된 언어 번역 수를 줄입니다. 개발 중에 한 언어에 resConfigs를 설정합니다. 최종 빌드의 경우 실제로 사용하는 언어에 resConfigs를 설정합니다. 기본적으로 Gradle에는 Navigation SDK에서 지원하는 모든 언어의 리소스 문자열이 포함됩니다.
Java8 지원을 위해 디슈가링 추가
- Android Gradle 플러그인 4.0.0 이상을 사용하여 앱을 빌드하는 경우 플러그인은 다양한 Java 8 언어 API 사용 지원을 확장합니다. 자세한 내용은 자바 8 디슈가링 지원을 참고하세요. 컴파일 및 종속 항목 옵션은 아래의 빌드 스크립트 스니펫 예를 참고하세요.

다음은 애플리케이션의 Gradle 빌드 스크립트의 예입니다. 사용 중인 Navigation SDK 버전이 이 문서보다 약간 앞서거나 뒤처질 수 있으므로 샘플 앱에서 업데이트된 종속 항목 세트를 확인하세요.

apply plugin: 'com.android.application'

ext {
    navSdk = "__NAVSDK_VERSION__"
}

android {
    compileSdk 33
    buildToolsVersion='28.0.3'

    defaultConfig {
        applicationId "<your id>"
        // Navigation SDK supports SDK 23 and later.
        minSdkVersion 23
        targetSdkVersion 33
        versionCode 1
        versionName "1.0"
        // Set this to the languages you actually use, otherwise you'll include resource strings
        // for all languages supported by the Navigation SDK.
        resConfigs "en"
        multiDexEnabled true
    }

    dexOptions {
        // This increases the amount of memory available to the dexer. This is required to build
        // apps using the Navigation SDK.
        javaMaxHeapSize "4g"
    }
    buildTypes {
        // Run ProGuard. Note that the Navigation SDK includes its own ProGuard configuration.
        // The configuration is included transitively by depending on the Navigation SDK.
        // If the ProGuard step takes too long, consider enabling multidex for development work
        // instead.
        all {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
    compileOptions {
        // Flag to enable support for the new language APIs
        coreLibraryDesugaringEnabled true
        // Sets Java compatibility to Java 8
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

repositories {
    // Navigation SDK for Android and other libraries are hosted on Google's Maven repository.
    google()
}

dependencies {
    // Include the Google Navigation SDK.
    // Note: remember to exclude Google Play service Maps SDK from your transitive
    // dependencies to avoid duplicate copies of the Google Maps SDK.
    api "com.google.android.libraries.navigation:navigation:${navSdk}"

    // Declare other dependencies for your app here.

    annotationProcessor "androidx.annotation:annotation:1.7.0"
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.1.9'
}

앱에 API 키 추가하기

이 섹션에서는 앱이 더욱 안전하게 참조할 수 있도록 API 키를 저장하는 방법을 설명합니다. API 키는 버전 제어 시스템에 체크인하면 안 되며, 프로젝트의 루트 디렉터리에 있는 secrets.properties 파일에 저장하는 것이 좋습니다. secrets.properties 파일에 관한 자세한 내용은 Gradle 속성 파일을 참고하세요.

이 작업을 간소화하려면 Android용 Secrets Gradle 플러그인을 사용하는 것이 좋습니다.

Google 지도 프로젝트에 Android용 Secrets Gradle 플러그인을 설치하려면 다음 단계를 따르세요.

Android 스튜디오에서 최상위 수준 build.gradle 또는 build.gradle.kts 파일을 열고 다음 코드를 buildscript 아래 dependencies 요소에 추가합니다.

Groovy

buildscript {
    dependencies {
        classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
    }
}

Kotlin

buildscript {
    dependencies {
        classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
    }
}

모듈 수준 build.gradle 파일을 열고 plugins 요소에 다음 코드를 추가합니다.

Groovy

plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}

Kotlin

plugins {
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}

모듈 수준 build.gradle 파일에서 targetSdk 및 compileSdk를 34로 설정해야 합니다.
파일을 저장하고 프로젝트를 Gradle과 동기화합니다.
최상위 수준 디렉터리에서 secrets.properties 파일을 연 후 다음 코드를 추가합니다. YOUR_API_KEY를 직접 생성한 API 키로 변경합니다. secrets.properties가 버전 제어 시스템에 체크인되는 데서 제외되었으므로 키를 이 파일에 저장합니다.
참고: secrets.properties 파일이 존재하지 않으면 local.properties 파일과 동일한 폴더에 파일을 만듭니다.
```
NAV_API_KEY=YOUR_API_KEY
```
파일을 저장합니다.
최상위 수준 디렉터리에서 secrets.properties 파일과 동일한 폴더에 local.defaults.properties 파일을 만든 후 다음 코드를 추가합니다.

참고: 아래에 표시된 대로 코드를 입력하세요. DEFAULT_API_KEY를 API 키로 바꾸지 마세요.
```
NAV_API_KEY=DEFAULT_API_KEY
```
이 파일의 목적은 secrets.properties 파일이 없는 경우 빌드에 실패하지 않도록 API 키의 백업 위치를 제공하는 것입니다. 이는 버전 제어 시스템에서 secrets.properties가 빠진 앱을 복제하거나 API 키를 제공하는 secrets.properties 파일을 아직 로컬에서 생성하지 않은 경우 발생할 수 있습니다.
파일을 저장합니다.
AndroidManifest.xml 파일에서 com.google.android.geo.API_KEY로 이동한 후 android:value attribute를 업데이트합니다. <meta-data> 태그가 존재하지 않으면 <application> 태그의 하위 요소로 태그를 만듭니다.
```
<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />
```
Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Navigation SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

Groovy

secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    propertiesFileName = "secrets.properties"

    // A properties file containing default secret values. This file can be
    // checked in version control.
    defaultPropertiesFileName = "local.defaults.properties"

    // Configure which keys should be ignored by the plugin by providing regular expressions.
    // "sdk.dir" is ignored by default.
    ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
    ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
}

Kotlin

secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    propertiesFileName = "secrets.properties"

    // A properties file containing default secret values. This file can be
    // checked in version control.
    defaultPropertiesFileName = "local.defaults.properties"

    // Configure which keys should be ignored by the plugin by providing regular expressions.
    // "sdk.dir" is ignored by default.
    ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
    ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
}

앱에 필수 저작자 표시 포함

앱에서 Android용 Navigation SDK를 사용하는 경우 앱의 법적 고지 섹션에 저작자 표시 텍스트와 오픈소스 라이선스를 포함해야 합니다.

Android용 Navigation SDK ZIP 파일에서 필수 저작자 표시 텍스트와 오픈소스 라이선스를 찾을 수 있습니다.

NOTICE.txt
LICENSES.txt

모빌리티 또는 플릿 엔진 배달 고객인 경우

이동성 또는 Fleet Engine 전송 고객인 경우 이동성 문서에서 청구에 대해 알아보세요. 거래 기록에 관한 자세한 내용은 결제 설정, 청구 가능한 거래 기록, 보고, 청구 가능한 거래 기록 (Android)을 참고하세요.