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

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 cho Android phiên bản 5.0.0 trở lên.

Các hướng dẫn này giả định rằng bạn đã cài đặt IDE Android và quen với việc phát triển Android.

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 5.0.0 trở lên.

Một dự án Google Cloud Console có bật SDK Điều hướng. Để cấp phép, hãy hỏi người đại diện của Nền tảng Google Maps.
Ứng dụng của bạn phải chỉ định các phiên bản Android như sau:
- phiên bản mục tiêu phải là Android 13 (API cấp 33) trở lên.
- phiên bản tối thiểu phải là Android 6 (API cấp 23) trở lên.
Để chạy một ứng dụng được tạo bằng SDK điều hướng, thiết bị Android phải đáp ứng các yêu cầu sau:
- Cài đặt và bật Dịch vụ Google Play.
- 2GB RAM trở lên.
- Hỗ trợ OpenGL ES 2.0. Xem tài liệu về Khả năng tương thích với Android 6.0 nguồn mở cho Android để biết tính năng Tăng tốc đồ hoạ 2D và 3D
Các thuộc tính và văn bản cấp phép phải được thêm vào ứng dụng.

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

Để có thể tạo hoặc kiểm thử một ứng dụng, bạn cần tạo một dự án Cloud Console và thêm thông tin xác thực 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 cùng quyền truy cập 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ó 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 bạn yêu thích, hãy đăng nhập vào Cloud Console rồi tạo dự án Cloud Console.
Trong IDE, chẳng hạn như Android Studio, hãy tạo một dự án phát triển ứng dụng Android và ghi lại tên gói.
Hãy liên hệ với người đại diện của Nền tảng Google Maps để yêu cầu cấp quyền truy cập vào SDK Điều hướng cho dự án Cloud Console của bạn.
Trên trang tổng quan Cloud Console trong trình duyệt web, hãy tạo thông tin xác thực để tạo một khoá API có các hạn chế.
Trên trang Khoá API, hãy nhấp vào phần Ứng dụng Android trong phần Application Restricted (Hạn chế ứng dụng).
Nhấp vào Add the package name and vân tay, sau đó nhập tên gói 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

SDK Điều hướng được cung cấp thông qua Maven. 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 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)

Nội dung sau đây sử dụng kho lưu trữ Maven google(). Đây là cách đơn giản nhất và được đề xuất để thêm SDK Điều hướng vào dự án của bạ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 phiên bản mong muốn của SDK điều hướng cho Android.

Gradle

Thêm 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 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.

Và thêm nội dung sau vào build.gradle cấp cao nhất của bạn:

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 của bạn:

<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 trong từng phần phụ thuộc đã khai báo dựa trên 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>

Đị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 và sử dụng thành công SDK Navigation.

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

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 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 đặt các tuỳ chọn tối ưu hoá.

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 33 trở lên.
3. Thêm 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 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 tính năng 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 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ữ mà bạn thực sự sử dụng. Theo mặc định, Gradle sẽ bao gồm các chuỗi tài nguyên cho tất cả ngôn ngữ mà SDK điều hướng hỗ trợ.
Thêm quá trình đơ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ợ này sẽ mở rộng khả năng hỗ trợ sử dụng một số API ngôn ngữ Java 8. Hãy xem bài viết Hỗ trợ đơn giản hoá Java 8 để biết thêm thông tin. Hãy xem đoạn mã tập lệnh bản dựng mẫu bên dưới để biết cách biên dịch và các tuỳ chọn phần phụ thuộc.

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

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

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 trong 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 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ợ Bí mật cho 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 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 và thêm mã sau vào 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 của bạ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 mã sau. 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 phép kiểm tra trong một 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 này trong cùng thư mục với tệp local.properties.
```
MAPS_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 ý: Hãy nhập mã như minh hoạ. Đừng thay thế DEFAULT_API_KEY bằng khoá API.
```
MAPS_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 của mình.
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 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.*"
}

Bao gồm các thuộc tính bắt buộc trong ứng dụng của bạn

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 phân bổ và giấy phép nguồn mở vào mục 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 cần thiết và giấy phép nguồn mở trong SDK Điều hướng cho Android:

NOTICE.txt
LICENSES.txt

Nếu bạn là khách hàng sử dụng công cụ Di động hoặc Phân phối động cơ của Fleet Engine

Nếu bạn là khách hàng sử dụng Dịch vụ di chuyển hoặc Dịch vụ vận chuyển của Fleet Engine, hãy tìm hiểu về việc thanh toán trong tài liệu về Khả năng di chuyển. Để biết thêm thông tin về việc ghi lại giao dịch, hãy xem phần Thiết lập thanh toán, Ghi lại các giao dịch có thể lập hóa đơn, Báo cáo và Ghi lại giao dịch có thể lập hóa đơn (Android).