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

Trang này giải thích cách tích hợp SDK điều hướng vào dự án phát triển của bạn.

Thêm Navigation SDK vào dự án

Bạn có thể sử dụng Navigation SDK thông qua Kho lưu trữ Maven của Google. Bạn có thể thêm SDK vào dự án bằng cách sử dụng cấu hình build.gradle của Gradle hoặc pom.xml của Maven.

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

Gradle

Thêm nội dung sau vào build.gradle ở cấp mô-đun:
```
dependencies {
        ...
        implementation 'com.google.android.libraries.navigation:navigation:VERSION_NUMBER'
}
```
Maven

Thêm nội dung sau vào pom.xml:
```
<dependencies>
  ...
  <dependency>
    <groupId>com.google.android.libraries.navigation</groupId>
    <artifactId>navigation</artifactId>
    <version>VERSION_NUMBER</version>
  </dependency>
</dependencies>
```
Lưu ý: Nếu bạn là khách hàng của Dịch vụ di động đang nâng cấp từ kho lưu trữ Maven riêng ban đầu, hãy lưu ý rằng tên nhóm và 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 cần thiết nữa.

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 đó trong mỗi phần phụ thuộc đã khai báo dựa trên SDK Maps.

Gradle

Thêm nội dung 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 nội dung sau vào pom.xml:

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

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

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

Cập nhật thuộc tính cục bộ

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

Cập nhật thuộc tính gradle

Trong thư mục Tập lệnh Gradle, hãy mở tệp gradle.properties và thêm nội dung sau đây nếu chưa có:
1. android.useAndroidX=true
2. android.enableJetifier=true

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

Mở tệp build.gradle (Module:app) và sử dụng các nguyên tắc sau để cập nhật chế độ cài đặt nhằm đáp ứng các yêu cầu đối với SDK điều hướng, đồng thời cân nhắc việc thiết lập các tuỳ chọn tối ưu hoá.

Chế độ cài đặt bắt buộc cho Navigation SDK
1. Đặt minSdkVersion thành 23 trở lên.
2. Đặt targetSdkVersion thành 34 trở lên.
3. Thêm chế độ cài đặt dexOptions để tăng javaMaxHeapSize.
4. Đặt vị trí cho các thư viện bổ sung.
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 phiên bản mới nhất hiện có.
Chế độ cài đặt không bắt buộc để giảm thời gian tạo bản dựng
- Bật tính năng rút gọn mã và rút gọn tài nguyên bằng cách sử dụ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 bật tính năng 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 các chuỗi tài nguyên cho tất cả ngôn ngữ mà Navigation SDK hỗ trợ.
Thêm tính năng đơn giản hoá để hỗ trợ Java8
- Nếu bạn đang xây dựng ứng dụng bằng cách sử dụng trình bổ trợ Android cho Gradle 4.0.0 trở lên thì trình bổ trợ sẽ mở rộng khả năng hỗ trợ sử dụng một số API ngôn ngữ Java 8. Hãy xem phần Hỗ trợ đơn giản hoá Java 8 để biết thêm thông tin. Hãy xem đoạn mã ví dụ về tập lệnh bản dựng bên dưới để biết cách biên dịch và các tuỳ chọn phần phụ thuộc.
- Bạn nên sử dụng Gradle 8.4, trình bổ trợ Android cho Gradle phiên bản 8.3.0 và thư viện Đơn giản hoá com.android.tools:desugar_jdk_libs_nio:2.0.3. Chế độ thiết lập này tương thích với Navigation SDK cho Android phiên bản 6.0.0 trở lên.
- Bạn cần bật thư viện đơn giản hoá cho mô-đun app và mọi mô-đun phụ thuộc trực tiếp vào SDK Điều hướng.

Dưới đây là ví dụ về tập lệnh bản dựng Gradle cho ứng dụng. Hãy kiểm tra ứng dụng mẫu để biết các nhóm phần phụ thuộc đã cập nhật, vì phiên bản SDK điều hướng mà bạn đang sử dụng có thể hơi sớm hoặc trễ so với tài liệu này.

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 34
        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_nio:2.0.3'
}

Thêm khoá API vào ứng dụng

Phần này mô tả cách lưu trữ khoá API để ứng dụng của bạn có thể tham chiếu khoá đó một cách an toàn. Bạn không nên kiểm tra khoá API vào hệ thống quản lý phiên bản, vì vậy, bạn nên lưu trữ khoá đó trong tệp secrets.properties 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 phần Tệp thuộc tính Gradle.

Để đơn giản hoá nhiệm 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ở tệp build.gradle.kts hoặc build.gradle cấp cao nhất và thêm mã sau vào phần tử dependencies trong buildscript.

Kotlin

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

Groovy

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

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

Kotlin

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

Groovy

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

Trong tệp build.gradle.kts hoặc build.gradle ở cấp mô-đun, hãy đảm bảo rằng bạn đặt targetSdk và compileSdk 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, sau đó thêm mã sau. Thay thế YOUR_API_KEY bằng khoá API của bạn. Lưu trữ khoá của bạn trong tệp này vì secrets.properties không được đưa vào hệ thống quản lý phiên bản.
Lưu ý: Nếu tệp secrets.properties không tồn tại, hãy tạo tệp đó 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 thư mục với tệp secrets.properties, sau đó thêm mã sau.

Lưu ý: Nhập mã như minh hoạ. Đừng thay thế DEFAULT_API_KEY bằng khoá API.
```
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 nhân bản ứng dụng từ một hệ thống quản lý phiên bản 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, hãy 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 dưới dạng thẻ con của thẻ <application>.
```
<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />
```
Lưu ý: com.google.android.geo.API_KEY là tên siêu dữ liệu được đề xuất cho khoá API. Bạn có thể dùng khoá có tên này để xác thực với nhiều API dựa trên Google Maps trên nền tảng Android, bao gồm cả Navigation SDK cho Android. Để có khả năng tương thích ngược, API cũng hỗ trợ tên com.google.android.maps.v2.API_KEY. Tên cũ này chỉ cho phép xác thực với Android Maps API v2. Một ứng dụng chỉ có thể chỉ định một trong các tên siêu dữ liệu khoá API. Nếu bạn chỉ định cả hai, API sẽ gửi một ngoại lệ.

Trong Android Studio, hãy mở tệp build.gradle.kts hoặc build.gradle ở cấp mô-đun và chỉnh sửa thuộc tính secrets. Nếu thuộc tính secrets không tồn tại, hãy thêm thuộc tính này.

Chỉnh sửa các thuộc tính của trình bổ trợ để đặt propertiesFileName thành secrets.properties, đặt defaultPropertiesFileName thành local.defaults.properties và đặt bất kỳ thuộc tính nào khác.

Kotlin

secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
    // 2. Add this line, where YOUR_API_KEY is your API key:
    //        MAPS_API_KEY=YOUR_API_KEY
    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.*"
}

Groovy

secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
    // 2. Add this line, where YOUR_API_KEY is your API key:
    //        MAPS_API_KEY=YOUR_API_KEY
    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.*"
}

Thêm thông tin ghi công bắt buộc vào ứng dụng

Nếu sử dụng SDK Điều hướng cho Android trong ứng dụng, bạn phải đưa văn bản ghi công và giấy phép nguồn mở vào phần 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 công bắt buộc và giấy phép nguồn mở trong tệp zip SDK Điều hướng cho Android:

NOTICE.txt
LICENSES.txt

Nếu bạn là khách hàng của dịch vụ Phân phối động cơ cho xe cơ giới hoặc Phân phối động cơ cho đội xe

Nếu bạn là khách hàng của Mobility hoặc Fleet Engine Deliveries, hãy tìm hiểu về việc thanh toán trong tài liệu về Mobility. Để biết thêm thông tin về cách ghi lại giao dịch, hãy xem phần Thiết lập hệ thống thanh toán, Ghi lại giao dịch có thể tính phí, Báo cáo và Ghi lại giao dịch có thể tính phí (Android).