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

สร้างแอป Android ที่แสดงแผนที่โดยใช้ Google Maps View เทมเพลตสำหรับ 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 คุณสามารถสร้างอุปกรณ์เสมือนและติดตั้งโปรแกรมจำลองโดยใช้ โปรแกรมจัดการอุปกรณ์เสมือน (AVD) สำหรับ Android ที่มาพร้อมกับ Android Studio

สร้างโปรเจ็กต์ Google Maps ใน Android Studio

มีการเปลี่ยนแปลงขั้นตอนการสร้างโปรเจ็กต์ Google Maps ใน Android Studio ใน Flamingo และ Android Studio รุ่นต่อๆ ไป

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 View ดังนี้

   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 หรือ build.gradle.kts ระดับบนสุด และเพิ่มโค้ดต่อไปนี้ลงในเอลิเมนต์ dependencies ใต้ buildscript

   ดึงดูด

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

   Kotlin

   buildscript {
       dependencies {
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }
   

2. เปิดไฟล์ build.gradle ระดับโมดูล และเพิ่มโค้ดต่อไปนี้ลงใน องค์ประกอบ plugins

   ดึงดูด

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

   Kotlin

   plugins {
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

3. ในไฟล์ 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}" />

   Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

10. In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

    Groovy

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        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.*"
    }
            

    Kotlin

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        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 หรือหากคุณตั้งค่า Kotlin เป็น ภาษาของแอปMapsActivity.kt

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

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

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

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

• ฟังก์ชัน addMarker จะเพิ่มเครื่องหมายลงในพิกัดสำหรับ ซิดนีย์ โปรดดูรายละเอียดในคู่มือเครื่องหมาย

ไฟล์ Gradle โมดูล

ไฟล์โมดูล build.gradle มีทรัพยากร 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 ซึ่งกำหนดไว้ในไฟล์กิจกรรมแผนที่
• 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