คู่มือนี้แสดงข้อกำหนดการกำหนดค่าบิลด์สำหรับการใช้ Navigation SDK สําหรับ Android วิธีการนี้จะถือว่าคุณมี Android IDE และคุ้นเคยกับการพัฒนาซอฟต์แวร์ Android
ข้อกำหนดขั้นต่ำสำหรับการใช้ Navigation SDK
ข้อกำหนดเหล่านี้มีผลกับ Navigation SDK สำหรับ Android เวอร์ชัน 4.99 และเวอร์ชันก่อนหน้า
โปรเจ็กต์ Google Cloud Console ที่เปิดใช้ Navigation SDK โปรดสอบถามตัวแทนของ Google Maps Platform เกี่ยวกับการเตรียมใช้งาน
แอปของคุณต้องกำหนดเป้าหมายเป็น API ระดับ 30 ขึ้นไป
หากต้องการเรียกใช้แอปที่สร้างด้วย Navigation SDK อุปกรณ์ Android จะต้องติดตั้งและเปิดใช้บริการ Google Play
โดยต้องเพิ่มข้อความระบุแหล่งที่มาและข้อความการอนุญาตให้ใช้สิทธิลงในแอป
ตั้งค่าโปรเจ็กต์: โปรเจ็กต์ Cloud Console และโปรเจ็กต์ Android
ก่อนจะสร้างหรือทดสอบแอป คุณต้องสร้างโปรเจ็กต์ Cloud Console และเพิ่มข้อมูลเข้าสู่ระบบคีย์ API โปรเจ็กต์ต้องมีการจัดสรรเพื่อเข้าถึง SDK การนำทาง คีย์ทั้งหมดในโปรเจ็กต์ Cloud Console ได้รับสิทธิ์เข้าถึง Navigation SDK ในระดับเดียวกัน คีย์อาจมีโปรเจ็กต์การพัฒนาเชื่อมโยงอยู่มากกว่า 1 โปรเจ็กต์ หากมีโปรเจ็กต์คอนโซลอยู่แล้ว คุณจะเพิ่มคีย์ในโปรเจ็กต์ปัจจุบันได้
วิธีตั้งค่า
- ลงชื่อเข้าใช้ Cloud Console ในเว็บเบราว์เซอร์ที่คุณชื่นชอบ แล้วสร้างโปรเจ็กต์ Cloud Console
- ใน IDE เช่น Android Studio ให้สร้างโปรเจ็กต์การพัฒนาแอป Android และจดชื่อแพ็กเกจไว้
- โปรดติดต่อตัวแทนของ Google Maps Platform เพื่อขอสิทธิ์เข้าถึง Navigation SDK สําหรับโปรเจ็กต์ในคอนโซลระบบคลาวด์
- ขณะที่อยู่ในแดชบอร์ด Cloud Console ในเว็บเบราว์เซอร์ ให้สร้างข้อมูลเข้าสู่ระบบเพื่อสร้างคีย์ API ที่มีข้อจำกัด
- ในหน้าคีย์ API ให้คลิกแอป Android ในพื้นที่ข้อจำกัดของแอปพลิเคชัน
- คลิกเพิ่มชื่อแพ็กเกจและลายนิ้วมือ แล้วป้อนชื่อแพ็กเกจของโปรเจ็กต์การพัฒนาและลายนิ้วมือ SHA-1 ของคีย์นั้น
- คลิกบันทึก
เพิ่ม Navigation SDK ลงในโปรเจ็กต์
Navigation SDK มีให้ใช้งานผ่าน Maven หรือแพ็กเกจ AAR หลังจากสร้างโปรเจ็กต์การพัฒนาแล้ว คุณสามารถผสานรวม SDK เข้ากับโปรเจ็กต์ได้โดยใช้แนวทางใดแนวทางหนึ่งต่อไปนี้
การใช้ Maven สำหรับ Navigation SDK เวอร์ชัน 4.5 ขึ้นไป (แนะนำ)
รายการต่อไปนี้ใช้ที่เก็บ google()
Maven ซึ่งเป็นวิธีที่ง่ายที่สุดในการเพิ่ม Navigation SDK ไปยังโปรเจ็กต์ของคุณ
เพิ่มทรัพยากร Dependency ต่อไปนี้ในการกำหนดค่า Gradle หรือ Maven ของคุณ โดยแทนที่ตัวยึดตำแหน่ง
VERSION_NUMBER
สำหรับ Navigation SDK สำหรับ Android เวอร์ชันที่ต้องการGradle
เพิ่มข้อมูลต่อไปนี้ลงใน
build.gradle
ระดับโมดูลdependencies { ... implementation 'com.google.android.libraries.navigation:navigation:VERSION_NUMBER' }
หากอัปเกรดจากที่เก็บ Maven เดิม โปรดทราบว่าชื่อกลุ่มและอาร์ติแฟกต์มีการเปลี่ยนแปลง และคุณไม่จำเป็นต้องใช้งานปลั๊กอิน
com.google.cloud.artifactregistry.gradle-plugin
อีกต่อไปและเพิ่มรายการต่อไปนี้ใน
build.gradle
ระดับบนสุด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
เพิ่มสิ่งต่อไปนี้ใน
pom.xml
<dependencies> ... <dependency> <groupId>com.google.android.libraries.navigation</groupId> <artifactId>navigation</artifactId> <version>VERSION_NUMBER</version> </dependency> </dependencies>
หากคุณมีทรัพยากร Dependency ที่ใช้ Maps SDK คุณต้องยกเว้นการขึ้นต่อกันที่ Dependency ที่ประกาศแต่ละรายการซึ่งอาศัย 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>
การใช้ Maven สำหรับ SDK การนำทางเวอร์ชันก่อนหน้าเวอร์ชัน 4.5 หรือ SDK ไดรเวอร์
Navigation SDK จะยังคงพร้อมใช้งานผ่านที่เก็บ Maven เดิมในเวอร์ชัน v4 ที่เหลือ ไลบรารีนี้เป็นไลบรารีเดียวกันที่มีการอัปเดตทั้งหมดเหมือนกับเวอร์ชันด้านบน และเข้ากันได้กับ Driver SDK และไลบรารีอื่นๆ ในระหว่างการเปลี่ยนผ่าน การใช้ข้อกำหนดนี้ต้องเข้าสู่ระบบโปรเจ็กต์ที่อยู่ในระบบคลาวด์ผ่าน gcloud
เมื่อคอมไพล์
- ตั้งค่าสภาพแวดล้อมเพื่อเข้าถึงที่เก็บ Maven ของ Google ตามที่อธิบายไว้ในส่วนข้อกําหนดเบื้องต้นของเอกสารประกอบ SDK สําหรับผู้บริโภค การเข้าถึง Navigation SDK จะควบคุมผ่านกลุ่มพื้นที่ทํางาน
เพิ่มทรัพยากร Dependency ต่อไปนี้ในการกําหนดค่า Gradle หรือ Maven โดยแทนที่ตัวยึดตําแหน่ง
VERSION_NUMBER
ด้วยเวอร์ชัน Navigation SDK ที่ต้องการGradle
เพิ่มข้อมูลต่อไปนี้ลงใน
build.gradle
ระดับโมดูลdependencies { ... implementation 'com.google.android.maps:navsdk:VERSION_NUMBER' }
และเพิ่มข้อมูลต่อไปนี้ลงใน
build.gradle
ระดับบนสุด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
เพิ่มสิ่งต่อไปนี้ใน
pom.xml
<dependencies> ... <dependency> <groupId>com.google.android.maps</groupId> <artifactId>navsdk</artifactId> <version>VERSION_NUMBER</version> </dependency> </dependencies>
หากมี Dependency ที่ใช้ Maps SDK คุณต้องยกเว้น Dependency นั้นใน Dependency ที่ประกาศแต่ละรายการซึ่งใช้ 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>
การใช้แพ็กเกจ AAR ที่ดาวน์โหลดมา (ไม่แนะนำ)
Navigation SDK มีให้บริการเป็นกลุ่ม AAR ด้วย หลังจากสร้างโปรเจ็กต์การพัฒนาแล้ว คุณจะผสานรวม SDK ได้ วิธีการเหล่านี้จะสมมติว่าคุณใช้ Android Studio เป็น IDE
ดาวน์โหลด Navigation SDK เวอร์ชันล่าสุดจาก Google ไดรฟ์ที่แชร์ แล้วแตกไฟล์ หากไม่มีสิทธิ์เข้าถึง โปรดติดต่อตัวแทนของคุณ
ใน Android Studio ให้เปิดโปรเจ็กต์และเพิ่มแพ็กเกจบริการ Google Play โดยใช้ SDK Manager
จากไดเรกทอรีไฟล์ ZIP ให้คัดลอก
libs/google_navigation_navmap.aar
ไปยังไดเรกทอรีapp/libs
ของโปรเจ็กต์เพิ่มข้อมูลต่อไปนี้ลงใน
build.gradle
ระดับโมดูลimplementation(name: 'google_navigation_navmap', ext: 'aar')
และเพิ่มรายการต่อไปนี้ใน
build.gradle
ระดับบนสุด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' } } }
กำหนดค่าบิลด์
หลังจากสร้างโปรเจ็กต์แล้ว คุณสามารถกําหนดการตั้งค่าเพื่อให้การบิลด์และการใช้ Navigation SDK สําเร็จ
อัปเดตที่พักในพื้นที่
- ในโฟลเดอร์สคริปต์ Gradle ให้เปิดไฟล์
local.properties
แล้วเพิ่มandroid.useDeprecatedNdk=true
อัปเดตสคริปต์การบิลด์ Gradle
เปิดไฟล์
build.gradle (Module:app)
และใช้หลักเกณฑ์ต่อไปนี้เพื่ออัปเดตการตั้งค่าให้เป็นไปตามข้อกำหนดของ Navigation SDK และพิจารณาตั้งค่าตัวเลือกการเพิ่มประสิทธิภาพด้วยการตั้งค่าที่จำเป็นสำหรับ SDK การนำทาง
- ตั้งค่า
minSdkVersion
เป็น 23 ขึ้นไป - ตั้งค่า
targetSdkVersion
เป็น 30 ขึ้นไป - เพิ่มการตั้งค่า
dexOptions
ที่เพิ่มjavaMaxHeapSize
- กำหนดตำแหน่งสำหรับคลังเพิ่มเติม
- เพิ่ม
repositories
และdependencies
สำหรับ Navigation SDK - แทนที่หมายเลขเวอร์ชันในทรัพยากร Dependency ด้วยเวอร์ชันล่าสุดที่มีอยู่
การตั้งค่าที่ไม่บังคับเพื่อลดเวลาบิลด์
- เปิดใช้การลดขนาดโค้ดและการลดขนาดทรัพยากรโดยใช้ R8/ProGuard เพื่อนำโค้ดและทรัพยากรที่ไม่ได้ใช้งานออกจากทรัพยากร Dependency หากขั้นตอน R8/ProGuard ใช้เวลานานเกินไป ให้พิจารณาเปิดใช้ multidex สำหรับงานพัฒนา
- ลดจำนวนคำแปลภาษาที่รวมอยู่ในบิลด์: ตั้งค่า
resConfigs
สำหรับ 1 ภาษาในระหว่างการพัฒนา สําหรับบิลด์สุดท้าย ให้ตั้งค่าresConfigs
สำหรับภาษาที่คุณใช้จริง โดยค่าเริ่มต้น Gradle รวมสตริงทรัพยากรสำหรับทุกภาษาที่ Navigation SDK รองรับ
- ตั้งค่า
ด้านล่างเป็นตัวอย่างของสคริปต์บิลด์ Gradle สำหรับแอปพลิเคชัน ตรวจสอบตัวอย่างแอปเพื่อดูชุดทรัพยากร Dependency ที่อัปเดตใหม่ เนื่องจากเวอร์ชัน SDK การนำทางที่คุณใช้อาจอยู่ก่อนหรือช้ากว่าเอกสารนี้เล็กน้อย
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'
}
เพิ่มคีย์ API ลงในแอป
ส่วนนี้อธิบายวิธีจัดเก็บคีย์ API เพื่อให้แอปอ้างอิงได้อย่างปลอดภัย คุณไม่ควรตรวจสอบคีย์ API ในระบบควบคุมเวอร์ชัน เราจึงขอแนะนำให้จัดเก็บไว้ในไฟล์ secrets.properties
ซึ่งอยู่ในไดเรกทอรีรูทของโปรเจ็กต์ ดูข้อมูลเพิ่มเติมเกี่ยวกับไฟล์ secrets.properties
ได้ที่ไฟล์พร็อพเพอร์ตี้ Gradle
เราขอแนะนำให้ใช้ปลั๊กอิน Secrets Gradle สำหรับ Android เพื่อปรับปรุงการทำงานนี้ให้มีประสิทธิภาพยิ่งขึ้น
วิธีติดตั้งปลั๊กอิน Secrets Gradle สำหรับ Android ในโปรเจ็กต์ Google Maps
-
ใน Android Studio ให้เปิดไฟล์
build.gradle.kts
หรือbuild.gradle
ระดับบนสุด แล้วเพิ่มโค้ดต่อไปนี้ลงในองค์ประกอบdependencies
ใต้buildscript
Kotlin
buildscript { dependencies { classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1") } }
ดึงดูด
buildscript { dependencies { classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1" } }
-
เปิดไฟล์
build.gradle.kts
หรือbuild.gradle
ระดับโมดูล และเพิ่มโค้ดต่อไปนี้ลงในองค์ประกอบplugins
Kotlin
plugins { // ... id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
ดึงดูด
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
- ในไฟล์
build.gradle.kts
หรือbuild.gradle
ระดับโมดูล โปรดตรวจสอบว่าได้ตั้งค่าtargetSdk
และcompileSdk
เป็น 34 - บันทึกไฟล์และซิงค์โปรเจ็กต์กับ Gradle
-
เปิดไฟล์
secrets.properties
ในไดเรกทอรีระดับบนสุด แล้วเพิ่มโค้ดต่อไปนี้ แทนที่YOUR_API_KEY
ด้วยคีย์ API เก็บคีย์ไว้ในไฟล์นี้เนื่องจากsecrets.properties
ได้รับการยกเว้นไม่ให้ตรวจสอบในระบบควบคุมเวอร์ชันNAV_API_KEY=YOUR_API_KEY
- บันทึกไฟล์
-
สร้างไฟล์
local.defaults.properties
ในไดเรกทอรีระดับบนสุด ซึ่งอยู่ในโฟลเดอร์เดียวกับไฟล์secrets.properties
แล้วเพิ่มโค้ดต่อไปนี้NAV_API_KEY=DEFAULT_API_KEY
วัตถุประสงค์ของไฟล์นี้คือระบุตำแหน่งสำรองสำหรับคีย์ API ในกรณีที่ไม่พบไฟล์
secrets.properties
เพื่อให้การสร้างไม่ล้มเหลว กรณีนี้อาจเกิดขึ้นได้หากคุณโคลนแอปจากระบบควบคุมเวอร์ชันที่ไม่ได้ใส่secrets.properties
และคุณยังไม่ได้สร้างไฟล์secrets.properties
ในเครื่องเพื่อระบุคีย์ API - บันทึกไฟล์
-
ในไฟล์
AndroidManifest.xml
ให้ไปที่com.google.android.geo.API_KEY
แล้วอัปเดตandroid:value attribute
หากไม่มีแท็ก<meta-data>
ให้สร้างเป็นแท็กย่อยของแท็ก<application>
<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
หมายเหตุ:
com.google.android.geo.API_KEY
คือชื่อข้อมูลเมตาที่แนะนําสำหรับคีย์ API คีย์ที่ใช้ชื่อนี้สามารถใช้เพื่อตรวจสอบสิทธิ์ API ต่างๆ ใน Google Maps บนแพลตฟอร์ม Android ซึ่งรวมถึง Navigation SDK สำหรับ Android สำหรับความเข้ากันได้แบบย้อนหลัง API ยังรองรับชื่อcom.google.android.maps.v2.API_KEY
ด้วย ชื่อเดิมนี้อนุญาตให้ตรวจสอบสิทธิ์กับ Android Maps API v2 เท่านั้น แอปพลิเคชันจะระบุชื่อข้อมูลเมตาของคีย์ API ได้เพียงชื่อเดียวเท่านั้น หากระบุทั้ง 2 รายการ API จะแสดงข้อยกเว้น -
ใน Android Studio ให้เปิดไฟล์
build.gradle.kts
หรือbuild.gradle
ระดับโมดูล แล้วแก้ไขพร็อพเพอร์ตี้secrets
หากไม่มีพร็อพเพอร์ตี้secrets
ให้เพิ่มพร็อพเพอร์ตี้นั้นแก้ไขพร็อพเพอร์ตี้ของปลั๊กอินเพื่อตั้งค่า
propertiesFileName
เป็นsecrets.properties
, ตั้งค่าdefaultPropertiesFileName
เป็นlocal.defaults.properties
และตั้งค่าพร็อพเพอร์ตี้อื่นๆ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.*" }
ดึงดูด
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.*" }
ใส่การระบุแหล่งที่มาที่จำเป็นในแอป
หากใช้ Navigation SDK สําหรับ Android ในแอป คุณต้องใส่ข้อความระบุแหล่งที่มาและใบอนุญาตโอเพนซอร์สในส่วนประกาศทางกฎหมายของแอป
คุณดูข้อความระบุแหล่งที่มาที่จําเป็นและใบอนุญาตโอเพนซอร์สได้ในไฟล์ ZIP ของ Navigation SDK สําหรับ Android
NOTICE.txt
LICENSES.txt