การเริ่มต้น Maps SDK สำหรับ Android อย่างรวดเร็ว

สร้างแอป 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 มีการเปลี่ยนแปลงใน Flamingo และรุ่นที่ใหม่กว่าของ Android Studio

1. เปิด Android Studio แล้วคลิกโปรเจ็กต์ใหม่ในหน้าต่างยินดีต้อนรับสู่ Android Studio

2. ในหน้าต่างโปรเจ็กต์ใหม่ ภายในหมวดหมู่โทรศัพท์และแท็บเล็ต ให้เลือกไม่มีกิจกรรม แล้วคลิกถัดไป

3. กรอกแบบฟอร์มโปรเจ็กต์ใหม่

   • ตั้งค่าภาษาเป็น 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 ภาษาจะแสดงในขั้นตอนต่อไปนี้

4. คลิกเสร็จสิ้น

   Android Studio จะเริ่มต้น Gradle และสร้างโปรเจ็กต์ อาจใช้เวลาสักครู่

5. เพิ่มกิจกรรมการดูใน Google Maps

   1. คลิกขวาที่โฟลเดอร์ app ในโปรเจ็กต์

   2. เลือกใหม่ > Google > กิจกรรมการดู Google Maps

      

   3. ในกล่องโต้ตอบกิจกรรม Android ใหม่ ให้เลือกช่องทําเครื่องหมายกิจกรรม Launcher

   4. เลือกเสร็จสิ้น

      ดูข้อมูลเพิ่มเติมได้ที่หัวข้อเพิ่มโค้ดจากเทมเพลต

6. เมื่อบิลด์เสร็จแล้ว Android Studio จะเปิดไฟล์ AndroidManifest.xml และ MapsActivity กิจกรรมของคุณอาจมีชื่ออื่น แต่กิจกรรมดังกล่าวคือกิจกรรมที่คุณกําหนดค่าไว้ระหว่างการตั้งค่า

ตั้งค่าโปรเจ็กต์ Google Cloud

ทําตามขั้นตอนการตั้งค่าคอนโซลระบบคลาวด์ที่จําเป็นโดยคลิกผ่านแท็บต่อไปนี้

gcloud projects create "PROJECT"

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

gcloud alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

เพิ่มคีย์ API ลงในแอป

ส่วนนี้อธิบายวิธีจัดเก็บคีย์ API เพื่อให้แอปอ้างอิงได้อย่างปลอดภัย คุณไม่ควรตรวจสอบคีย์ API ในระบบควบคุมเวอร์ชัน เราจึงขอแนะนำให้จัดเก็บไว้ในไฟล์ secrets.properties ซึ่งอยู่ในไดเรกทอรีรูทของโปรเจ็กต์ ดูข้อมูลเพิ่มเติมเกี่ยวกับไฟล์ secrets.properties ได้ที่ไฟล์พร็อพเพอร์ตี้ Gradle

เราขอแนะนำให้ใช้ปลั๊กอินข้อมูลลับ Gradle สําหรับ Android เพื่อลดความซับซ้อนของงานนี้

วิธีติดตั้งปลั๊กอินข้อมูลลับ Gradle สําหรับ Android ในโปรเจ็กต์ Google Maps

1. ใน 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"
       }
   }

2. เปิดไฟล์ 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'
   }

3. ในไฟล์ build.gradle.kts หรือ build.gradle ระดับโมดูล ให้ตรวจสอบว่าได้ตั้งค่า targetSdk และ compileSdk เป็น 34
4. บันทึกไฟล์แล้วซิงค์โปรเจ็กต์กับ Gradle
5. เปิดไฟล์ secrets.properties ในไดเรกทอรีระดับบนสุด แล้วเพิ่มโค้ดต่อไปนี้ แทนที่ YOUR_API_KEY ด้วยคีย์ API ของคุณ เก็บคีย์ไว้ในไฟล์นี้เนื่องจาก secrets.properties ได้รับการยกเว้นไม่ให้ตรวจสอบในระบบควบคุมเวอร์ชัน

   MAPS_API_KEY=YOUR_API_KEY

6. บันทึกไฟล์

7. สร้างไฟล์ local.defaults.properties ในไดเรกทอรีระดับบนสุด ซึ่งเป็นโฟลเดอร์เดียวกับไฟล์ secrets.properties แล้วเพิ่มโค้ดต่อไปนี้

   MAPS_API_KEY=DEFAULT_API_KEY

   วัตถุประสงค์ของไฟล์นี้คือระบุตำแหน่งสำรองสำหรับคีย์ API ในกรณีที่ไม่พบไฟล์ secrets.properties เพื่อให้การสร้างไม่ล้มเหลว กรณีนี้อาจเกิดขึ้นได้หากคุณโคลนแอปจากระบบควบคุมเวอร์ชันที่ไม่ได้ใส่ secrets.properties และคุณยังไม่ได้สร้างไฟล์ secrets.properties ในเครื่องเพื่อระบุคีย์ API

8. บันทึกไฟล์
9. ในไฟล์ 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 รวมถึง Maps SDK สำหรับ Android API ยังรองรับชื่อ com.google.android.maps.v2.API_KEY เพื่อความเข้ากันได้แบบย้อนหลังด้วย ชื่อเดิมนี้อนุญาตให้ตรวจสอบสิทธิ์กับ Android Maps API v2 เท่านั้น แอปพลิเคชันจะระบุชื่อข้อมูลเมตาของคีย์ API ได้เพียงชื่อเดียวเท่านั้น หากระบุทั้ง 2 รายการ API จะแสดงข้อยกเว้น

10. ใน 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

ไฟล์กิจกรรม Maps คือกิจกรรมหลักของแอป และจะมีโค้ดสำหรับจัดการและแสดงแผนที่ โดยค่าเริ่มต้น ไฟล์ที่กําหนดกิจกรรมจะมีชื่อว่า MapsActivity.java หรือ MapsActivity.kt หากคุณตั้งค่า Kotlin เป็นภาษาสําหรับแอป

องค์ประกอบหลักของกิจกรรมบนแผนที่

• ออบเจ็กต์ SupportMapFragment จะจัดการวงจรชีวิตของแผนที่ และเป็นองค์ประกอบหลักของ UI ของแอป

• ออบเจ็กต์ GoogleMap ให้สิทธิ์เข้าถึงข้อมูลแผนที่และมุมมอง นี่คือคลาสหลักของ Maps SDK สําหรับ Android คำแนะนำออบเจ็กต์แผนที่อธิบายออบเจ็กต์ SupportMapFragment และ GoogleMap อย่างละเอียด

• ฟังก์ชัน moveCamera จะวางแผนที่ให้อยู่กึ่งกลางที่พิกัด LatLng ของซิดนีย์ ออสเตรเลีย การตั้งค่าแรกที่ต้องกำหนดเมื่อเพิ่มแผนที่มักจะเป็นตำแหน่งแผนที่และการตั้งค่ากล้อง เช่น มุมมอง การวางแนวแผนที่ และระดับการซูม ดูรายละเอียดได้ในคู่มือกล้องและมุมมอง

• ฟังก์ชัน addMarker จะเพิ่มเครื่องหมายลงในพิกัดของซิดนีย์ ดูรายละเอียดได้ในคู่มือเครื่องหมาย

ไฟล์ Gradle ของโมดูล

ไฟล์โมดูล build.gradle.kts มีการพึ่งพาแผนที่ต่อไปนี้ ซึ่ง 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 ซึ่งกำหนดไว้ในไฟล์กิจกรรม Maps
• android:name ตั้งค่าชื่อคลาสของข้อมูลโค้ดเป็น SupportMapFragment ซึ่งเป็นประเภทข้อมูลโค้ดที่ใช้ในไฟล์กิจกรรมแผนที่

ไฟล์เลย์เอาต์ 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" />

ติดตั้งใช้งานและเรียกใช้แอป

เมื่อเรียกใช้แอปสําเร็จ แอปจะแสดงแผนที่ที่กําหนดศูนย์กลางเป็นซิดนีย์ ออสเตรเลียพร้อมเครื่องหมายบนเมืองดังที่เห็นในภาพหน้าจอต่อไปนี้

วิธีทำให้แอปใช้งานได้

1. ใน Android Studio ให้คลิกตัวเลือกเมนู Run (หรือไอคอนปุ่มเล่น) เพื่อเรียกใช้แอป
2. เมื่อได้รับข้อความแจ้งให้เลือกอุปกรณ์ ให้เลือกตัวเลือกใดตัวเลือกหนึ่งต่อไปนี้
   • เลือกอุปกรณ์ Android ที่เชื่อมต่อกับคอมพิวเตอร์
   • หรือเลือกปุ่มตัวเลือกเปิดโปรแกรมจำลอง แล้วเลือกอุปกรณ์เสมือนที่คุณตั้งค่าไว้
3. คลิกตกลง Android Studio จะเริ่ม Gradle เพื่อสร้างแอป จากนั้นจะแสดงผลลัพธ์ในอุปกรณ์หรือโปรแกรมจำลอง ระบบอาจใช้เวลาหลายนาทีก่อนที่แอปจะเปิดขึ้น

ขั้นตอนถัดไป

• ตั้งค่าแผนที่: เอกสารนี้อธิบายวิธีตั้งค่าเริ่มต้นและการตั้งค่ารันไทม์สําหรับแผนที่ เช่น ตำแหน่งกล้อง ประเภทแผนที่ คอมโพเนนต์ UI และท่าทางสัมผัส

• เพิ่มแผนที่ลงในแอป Android (Kotlin): โค้ดแล็บนี้จะแนะนำแอปที่สาธิตฟีเจอร์เพิ่มเติมบางอย่างของ Maps SDK สําหรับ Android

• ใช้ไลบรารี KTX ของ Maps สำหรับ Android: ไลบรารีส่วนขยาย Kotlin (KTX) นี้ช่วยให้คุณใช้ประโยชน์จากฟีเจอร์ภาษา Kotlin หลายอย่างได้ขณะใช้ Maps SDK สําหรับ Android