Thiết lập dự án Android Studio

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

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

Navigation SDK có sẵn 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.

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

    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>

  2. Nếu có bất kỳ phần phụ thuộc nào sử dụng Maps SDK, 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 vào Maps SDK.

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

Cập nhật các 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 tập lệnh bản dựng Gradle

  • Mở tệp build.gradle (Module:app) rồi 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 Navigation SDK và cân nhắc việc đặt các tuỳ chọn tối ưu hoá.

    Các chế độ cài đặt bắt buộc đối với Navigation SDK

    1. Đặt minSdkVersion thành 24 trở lên.
    2. Đặt targetSdkVersion thành 36 trở lên.
    3. Thêm chế độ cài đặt dexOptions giúp tăng javaMaxHeapSize.
    4. Đặt vị trí cho các thư viện bổ sung.
    5. Thêm repositories và dependencies cho Navigation SDK.
    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 tính năng rút gọn mã và rút gọn tài nguyên bằng R8/ProGuard để loại bỏ 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ữ 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ữ được Navigation SDK hỗ trợ.

    Thêm tính năng đơn giản hoá để hỗ trợ Java8

    • Nếu bạn đang tạo ứng dụng bằ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 support để 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ác tuỳ chọn biên dịch và phần phụ thuộc.
    • Đối với Android phiên bản 7.7.0 trở lên, bạn phải sử dụng Gradle 8.13, trình bổ trợ Android cho Gradle phiên bản 8.13.2 và thư viện Desugar com.android.tools:desugar_jdk_libs_nio:2.1.5.
    • Đối với Android phiên bản 7.3.0 đến 7.6.0, bạn phải sử dụng Gradle 8.11.1, trình bổ trợ Android cho Gradle phiên bản 8.10.0 và thư viện Desugar com.android.tools:desugar_jdk_libs_nio:2.0.3.
    • Bạn cần bật thư viện Desugar cho mô-đun app và mọi mô-đun trực tiếp phụ thuộc vào Navigation SDK.

Dưới đây là một ví dụ về tập lệnh bản dựng Gradle cho ứng dụng. Hãy kiểm tra các ứng dụng mẫu để biết các tập hợp phần phụ thuộc đã cập nhật, vì phiên bản Navigation SDK mà bạn đang sử dụng có thể hơi sớm hoặc muộn hơn 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.1.5'
}

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 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á này 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 bài viết 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 và lưu trữ khoá API:

  1. Trong Android Studio, hãy mở tệp build.gradle ở cấp gốc rồi thêm đoạn 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")
    }
}
  2. Mở tệp build.gradle ở cấp ứng dụng rồi thêm đoạn mã sau vào phần tử plugins.

    Groovy

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

    Kotlin

    plugins {
    id("com.android.application")
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. Nếu bạn sử dụng Android Studio, hãy đồng bộ hoá dự án với Gradle.
  4. Mở local.properties trong thư mục cấp dự án, sau đó thêm đoạn mã sau. Thay thế YOUR_API_KEY bằng khoá API của bạn. 
    MAPS_API_KEY=YOUR_API_KEY
  5. Bạn có thể thêm khoá API vào tệp AndroidManifest.xml hoặc cung cấp khoá API theo phương thức lập trình.
    • Thêm khoá API vào AndroidManifest.xml: 
      <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 cho nhiều API dựa trên Google Maps trên nền tảng Android, bao gồm cả Navigation SDK cho Android. Để tương thích ngược, API này 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 cho 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 trường hợp ngoại lệ.

    • Cung cấp khoá API theo phương thức lập trình:

      Trình bổ trợ Secrets Gradle giúp cung cấp khoá trong lớp BuildConfig. Trong quá trình khởi chạy ứng dụng (ví dụ: trong phương thức Application.onCreate()), hãy gọi phương thức như sau:

      Kotlin

      1. Thêm các câu lệnh nhập sau: 
        import com.google.android.libraries.navigation.NavigationApi
      2. Thêm nội dung sau vào phương thức Application.onCreate(): 
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY)

      Java

      1. Thêm các câu lệnh nhập sau: 
        import com.google.android.libraries.navigation.NavigationApi;
      2. Thêm nội dung sau vào phương thức Application.onCreate(): 
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY);
      Lưu ý: Khi sử dụng setApiKey(), hãy lưu ý những điều sau:
      • Cung cấp khoá API không rỗng và không có giá trị null.
      • Chỉ gọi setApiKey() một lần trong vòng đời của ứng dụng. Phương thức này sẽ gửi một IllegalStateException nếu được gọi nhiều lần.
      • Gọi setApiKey() trước khi khởi chạy bất kỳ thành phần Navigation SDK nào khác, chẳng hạn như Navigator.
      • Khoá mà bạn cung cấp bằng phương thức này sẽ ghi đè mọi khoá API trong AndroidManifest.xml.
      • Sử dụng Navigation SDK phiên bản 7.6 trở lên.

Đưa thông tin trích dẫn bắt buộc vào ứng dụng

Nếu bạn sử dụng Navigation SDK 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 Navigation SDK cho Android:

  • NOTICE.txt
  • LICENSES.txt

Nếu bạn là khách hàng của Dịch vụ di động hoặc Fleet Engine Deliveries

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

Phần phụ thuộc thủ công (không phải Gradle/Maven)

Nếu hệ thống xây dựng của bạn không giải quyết các phần phụ thuộc bắc cầu (chẳng hạn như Bazel) hoặc nếu bạn tích hợp AAR theo cách thủ công, thì bạn phải thêm các phần phụ thuộc này vào dự án. Gradle và Maven sẽ tự động giải quyết các phần phụ thuộc này.

  • androidx.datastore:datastore-core
  • androidx.datastore:datastore-guava
  • com.google.guava:listenablefuture
  • androidx.concurrent:concurrent-futures