SDK điều hướng hiện chỉ được cung cấp cho một số khách hàng. Liên hệ với bộ phận bán hàng để tìm hiểu thêm.

Kiểu bản đồ mới sắp xuất hiện trên Nền tảng Google Maps. Bản cập nhật này để tạo kiểu bản đồ bao gồm một bảng màu mặc định mới và các cải tiến về trải nghiệm bản đồ cũng như khả năng hữu dụng. Tất cả kiểu bản đồ sẽ được cập nhật tự động vào tháng 3 năm 2025. Để biết thêm thông tin về phạm vi cung cấp và cách chọn tham gia sớm hơn, hãy xem bài viết Kiểu bản đồ mới cho Nền tảng Google Maps.

Trang này được dịch bởi Cloud Translation API.

Thiết lập dự án -- Phiên bản 4.99 trở xuống

Hướng dẫn này liệt kê các yêu cầu về cấu hình bản dựng để sử dụng SDK điều hướng dành cho Android. Những hướng dẫn này giả định bạn có một IDE Android đã cài đặt và làm quen với việc phát triển Android.

Các yêu cầu tối thiểu để sử dụng SDK điều hướng

Những yêu cầu này áp dụng cho SDK điều hướng dành cho Android phiên bản 4.99 trở xuống.

Một dự án Google Cloud Console có bật SDK điều hướng. Để cung cấp, hãy hỏi người đại diện Nền tảng Google Maps của bạn.
Ứng dụng của bạn phải nhắm đến API cấp 30 trở lên.
Để chạy một ứng dụng được tạo bằng SDK điều hướng, Android thiết bị phải có Dịch vụ Google Play sau khi cài đặt và bật.
Phân bổ và văn bản cấp phép phải được thêm vào ứng dụng.

Thiết lập dự án: Dự án Cloud Console và dự án Android

Trước khi có thể tạo hoặc thử nghiệm một ứng dụng, bạn cần tạo một dự án trên Cloud Console và thêm thông tin đăng nhập khoá API. Dự án phải có cấp phép để truy cập vào SDK điều hướng. Tất cả các khoá trong dự án Cloud Console đều được cấp quyền truy cập tương tự vào SDK điều hướng. Một khoá có thể liên kết với nhiều dự án phát triển. Nếu đã có một dự án trên bảng điều khiển, bạn có thể thêm khoá vào dự án hiện tại.

Cách thiết lập

Trong trình duyệt web yêu thích của bạn, hãy đăng nhập vào Bảng điều khiển Cloud và tạo Bảng điều khiển Cloud dự án.
Trong IDE của bạn, chẳng hạn như Android Studio, hãy tạo một hoạt động phát triển ứng dụng Android dự án và ghi lại tên gói.
Hãy liên hệ với đại diện Nền tảng Google Maps của bạn để cung cấp quyền truy cập vào SDK điều hướng dành cho Cloud Console dự án.
Khi đang sử dụng trang tổng quan Cloud Console trên trình duyệt web, tạo thông tin đăng nhập để tạo khoá API kèm theo các quy định hạn chế.
Trên trang khoá API, hãy nhấp vào Ứng dụng Android trong phần Hạn chế ứng dụng .
Nhấp vào Thêm tên gói và vân tay số rồi nhập gói đó tên của dự án phát triển và vân tay số SHA-1 cho khoá đó.
Nhấp vào Lưu.

Thêm SDK điều hướng vào dự án của bạn

SDK Điều hướng được cung cấp thông qua Maven hoặc dưới dạng một Gói AAR. Sau khi tạo dự án phát triển, bạn có thể tích hợp SDK vào dự án đó bằng cách bằng một trong các phương pháp sau.

Sử dụng Maven cho SDK điều hướng phiên bản 4.5 trở lên (nên dùng)

Phần sau đây sử dụng kho lưu trữ Maven google(), đơn giản nhất và đề xuất cách thêm SDK điều hướng vào dự án

Thêm phần phụ thuộc sau vào cấu hình Gradle hoặc Maven của bạn: thay thế phần giữ chỗ VERSION_NUMBER cho phần phiên bản mong muốn của SDK điều hướng cho Android.

Gradle

Thêm đoạn mã sau vào build.gradle cấp mô-đun:

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

Nếu nâng cấp từ kho lưu trữ Maven ban đầu, hãy lưu ý rằng nhóm và tên cấu phần phần mềm đã thay đổi và Trình bổ trợ com.google.cloud.artifactregistry.gradle-plugin không còn hoạt động nữa nếu cần.

Và thêm đoạn mã sau vào build.gradle cấp cao nhất:

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

Thêm phần sau vào pom.xml:

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

Nếu có bất kỳ phần phụ thuộc nào sử dụng SDK Maps, bạn phải loại trừ phần phụ thuộc phần phụ thuộc trong mỗi phần phụ thuộc được khai báo và phụ thuộc vào SDK Maps.

<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>

Sử dụng Maven cho SDK điều hướng trước phiên bản 4.5 hoặc với SDK trình điều khiển

SDK điều hướng tiếp tục được cung cấp thông qua kho lưu trữ Maven gốc thông qua phần còn lại của các phiên bản v4. Đây là cùng một thư viện với tất cả nội dung cập nhật giống như phiên bản ở trên và cung cấp khả năng tương thích với SDK trình điều khiển và các thư viện khác trong quá trình chuyển đổi. Sử dụng phần phụ thuộc này yêu cầu đăng nhập vào dự án trên đám mây của bạn qua gcloud khi biên dịch.

Thiết lập môi trường để truy cập vào kho lưu trữ Maven của Google như mô tả trong Điều kiện tiên quyết trong tài liệu về SDK người tiêu dùng. Quyền truy cập vào SDK điều hướng được kiểm soát thông qua một nhóm không gian làm việc.

Thêm phần phụ thuộc sau vào cấu hình Gradle hoặc Maven, thay thế phần phụ thuộc Phần giữ chỗ VERSION_NUMBER cho phiên bản SDK điều hướng mong muốn.

Gradle

Thêm đoạn mã sau vào build.gradle cấp mô-đun:

dependencies {
  ...
  implementation 'com.google.android.maps:navsdk:VERSION_NUMBER'
}

Và thêm đoạn mã sau vào build.gradle cấp cao nhất:

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

Thêm phần sau vào pom.xml:

<dependencies>
  ...
  <dependency>
    <groupId>com.google.android.maps</groupId>
    <artifactId>navsdk</artifactId>
    <version>VERSION_NUMBER</version>
  </dependency>
</dependencies>

<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>

Sử dụng gói AAR đã tải xuống (không nên)

SDK điều hướng cũng được cung cấp dưới dạng một gói AAR. Sau khi tạo dự án phát triển, bạn có thể tích hợp SDK. Những hướng dẫn này giả định việc sử dụng Android Studio cho IDE của bạn.

Tải xuống phiên bản mới nhất của SDK điều hướng từ Google Drive dùng chung rồi giải nén tệp đó. Nếu bạn không có quyền truy cập, hãy liên hệ với đại diện của bạn.
Trong Android Studio, hãy mở một dự án rồi thêm gói Dịch vụ Google Play bằng Trình quản lý SDK.
Từ thư mục tệp zip, hãy sao chép libs/google_navigation_navmap.aar vào thư mục app/libs của dự án.

Thêm đoạn mã sau vào build.gradle cấp mô-đun:

implementation(name: 'google_navigation_navmap', ext: 'aar')

Và thêm đoạn mã sau vào build.gradle cấp cao nhất:

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'
        }
    }
}

Định cấu hình bản dựng

Sau khi tạo dự án, bạn có thể định cấu hình chế độ cài đặt cho tạo và sử dụng thành công SDK điều hướng.

Cập nhật các cơ sở lưu trú tại địa phương

Trong thư mục Gradle Scripts (Tập lệnh Gradle), hãy mở tệp local.properties rồi thêm android.useDeprecatedNdk=true.

Cập nhật tập lệnh bản dựng Gradle

Mở tệp build.gradle (Module:app) và làm theo các nguyên tắc sau để hãy cập nhật các chế độ cài đặt để đáp ứng các yêu cầu đối với SDK điều hướng và xem xét đặt các tuỳ chọn tối ưu hoá.

Các chế độ cài đặt bắt buộc cho SDK điều hướng
1. Đặt minSdkVersion thành 23 trở lên.
2. Đặt targetSdkVersion thành 30 trở lên.
3. Thêm một chế độ cài đặt dexOptions để tăng javaMaxHeapSize.
4. Đặt vị trí cho các thư viện khác.
5. Thêm repositories và dependencies cho SDK điều hướng.
6. Thay thế số phiên bản trong các phần phụ thuộc bằng các phiên bản mới nhất hiện có.
Các chế độ cài đặt không bắt buộc để giảm thời gian xây dựng
- Bật rút gọn mã và rút gọn tài nguyên bằng R8/ProGuard để xoá mã và tài nguyên không dùng đến khỏi các phần phụ thuộc. Nếu bước R8/ProGuard mất quá nhiều thời gian để chạy, hãy cân nhắc việc bật multidex cho công việc phát triển.
- Giảm số lượng bản dịch ngôn ngữ có trong bản dựng: Đặt resConfigs cho một ngôn ngữ trong quá trình phát triển. Đối với bản dựng cuối cùng, hãy đặt resConfigs cho các ngôn ngữ bạn thực sự sử dụng. Theo mặc định, Gradle bao gồm chuỗi tài nguyên cho tất cả các ngôn ngữ mà SDK điều hướng hỗ trợ.

Dưới đây là ví dụ về tập lệnh bản dựng Gradle cho ứng dụng. Xem ứng dụng mẫu cho các tập hợp phần phụ thuộc đã cập nhật, làm phiên bản của SDK điều hướng bạn đang sử dụng có thể hơi chậm hoặc sau tài liệu này.

apply plugin: 'com.android.application'
apply plugin: 'com.google.cloud.artifactregistry.gradle-plugin'

ext {
    androidxVersion = "1.0.0"
    lifecycle_version = "1.1.1"
}

android {
    compileSdkVersion 30
    buildToolsVersion '28.0.3'

    defaultConfig {
        applicationId "<your id>"
        // Navigation SDK supports SDK 23 and later.
        minSdkVersion 23
        targetSdkVersion 30
        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 {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

// This tells Gradle where to look to find additional libraries - in this case, the
// google_navigation_navmap.aar file.
repositories {
    flatDir {
        dirs 'libs'
    }
    google()

    // Required for accessing the Navigation SDK on Google's Maven repository.
    maven {
        url "artifactregistry://us-west2-maven.pkg.dev/gmp-artifacts/transportation"
    }
}

dependencies {
    // Include the Google Navigation SDK
    implementation 'com.google.android.maps:navsdk:4.4.0'

    // The included AAR file under libs can be used instead of the Maven repository.
    // Uncomment the line below and comment out the previous dependency to use
    // the AAR file instead. Ensure that you add the AAR file to the libs directory.
    // implementation(name: 'google_navigation_navmap', ext: 'aar')

    // These dependencies are required for the Navigation SDK to function
    // properly at runtime.
    implementation 'org.chromium.net:cronet-fallback:69.3497.100'
    // Optional for Cronet users:
    // implementation 'org.chromium.net:cronet-api:69.3497.100'
    implementation 'androidx.appcompat:appcompat:${androidxVersion}'
    implementation 'androidx.cardview:cardview:${androidxVersion}'
    implementation 'com.google.android.material:material:${androidxVersion}'
    implementation 'androidx.mediarouter:mediarouter:${androidxVersion}'
    implementation 'androidx.preference:preference:${androidxVersion}'
    implementation 'androidx.recyclerview:recyclerview:${androidxVersion}'
    implementation 'androidx.legacy:legacy-support-v4:${androidxVersion}'
    implementation 'com.github.bumptech.glide:glide:4.9.0'
    implementation 'com.github.bumptech.glide:okhttp-integration:4.9.0'
    implementation 'android.arch.lifecycle:common-java8:$lifecycle_version'
    implementation 'com.android.support:multidex:1.0.3'
    implementation 'com.google.android.datatransport:transport-api:2.2.0'
    implementation 'com.google.android.datatransport:transport-backend-cct:2.2.0'
    implementation 'com.google.android.datatransport:transport-runtime:2.2.0'
    implementation 'joda-time:joda-time:2.9.9'
    annotationProcessor 'androidx.annotation:annotation:1.1.0'
    annotationProcessor 'com.github.bumptech.glide:compiler:4.9.0'
}

Thêm khoá API vào ứng dụng của bạn

Phần này mô tả cách lưu trữ khoá API để bạn có thể tham chiếu khoá API một cách an toàn ứng dụng của bạn. Bạn không nên kiểm tra khoá API trong hệ thống quản lý phiên bản của mình. Vì vậy, bạn nên lưu trữ tệp này vào tệp secrets.properties. Tệp này nằm trong thư mục gốc của dự án. Để biết thêm thông tin về tệp secrets.properties, hãy xem Các tệp thuộc tính Gradle.

Để đơn giản hoá tác vụ này, bạn nên sử dụng Trình bổ trợ Secrets Gradle cho Android.

Cách cài đặt trình bổ trợ Secrets Gradle cho Android trong dự án Google Maps:

Trong Android Studio, hãy mở build.gradle hoặc build.gradle.kts cấp cao nhất rồi thêm mã sau vào phần tử dependencies trong buildscript.

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")
    }
}

Mở tệp build.gradle ở cấp mô-đun rồi thêm mã sau vào tệp Phần tử plugins.

Groovy

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

Kotlin

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

Trong tệp build.gradle ở cấp mô-đun, hãy đảm bảo rằng targetSdk và compileSdk được đặt thành 34.
Lưu tệp và đồng bộ hoá dự án với Gradle.
Mở tệp secrets.properties trong thư mục cấp cao nhất của bạn, sau đó thêm sau đây. Thay thế YOUR_API_KEY bằng khoá API. Lưu trữ khoá của bạn trong tệp này vì secrets.properties không được kiểm tra trong phần kiểm soát phiên bản hệ thống.
Lưu ý: Nếu tệp secrets.properties không hãy tạo tệp này trong cùng thư mục với tệp local.properties.
```
NAV_API_KEY=YOUR_API_KEY
```
Lưu tệp.
Tạo tệp local.defaults.properties trong thư mục cấp cao nhất cũng bằng cách này làm tệp secrets.properties, rồi thêm mã sau.

Lưu ý: Hãy nhập mã như hình minh hoạ. Không thay thế DEFAULT_API_KEY bằng khoá API của bạn.
```
NAV_API_KEY=DEFAULT_API_KEY
```
Mục đích của tệp này là cung cấp vị trí sao lưu cho khoá API nếu Không tìm thấy tệp secrets.properties để các bản dựng không bị lỗi. Điều này có thể xảy ra nếu bạn sao chép ứng dụng từ một hệ thống quản lý phiên bản, trong đó bỏ qua secrets.properties và bạn chưa tạo tệp secrets.properties cục bộ để cung cấp Khoá API.
Lưu tệp.
Trong tệp AndroidManifest.xml, chuyển đến com.google.android.geo.API_KEY rồi cập nhật android:value attribute. Nếu thẻ <meta-data> không tồn tại, hãy tạo thẻ này làm thẻ con của Thẻ <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.*"
}

Đưa các thuộc tính bắt buộc vào ứng dụng của bạn

Nếu sử dụng SDK điều hướng dành cho Android trong ứng dụng của mình, bạn phải cung cấp văn bản ghi công và giấy phép nguồn mở như một phần trong thông báo pháp lý của ứng dụng .

Bạn có thể tìm thấy văn bản ghi nhận tác giả và giấy phép nguồn mở bắt buộc trong SDK điều hướng dành cho tệp zip Android:

NOTICE.txt
LICENSES.txt