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 Navigation SDK cho Android. Hướng dẫn này giả định rằng bạn đã cài đặt IDE Android và quen thuộc với quá trình phát triển Android.

Yêu cầu tối thiểu để sử dụng Navigation SDK

Các yêu cầu này áp dụng cho Navigation SDK cho Android phiên bản 4.99 trở xuống.

Bảng điều khiển Google Cloud

dự án đã bật Navigation SDK. Để cung cấp, hãy hỏi đại diện Google Maps Platform.
Ứng dụng của bạn phải nhắm đến cấp độ API mục tiêu 30 trở lên.
Để chạy một ứng dụng được xây dựng bằng Navigation SDK, thiết bị Android phải cài đặt và bật Dịch vụ Google Play.
Bạn phải thêm thông tin trích dẫn và văn bản cấp phép vào ứng dụng.

Thiết lập dự án: Dự án trên bảng điều khiển Cloud và dự án Android

Trước khi có thể tạo hoặc kiểm thử một ứng dụng, bạn cần tạo một dự án trên bảng điều khiển Cloud và thêm thông tin xác thực khoá API. Dự án phải có quyền cung cấp để truy cập vào Navigation SDK. Tất cả các khoá trong dự án trên bảng điều khiển Cloud đều được cấp cùng một quyền truy cập vào Navigation SDK. 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 một 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, hãy đăng nhập vào bảng điều khiển Cloud rồi tạo dự án trên bảng điều khiển Cloud.
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.
Liên hệ với đại diện Google Maps Platform để cấp quyền truy cập vào Navigation SDK cho dự án trên bảng điều khiển Cloud.
Khi ở trang tổng quan của bảng điều khiển Cloud trong trình duyệt web, hãy tạo thông tin xác thực để tạo khoá API có các hạn chế.
Trên trang khoá API, hãy nhấp vào Ứng dụng Android trong khu vực Hạn chế về ứng dụng.
Nhấp vào Thêm tên gói và dấu vân tay, sau đó nhập tên gói của dự án phát triển và dấu vân tay SHA-1 cho khoá đó.
Nhấp vào Lưu.

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

Bạn có thể sử dụng Navigation SDK thông qua Maven hoặc dưới dạng gói AAR bundle. 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 những phương pháp sau.

Sử dụng Maven cho Navigation SDK phiên bản 4.5 trở lên (nên dùng)

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 Navigation SDK vào dự án

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.

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

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à không cần dùng trình bổ trợ com.google.cloud.artifactregistry.gradle-plugin nữa.

Và 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 nsure 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>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 Maps SDK, 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 vào 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>

Sử dụng Maven cho Navigation SDK trước phiên bản 4.5 hoặc với Driver SDK

Bạn vẫn có thể sử dụng Navigation SDK thông qua kho lưu trữ Maven ban đầu trong phần còn lại của các phiên bản 4. Đây là cùng một thư viện có tất cả các bản 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 Driver SDK 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, bạn phải đăng nhập vào dự án trên đám mây bằng 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 phần Điều kiện tiên quyết của tài liệu Consumer SDK. Quyền truy cập vào Navigation SDK đượ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 giữ chỗ VERSION_NUMBER cho phiên bản Navigation SDK.

Gradle

Thêm nội dung sau vào build.gradle ở cấp mô-đun:

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

Và 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>com.google.android.maps</groupId>
     <artifactId>navsdk</artifactId>
     <version>VERSION_NUMBER</version>
</dependency>
</dependencies>

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 mỗi phần phụ thuộc đã khai báo dựa vào 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>

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

Navigation SDK cũng có dưới dạng gói AAR bundle. Sau khi tạo dự án phát triển, bạn có thể tích hợp SDK. Các hướng dẫn này giả định rằng bạn sử dụng Android Studio cho IDE.

Tải phiên bản Navigation SDK mới nhất xuống từ Google Drive được chia sẻ và trích xuất phiên bản đó. 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 và 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 nội dung sau vào build.gradle ở cấp mô-đun:

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

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

Đị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) 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 Navigation SDK, đồng thời cân nhắc việc thiết lập các lựa 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 23 trở lên.
2. Đặt targetSdkVersion thành 30 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 sử dụng 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ố 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 bao gồm các chuỗi tài nguyên cho tất cả các ngôn ngữ mà Navigation SDK hỗ trợ.

Dưới đây là một ví dụ về tập lệnh bản dựng Gradle cho ứng dụng. Kiểm tra các ứng dụng mẫu để biết tập hợp các 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'
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. Make sure 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

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 vào 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 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 và lưu trữ khoá API:

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

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

Nếu bạn sử dụng Android Studio, hãy đồng bộ hoá dự án với Gradle.
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
```
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ể sử 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 phiên bản 2. 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 cả hai đều được chỉ định, API sẽ gửi một 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 khoá có sẵn 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, không có giá trị rỗng.
  - 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.

Thêm thông tin trích dẫn bắt buộc vào ứng dụng

Nếu sử dụng Navigation SDK cho Android trong ứng dụng, bạn phải thêm 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

Thiết lập dự án -- Phiên bản 4.99 trở xuống Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Yêu cầu tối thiểu để sử dụng Navigation SDK

Thiết lập dự án: Dự án trên bảng điều khiển Cloud và dự án Android

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

Sử dụng Maven cho Navigation SDK phiên bản 4.5 trở lên (nên dùng)

Gradle

Maven

Sử dụng Maven cho Navigation SDK trước phiên bản 4.5 hoặc với Driver SDK

Gradle

Maven

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

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

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

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

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

Groovy

Kotlin

Groovy

Kotlin

Kotlin

Java

Thêm thông tin trích dẫn bắt buộc vào ứng dụng

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