สร้างแอป Android ที่แสดงแผนที่โดยใช้เทมเพลตมุมมอง Google Maps สำหรับ Android Studio หากมีโปรเจ็กต์ Android Studio อยู่แล้วที่ต้องการตั้งค่า โปรดดูตั้งค่าโปรเจ็กต์ Android Studio
การเริ่มต้นใช้งานอย่างรวดเร็วนี้มีไว้สำหรับนักพัฒนาซอฟต์แวร์ที่คุ้นเคยกับการพัฒนา Android ขั้นพื้นฐานด้วย Kotlin หรือ Java
เกี่ยวกับสภาพแวดล้อมในการพัฒนาซอฟต์แวร์
บทแนะนำเริ่มต้นฉบับนี้พัฒนาโดยใช้ Android Studio Hedgehog และปลั๊กอิน Android Gradle เวอร์ชัน 8.2
ตั้งค่าอุปกรณ์ Android
หากต้องการเรียกใช้แอปที่ใช้ Maps SDK สําหรับ Android คุณต้องติดตั้งใช้งานแอปในอุปกรณ์ Android หรือโปรแกรมจําลอง Android ที่ใช้ Android 5.0 ขึ้นไปและมี Google API
- หากต้องการใช้อุปกรณ์ Android ให้ทำตามวิธีการที่หัวข้อเรียกใช้แอปในอุปกรณ์ฮาร์ดแวร์
- หากต้องการใช้โปรแกรมจำลอง Android คุณสามารถสร้างอุปกรณ์เสมือนและติดตั้งโปรแกรมจำลองได้โดยใช้เครื่องมือจัดการอุปกรณ์เสมือน Android (AVD) ที่มาพร้อมกับ Android Studio
สร้างโปรเจ็กต์ Google Maps ใน Android Studio
ขั้นตอนการสร้างโปรเจ็กต์ Google Maps ใน Android Studio มีการเปลี่ยนแปลงใน Android Studio เวอร์ชัน Flamingo ขึ้นไป
เปิด Android Studio แล้วคลิกโปรเจ็กต์ใหม่ในหน้าต่างยินดีต้อนรับสู่ Android Studio
ในหน้าต่างโปรเจ็กต์ใหม่ ภายในหมวดหมู่โทรศัพท์และแท็บเล็ต ให้เลือกไม่มีกิจกรรม แล้วคลิกถัดไป
กรอกแบบฟอร์มโปรเจ็กต์ใหม่
ตั้งค่าภาษาเป็น Java หรือ Kotlin Maps SDK สำหรับ Android รองรับทั้ง 2 ภาษาอย่างเต็มรูปแบบ ดูข้อมูลเพิ่มเติมเกี่ยวกับ Kotlin ได้ที่หัวข้อพัฒนาแอป Android ด้วย Kotlin
ตั้งค่า SDK ขั้นต่ำเป็นเวอร์ชัน SDK ที่เข้ากันได้กับอุปกรณ์ทดสอบ คุณต้องเลือกเวอร์ชันที่มากกว่าเวอร์ชันขั้นต่ำที่ Maps SDK สำหรับ Android เวอร์ชัน 19.0.x กำหนด ซึ่งก็คือ Android API ระดับ 21 ("Lollipop"; Android 5.0) ขึ้นไป ดูข้อมูลล่าสุดเกี่ยวกับข้อกําหนดของเวอร์ชัน SDK ได้ที่บันทึกประจำรุ่น
ตั้งค่าภาษาการกําหนดค่าบิลด์เป็น Kotlin DSL หรือ Groovy DSL ข้อมูลโค้ดสำหรับภาษาการกำหนดค่าบิลด์ทั้ง 2 ภาษาจะแสดงในขั้นตอนต่อไปนี้
คลิกเสร็จสิ้น
Android Studio จะเริ่มต้น Gradle และสร้างโปรเจ็กต์ อาจใช้เวลาสักครู่
เพิ่มกิจกรรมการดูใน Google Maps
- คลิกขวาที่โฟลเดอร์
app
ในโปรเจ็กต์ เลือกใหม่ > Google > กิจกรรมการดูใน Google Maps
ในกล่องโต้ตอบกิจกรรม Android ใหม่ ให้เลือกช่องทําเครื่องหมายกิจกรรม Launcher
เลือกเสร็จสิ้น
ดูข้อมูลเพิ่มเติมได้ที่หัวข้อเพิ่มโค้ดจากเทมเพลต
- คลิกขวาที่โฟลเดอร์
เมื่อบิลด์เสร็จแล้ว Android Studio จะเปิดไฟล์
AndroidManifest.xml
และMapsActivity
กิจกรรมของคุณอาจมีชื่ออื่น แต่กิจกรรมดังกล่าวคือกิจกรรมที่คุณกําหนดค่าไว้ในระหว่างการตั้งค่า
ตั้งค่าโปรเจ็กต์ Google Cloud
ทําตามขั้นตอนการตั้งค่า Cloud Console ที่จําเป็นโดยคลิกผ่านแท็บต่อไปนี้
ขั้นตอนที่ 1
คอนโซล
-
ในคอนโซล Google Cloud ให้คลิกสร้างโปรเจ็กต์ในหน้าตัวเลือกโปรเจ็กต์เพื่อเริ่มสร้างโปรเจ็กต์ Cloud ใหม่
-
ตรวจสอบว่าเปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์ Cloud แล้ว ยืนยันว่าโปรเจ็กต์เปิดใช้การเรียกเก็บเงินแล้ว
Google Cloud เสนอช่วงทดลองใช้แบบไม่มีค่าใช้จ่าย ช่วงทดลองใช้จะสิ้นสุดลงเมื่อครบ 90 วันหรือหลังจากที่บัญชีมีค่าใช้จ่ายสะสมครบ $300 แล้วแต่ว่ากรณีใดจะเกิดขึ้นก่อน ยกเลิกได้ทุกเมื่อ Google Maps Platform มีเครดิตรายเดือนมูลค่า $200 แบบตามรอบ ดูข้อมูลเพิ่มเติมได้ที่เครดิตในบัญชีสำหรับการเรียกเก็บเงินและการเรียกเก็บเงิน
Cloud SDK
gcloud projects create "PROJECT"
อ่านข้อมูลเพิ่มเติมเกี่ยวกับ Google Cloud SDK , การติดตั้ง Cloud SDK และคําสั่งต่อไปนี้
ขั้นตอนที่ 2
หากต้องการใช้ Google Maps Platform คุณต้องเปิดใช้ API หรือ SDK ที่คุณวางแผนจะใช้กับโปรเจ็กต์
คอนโซล
Cloud SDK
gcloud services enable \ --project "PROJECT" \ "maps-android-backend.googleapis.com"
อ่านข้อมูลเพิ่มเติมเกี่ยวกับ Google Cloud SDK , การติดตั้ง Cloud SDK และคําสั่งต่อไปนี้
ขั้นตอนที่ 3
ขั้นตอนนี้จะทําตามกระบวนการสร้างคีย์ API เท่านั้น หากคุณใช้คีย์ API ในเวอร์ชันที่ใช้งานจริง เราขอแนะนําอย่างยิ่งให้คุณจํากัดคีย์ API ดูข้อมูลเพิ่มเติมได้ในหน้าการใช้คีย์ API สำหรับผลิตภัณฑ์หนึ่งๆ โดยเฉพาะ
คีย์ API คือตัวระบุที่ไม่ซ้ำกันซึ่งตรวจสอบสิทธิ์คําขอที่เชื่อมโยงกับโปรเจ็กต์ของคุณเพื่อวัตถุประสงค์ด้านการใช้งานและการเรียกเก็บเงิน คุณต้องมีคีย์ API ที่เชื่อมโยงกับโปรเจ็กต์อย่างน้อย 1 คีย์
วิธีสร้างคีย์ API
คอนโซล
-
ไปที่หน้า Google Maps Platform > ข้อมูลเข้าสู่ระบบ
-
ในหน้าข้อมูลเข้าสู่ระบบ ให้คลิกสร้างข้อมูลเข้าสู่ระบบ > คีย์ API
กล่องโต้ตอบสร้างคีย์ API แล้วจะแสดงคีย์ API ที่สร้างขึ้นใหม่ -
คลิกปิด
คีย์ API ใหม่จะแสดงอยู่ในหน้าข้อมูลเข้าสู่ระบบในส่วนคีย์ API
(อย่าลืมจํากัดคีย์ API ก่อนนำไปใช้ในเวอร์ชันที่ใช้งานจริง)
Cloud SDK
gcloud alpha services api-keys create \ --project "PROJECT" \ --display-name "DISPLAY_NAME"
อ่านข้อมูลเพิ่มเติมเกี่ยวกับ Google Cloud SDK , การติดตั้ง Cloud SDK และคําสั่งต่อไปนี้
เพิ่มคีย์ 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
ได้รับการยกเว้นไม่ให้ตรวจสอบในระบบควบคุมเวอร์ชันMAPS_API_KEY=YOUR_API_KEY
- บันทึกไฟล์
-
สร้างไฟล์
local.defaults.properties
ในไดเรกทอรีระดับบนสุด ซึ่งเป็นโฟลเดอร์เดียวกับไฟล์secrets.properties
แล้วเพิ่มโค้ดต่อไปนี้MAPS_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 ซึ่งรวมถึง Maps 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.*" }
ดูโค้ด
ตรวจสอบโค้ดที่เทมเพลตระบุ โดยเฉพาะอย่างยิ่ง ให้ดูไฟล์ต่อไปนี้ในโปรเจ็กต์ Android Studio
ไฟล์กิจกรรมใน Maps
ไฟล์กิจกรรมแผนที่คือกิจกรรมหลักของแอป และมีโค้ดสำหรับจัดการและแสดงแผนที่ โดยค่าเริ่มต้น ไฟล์ที่กําหนดกิจกรรมจะมีชื่อว่า MapsActivity.java
หรือ MapsActivity.kt
หากคุณตั้งค่า Kotlin เป็นภาษาสําหรับแอป
องค์ประกอบหลักของกิจกรรมใน Maps
ออบเจ็กต์
SupportMapFragment
จะจัดการวงจรชีวิตของแผนที่ และเป็นองค์ประกอบหลักของ UI ของแอปออบเจ็กต์
GoogleMap
ให้สิทธิ์เข้าถึงข้อมูลแผนที่และมุมมอง นี่คือคลาสหลักของ Maps SDK สำหรับ Android คำแนะนำเกี่ยวกับออบเจ็กต์แผนที่อธิบายออบเจ็กต์SupportMapFragment
และGoogleMap
โดยละเอียดฟังก์ชัน
moveCamera
จะวางกึ่งกลางแผนที่ที่พิกัดLatLng
สำหรับซิดนีย์ ออสเตรเลีย การตั้งค่าแรกที่ต้องกำหนดเมื่อเพิ่มแผนที่มักจะเป็นตำแหน่งแผนที่และการตั้งค่ากล้อง เช่น มุมมอง การวางแนวแผนที่ และระดับการซูม ดูรายละเอียดได้จากคำแนะนำกล้องและมุมมองฟังก์ชัน
addMarker
จะเพิ่มเครื่องหมายลงในพิกัดของซิดนีย์ ดูรายละเอียดได้จากคู่มือเครื่องหมาย
ไฟล์ Gradle ของโมดูล
ไฟล์โมดูล build.gradle.kts
มีทรัพยากร Dependency ของแผนที่ต่อไปนี้ ซึ่ง Maps SDK สำหรับ Android ต้องใช้
dependencies { // Maps SDK for Android implementation("com.google.android.gms:play-services-maps:19.0.0") }
ดูข้อมูลเพิ่มเติมเกี่ยวกับการจัดการทรัพยากร Dependency ของ Maps ได้ที่การกำหนดเวอร์ชัน
ไฟล์เลย์เอาต์ XML
ไฟล์ activity_maps.xml
คือไฟล์เลย์เอาต์ XML ที่กําหนดโครงสร้าง UI ของแอป ไฟล์จะอยู่ในไดเรกทอรี res/layout
ไฟล์ activity_maps.xml
จะประกาศข้อมูลโค้ดที่ประกอบด้วยองค์ประกอบต่อไปนี้
tools:context
ตั้งค่ากิจกรรมเริ่มต้นของข้อมูลโค้ดเป็นMapsActivity
ซึ่งกำหนดไว้ในไฟล์กิจกรรม Mapsandroid:name
ตั้งค่าชื่อคลาสของฟragment เป็นSupportMapFragment
ซึ่งเป็นประเภท Fragment ที่ใช้กับไฟล์กิจกรรม Maps
ไฟล์เลย์เอาต์ XML มีโค้ดต่อไปนี้
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:map="http://schemas.android.com/apk/res-auto"
xmlns:tools="http://schemas.android.com/tools"
android:id="@+id/map"
android:name="com.google.android.gms.maps.SupportMapFragment"
android:layout_width="match_parent"
android:layout_height="match_parent"
tools:context=".MapsActivity" />
ติดตั้งใช้งานและเรียกใช้แอป
เมื่อเรียกใช้แอปสําเร็จ แอปจะแสดงแผนที่ที่กําหนดศูนย์กลางไว้ที่ซิดนีย์ ออสเตรเลียพร้อมเครื่องหมายบนเมืองดังที่เห็นในภาพหน้าจอต่อไปนี้
วิธีทำให้แอปใช้งานได้
- ใน Android Studio ให้คลิกตัวเลือกเมนูเรียกใช้ (หรือไอคอนปุ่มเล่น) เพื่อเรียกใช้แอป
- เมื่อได้รับข้อความแจ้งให้เลือกอุปกรณ์ ให้เลือกตัวเลือกใดตัวเลือกหนึ่งต่อไปนี้
- เลือกอุปกรณ์ Android ที่เชื่อมต่อกับคอมพิวเตอร์
- หรือเลือกปุ่มตัวเลือกเปิดโปรแกรมจำลอง แล้วเลือกอุปกรณ์เสมือนที่คุณตั้งค่าไว้
- คลิกตกลง Android Studio จะเริ่ม Gradle เพื่อสร้างแอป จากนั้นจะแสดงผลลัพธ์ในอุปกรณ์หรือโปรแกรมจำลอง ระบบอาจใช้เวลาหลายนาทีก่อนที่แอปจะเปิดขึ้น
ขั้นตอนถัดไป
ตั้งค่าแผนที่: เอกสารนี้อธิบายวิธีตั้งค่าเริ่มต้นและการตั้งค่ารันไทม์สําหรับแผนที่ เช่น ตำแหน่งกล้อง ประเภทแผนที่ คอมโพเนนต์ UI และท่าทางสัมผัส
เพิ่มแผนที่ลงในแอป Android (Kotlin): Codelab นี้จะแนะนำแอปที่สาธิตฟีเจอร์เพิ่มเติมบางอย่างของ Maps SDK สําหรับ Android
ใช้ไลบรารี KTX ของ Maps สำหรับ Android: ไลบรารีส่วนขยาย Kotlin (KTX) นี้ช่วยให้คุณใช้ประโยชน์จากฟีเจอร์ภาษา Kotlin หลายอย่างได้ขณะใช้ Maps SDK สําหรับ Android