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

สร้างแอป Android ที่แสดงแผนที่โดยใช้เทมเพลตมุมมอง Google Maps สำหรับ Android Studio หากมีโปรเจ็กต์ Android Studio อยู่แล้วที่ต้องการตั้งค่า โปรดดูตั้งค่าโปรเจ็กต์ Android Studio

การเริ่มต้นใช้งานอย่างรวดเร็วนี้มีไว้สำหรับนักพัฒนาซอฟต์แวร์ที่คุ้นเคยกับการพัฒนา Android ขั้นพื้นฐานด้วย Kotlin หรือ Java

เกี่ยวกับสภาพแวดล้อมในการพัฒนาซอฟต์แวร์

บทแนะนำเริ่มต้นฉบับนี้พัฒนาโดยใช้ Android Studio Hedgehog และปลั๊กอิน Android Gradle เวอร์ชัน 8.2

หมายเหตุ: หากสภาพแวดล้อมการพัฒนาใช้ Android Studio หรือ Gradle เวอร์ชันอื่น คุณอาจต้องแก้ไขขั้นตอนตามสภาพแวดล้อม ดูข้อมูลเพิ่มเติมเกี่ยวกับเวอร์ชัน Android Studio และ Gradle ได้ที่ความเข้ากันได้ของปลั๊กอิน Android Gradle กับ Android Studio

ตั้งค่าอุปกรณ์ Android

หากต้องการเรียกใช้แอปที่ใช้ Maps SDK สําหรับ Android คุณต้องติดตั้งใช้งานแอปในอุปกรณ์ Android หรือโปรแกรมจําลอง Android ที่ใช้ Android 5.0 ขึ้นไปและมี Google API

• หากต้องการใช้อุปกรณ์ Android ให้ทำตามวิธีการที่หัวข้อเรียกใช้แอปในอุปกรณ์ฮาร์ดแวร์
• หากต้องการใช้โปรแกรมจำลอง Android คุณสามารถสร้างอุปกรณ์เสมือนและติดตั้งโปรแกรมจำลองได้โดยใช้เครื่องมือจัดการอุปกรณ์เสมือน Android (AVD) ที่มาพร้อมกับ Android Studio
  หมายเหตุ: หากเลือกใช้โปรแกรมจำลอง Android โปรดตรวจสอบว่าคุณเลือกอุปกรณ์ที่มีไอคอน Play ซึ่งแสดงในคอลัมน์ Play Store ไอคอนนี้บ่งบอกว่าโปรไฟล์เหล่านี้เป็นไปตามข้อกำหนด CTS อย่างสมบูรณ์และอาจใช้ภาพระบบที่มีแอป Play Store

  

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

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

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 ได้ที่บันทึกประจำรุ่น

     หมายเหตุ: หากไม่แน่ใจว่าควรเลือก SDK เวอร์ชันใด ให้เลือกลิงก์ช่วยฉันเลือกเพื่อแสดงข้อมูลการเผยแพร่สำหรับ SDK ของ Android ที่รองรับ ตัวอย่างเช่น หากคุณเลือกAndroid API ระดับ 21 ("Lollipop"; Android 5.0) แอปของคุณควรทำงานในอุปกรณ์ Android ได้มากกว่า 99%

   • ตั้งค่าภาษาการกําหนดค่าบิลด์เป็น 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 กิจกรรมของคุณอาจมีชื่ออื่น แต่กิจกรรมดังกล่าวคือกิจกรรมที่คุณกําหนดค่าไว้ในระหว่างการตั้งค่า

   ข้อควรระวัง: ไฟล์ AndroidManifest.xml มีวิธีการรับคีย์ API ของ Google Maps แล้วเพิ่มลงในไฟล์ local.properties อย่าใส่คีย์ API ลงในไฟล์ local.properties เนื่องจากการเก็บคีย์ API ไว้ในระบบคลาวด์จะทำให้คีย์มีความปลอดภัยน้อยลง แต่ให้ทําตามวิธีการในหัวข้อตั้งค่าโปรเจ็กต์ Google Cloud เพื่อสร้างโปรเจ็กต์ Cloud และกำหนดค่าคีย์ API

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

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

ขั้นตอนที่ 1

คอนโซล

1. ในคอนโซล Google Cloud ให้คลิกสร้างโปรเจ็กต์ในหน้าตัวเลือกโปรเจ็กต์เพื่อเริ่มสร้างโปรเจ็กต์ Cloud ใหม่

   ไปที่หน้าเครื่องมือเลือกโปรเจ็กต์

2. ตรวจสอบว่าเปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์ Cloud แล้ว ยืนยันว่าเปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์แล้ว

   Google Cloud เสนอช่วงทดลองใช้แบบไม่มีค่าใช้จ่าย ช่วงทดลองใช้จะสิ้นสุดลงเมื่อครบ 90 วันหรือหลังจากที่บัญชีมีค่าใช้จ่ายสะสมครบ $300 แล้วแต่ว่ากรณีใดจะเกิดขึ้นก่อน ยกเลิกได้ทุกเมื่อ Google Maps Platform มีเครดิตรายเดือนมูลค่า $200 แบบตามรอบ ดูข้อมูลเพิ่มเติมได้ที่เครดิตในบัญชีสำหรับการเรียกเก็บเงินและการเรียกเก็บเงิน

Cloud SDK

gcloud projects create "PROJECT"

อ่านข้อมูลเพิ่มเติมเกี่ยวกับ Google Cloud SDK , การติดตั้ง Cloud SDK และคําสั่งต่อไปนี้

• gcloud projects create

หมายเหตุ: หากไม่ต้องการเก็บทรัพยากรที่สร้างขึ้นในแบบฝึกหัด ให้สร้างโปรเจ็กต์แทนการเลือกโปรเจ็กต์ที่มีอยู่ หลังจากทำแบบฝึกหัดเสร็จแล้ว คุณจะลบโปรเจ็กต์ซึ่งเป็นการนำทรัพยากรทั้งหมดที่เชื่อมโยงกับโปรเจ็กต์นี้ออกได้

ขั้นตอนที่ 2

หากต้องการใช้ Google Maps Platform คุณต้องเปิดใช้ API หรือ SDK ที่คุณวางแผนจะใช้กับโปรเจ็กต์

คอนโซล

เปิดใช้ Maps SDK สำหรับ Android

Cloud SDK

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

อ่านข้อมูลเพิ่มเติมเกี่ยวกับ Google Cloud SDK , การติดตั้ง Cloud SDK และคําสั่งต่อไปนี้

• gcloud services enable
• gcloud services disable

ขั้นตอนที่ 3

ขั้นตอนนี้จะทําตามกระบวนการสร้างคีย์ API เท่านั้น หากคุณใช้คีย์ API ในเวอร์ชันที่ใช้งานจริง เราขอแนะนําอย่างยิ่งให้คุณจํากัดคีย์ API ดูข้อมูลเพิ่มเติมได้ในหน้าการใช้คีย์ API สำหรับผลิตภัณฑ์นั้นๆ

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

วิธีสร้างคีย์ API

คอนโซล

1. ไปที่หน้า Google Maps Platform > ข้อมูลเข้าสู่ระบบ

   ไปที่หน้าข้อมูลเข้าสู่ระบบ

2. ในหน้าข้อมูลเข้าสู่ระบบ ให้คลิกสร้างข้อมูลเข้าสู่ระบบ > คีย์ API
   กล่องโต้ตอบสร้างคีย์ API แล้วจะแสดงคีย์ API ที่สร้างขึ้นใหม่
3. คลิกปิด
   คีย์ API ใหม่จะแสดงอยู่ในหน้าข้อมูลเข้าสู่ระบบในส่วนคีย์ API
   (อย่าลืมจํากัดคีย์ API ก่อนนำไปใช้ในเวอร์ชันที่ใช้งานจริง)

Cloud SDK

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

อ่านข้อมูลเพิ่มเติมเกี่ยวกับ Google Cloud SDK , การติดตั้ง Cloud SDK และคําสั่งต่อไปนี้

• gcloud alpha services api-keys create

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

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

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

หมายเหตุ: ดูเอกสารประกอบปลั๊กอินข้อมูลลับ Gradle สำหรับ Android ใน GitHub เพื่อดูข้อกำหนดของระบบและวิธีการติดตั้งล่าสุด

วิธีติดตั้งปลั๊กอินข้อมูลลับ 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 ได้รับการยกเว้นไม่ให้ตรวจสอบในระบบควบคุมเวอร์ชัน
   หมายเหตุ: หากไม่มีไฟล์ secrets.properties ให้สร้างไฟล์ดังกล่าวในโฟลเดอร์เดียวกับไฟล์ local.properties

   MAPS_API_KEY=YOUR_API_KEY

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

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

   หมายเหตุ: ป้อนรหัสตามที่แสดง อย่าแทนที่ DEFAULT_API_KEY ด้วยคีย์ API ของคุณ

   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.kts or build.gradle 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.

    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")
}

หมายเหตุ: เวอร์ชันที่แน่นอนอาจเปลี่ยนแปลงตามเวอร์ชันปัจจุบันของ Maps SDK สําหรับ Android

ดูข้อมูลเพิ่มเติมเกี่ยวกับการจัดการทรัพยากร Dependency ของ Maps ได้ที่การกำหนดเวอร์ชัน

ไฟล์เลย์เอาต์ XML

ไฟล์ activity_maps.xml คือไฟล์เลย์เอาต์ XML ที่กําหนดโครงสร้าง UI ของแอป ไฟล์จะอยู่ในไดเรกทอรี res/layout ไฟล์ activity_maps.xml จะประกาศข้อมูลโค้ดที่ประกอบด้วยองค์ประกอบต่อไปนี้

• tools:context ตั้งค่ากิจกรรมเริ่มต้นของข้อมูลโค้ดเป็น MapsActivity ซึ่งกำหนดไว้ในไฟล์กิจกรรม Maps
• android: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" />

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

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

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

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

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

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

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

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