การเริ่มต้น 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 4.0 ขึ้นไปและมี Google APIs

• หากต้องการใช้อุปกรณ์ Android ให้ทำตามวิธีการที่ เรียกใช้แอปในอุปกรณ์ฮาร์ดแวร์
• หากต้องการใช้โปรแกรมจำลอง Android คุณสร้างอุปกรณ์เสมือนและติดตั้งโปรแกรมจำลองได้โดยใช้ Android Virtual Device Manager (AVD) ที่มาพร้อมกับ 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 เวอร์ชัน 18.2.x ซึ่งเป็น Android API ระดับ 19 ("KitKat" และ Android 4.4) ขึ้นไป ดูข้อมูลล่าสุดเกี่ยวกับข้อกำหนดเวอร์ชัน SDK ได้ที่บันทึกประจำรุ่น

   • ตั้งค่าภาษาการกําหนดค่าบิลด์เป็น Kotlin DSL หรือ Groovy DSL ตัวอย่างข้อมูลสำหรับภาษาของการกำหนดค่าบิลด์ทั้ง 2 ภาษาจะแสดงในขั้นตอนต่อไปนี้

4. คลิกเสร็จ

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

5. เพิ่มกิจกรรม Google Maps View:

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

   2. เลือกใหม่ > 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

เราขอแนะนำให้ใช้ปลั๊กอิน Secrets 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

ไฟล์กิจกรรม Maps

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

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

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

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

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

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

ไฟล์ Module Gradle

ไฟล์โมดูล build.gradle ประกอบด้วยทรัพยากร Dependency ของแผนที่ต่อไปนี้ ซึ่ง Maps SDK สำหรับ Android จำเป็นต้องใช้

dependencies {

    // Maps SDK for Android
    implementation 'com.google.android.gms:play-services-maps:18.2.0'
}

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

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

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

• tools:context ตั้งค่ากิจกรรมเริ่มต้นของส่วนย่อยเป็น MapsActivity ซึ่งกำหนดไว้ในไฟล์กิจกรรมแผนที่
• android:name ตั้งชื่อคลาสของ Fragment เป็น 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