คู่มือนี้แสดงข้อกำหนดการกำหนดค่าบิลด์สำหรับการใช้ 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 ก่อนจึงจะสร้างหรือทดสอบแอปได้ โปรเจ็กต์ต้องมีการจัดสรรเพื่อเข้าถึง Navigation SDK คีย์ทั้งหมดภายในโปรเจ็กต์ Cloud Console จะได้รับสิทธิ์เข้าถึง Navigation SDK เดียวกัน คีย์หนึ่งๆ อาจเชื่อมโยงกับโปรเจ็กต์การพัฒนาได้มากกว่า 1 โปรเจ็กต์ หากมีโปรเจ็กต์คอนโซลอยู่แล้ว คุณสามารถเพิ่มคีย์ลงในโปรเจ็กต์ปัจจุบันได้
วิธีตั้งค่า
- ในเว็บเบราว์เซอร์ที่ชื่นชอบ ให้ลงชื่อเข้าใช้คอนโซล Cloud และสร้างโปรเจ็กต์ในคอนโซล Cloud
- ใน 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 ขึ้นไป (แนะนํา)
ตัวอย่างต่อไปนี้ใช้ที่เก็บ Maven ของ google()
ซึ่งเป็นวิธีที่ง่ายที่สุดและแนะนําในการเพิ่ม 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 นั้นใน 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 สำหรับ Navigation SDK เวอร์ชันก่อน v4.5 หรือกับ Driver 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 Services โดยใช้ 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 และพิจารณาตั้งค่าตัวเลือกการเพิ่มประสิทธิภาพด้วยการตั้งค่าที่จําเป็นสําหรับ Navigation SDK
- ตั้งค่า
minSdkVersion
เป็น 23 ขึ้นไป - ตั้งค่า
targetSdkVersion
เป็น 30 ขึ้นไป - เพิ่มการตั้งค่า
dexOptions
ที่เพิ่มjavaMaxHeapSize
- กำหนดตำแหน่งสำหรับคลังเพิ่มเติม
- เพิ่ม
repositories
และdependencies
สำหรับ Navigation SDK - แทนที่หมายเลขเวอร์ชันในข้อกําหนดด้วยเวอร์ชันล่าสุดที่พร้อมใช้งาน
การตั้งค่าที่ไม่บังคับเพื่อลดเวลาสร้าง
- เปิดใช้การลดขนาดโค้ดและการลดขนาดทรัพยากรโดยใช้ R8/ProGuard เพื่อนำโค้ดและทรัพยากรที่ไม่ได้ใช้งานออกจากทรัพยากร Dependency หากขั้นตอน R8/ProGuard ใช้เวลาในการเรียกใช้นานเกินไป ให้ลองเปิดใช้ multidex สำหรับการทํางานด้านการพัฒนา
- ลดจำนวนคำแปลภาษาที่รวมอยู่ในบิลด์: ตั้งค่า
resConfigs
สำหรับ 1 ภาษาในระหว่างการพัฒนา สําหรับบิลด์สุดท้าย ให้ตั้งค่าresConfigs
สำหรับภาษาที่คุณใช้จริง โดยค่าเริ่มต้น Gradle จะรวมสตริงทรัพยากรสำหรับทุกภาษาที่ Navigation SDK รองรับ
- ตั้งค่า
ด้านล่างนี้คือตัวอย่างสคริปต์การบิลด์ Gradle สําหรับแอปพลิเคชัน ตรวจสอบชุดทรัพยากร แอปตัวอย่างเพื่อดูชุดทรัพยากร Dependency ที่อัปเดตแล้ว เนื่องจากเวอร์ชันของ Navigation 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
เราขอแนะนำให้ใช้ปลั๊กอินข้อมูลลับ Gradle สําหรับ Android เพื่อปรับปรุงประสิทธิภาพของงานนี้
วิธีติดตั้งปลั๊กอินข้อมูลลับ 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 หลายรายการที่ทำงานบนแพลตฟอร์ม Android ซึ่งอิงตาม Google Maps รวมถึง 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