การเริ่มต้น 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 มีการเปลี่ยนแปลงใน Android Studio เวอร์ชัน Flamingo ขึ้นไป

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

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

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

   • ตั้งค่าภาษาเป็น Java หรือ Kotlin ทั้ง 2 ภาษาได้รับการสนับสนุนอย่างสมบูรณ์โดย Maps SDK สำหรับ Android ดูข้อมูลเพิ่มเติมเกี่ยวกับ 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. เลือก New > Google กิจกรรมใน Google Maps View

      

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

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

      สำหรับข้อมูลเพิ่มเติม โปรดดู เพิ่มโค้ดจากเทมเพลต

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

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

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

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

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

ไฟล์กิจกรรมบนแผนที่

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

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

• ออบเจ็กต์ 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 ซึ่งกำหนดไว้ในไฟล์กิจกรรม 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 ให้คลิกตัวเลือกเมนูเรียกใช้ (หรือไอคอนปุ่มเล่น) เพื่อ เรียกใช้แอปของคุณ
2. เมื่อได้รับข้อความแจ้งให้เลือกอุปกรณ์ ให้เลือกตัวเลือกใดตัวเลือกหนึ่งต่อไปนี้
   • เลือกอุปกรณ์ Android ที่เชื่อมต่อกับคอมพิวเตอร์ของคุณ
   • หรือเลือกปุ่มตัวเลือกเปิดโปรแกรมจำลอง แล้วเลือกอุปกรณ์เสมือนที่คุณตั้งค่าไว้
3. คลิกตกลง Android Studio จะเริ่ม Gradle เพื่อสร้างแอป จากนั้นจะแสดงผลลัพธ์ในอุปกรณ์หรือโปรแกรมจำลอง แอปอาจใช้เวลาหลายนาที เปิดตัว

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

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

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

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