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

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

คู่มือเริ่มต้นฉบับย่อนี้เหมาะสำหรับนักพัฒนาแอป Android ที่คุ้นเคยกับการพัฒนาแอป Android เบื้องต้นด้วย Kotlin หรือ Java

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

คู่มือเริ่มต้นฉบับย่อนี้พัฒนาขึ้นโดยใช้ Android Studio Hedgehog และ Android Gradle plugin เวอร์ชัน 8.2

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

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

• หากต้องการใช้อุปกรณ์ Android ให้ทำตามวิธีการที่ หัวข้อเรียกใช้แอปในอุปกรณ์ฮาร์ดแวร์
• หากต้องการใช้โปรแกรมจำลอง Android คุณสามารถสร้างอุปกรณ์เสมือนและติดตั้งโปรแกรมจำลองได้โดยใช้ Android Virtual Device (AVD) Manager ที่มาพร้อมกับ Android Studio

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

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

1. เปิด Android Studio แล้วคลิกโปรเจ็กต์ใหม่ ในหน้าต่าง Welcome to Android Studio

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

3. กรอกแบบฟอร์มโปรเจ็กต์ใหม่ ดังนี้

   • ตั้งค่าภาษา เป็น Java หรือ Kotlin Maps SDK สำหรับ Android รองรับทั้ง 2 ภาษาอย่างเต็มที่ ดูข้อมูลเพิ่มเติมเกี่ยวกับ Kotlin ได้ที่ พัฒนาแอป Android ด้วย Kotlin

   • ตั้งค่า SDK ขั้นต่ำ เป็น SDK เวอร์ชันที่เข้ากันได้กับอุปกรณ์ทดสอบ คุณต้องเลือกเวอร์ชันที่สูงกว่าเวอร์ชันขั้นต่ำที่ Maps SDK สำหรับ Android เวอร์ชัน 20.0.x กำหนด ซึ่งคือ Android API ระดับ 23 ("Marshmallow"; Android 6.0) ขึ้นไป ดูข้อมูลล่าสุดเกี่ยวกับข้อกำหนดเวอร์ชัน SDK ได้ในบันทึกประจำรุ่นสำหรับ

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

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

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

5. เพิ่ม Google Maps Views Activity โดยทำดังนี้

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

   2. เลือกใหม่ > Google > Google Maps Views Activity

      

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

   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 services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

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

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

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

วิธีติดตั้งปลั๊กอินข้อมูลลับ Gradle สำหรับ Android และจัดเก็บคีย์ API

1. ใน Android Studio ให้เปิดไฟล์ build.gradle ระดับราก แล้วเพิ่มโค้ดต่อไปนี้ลงในองค์ประกอบ dependencies ในส่วน buildscript

   Groovy

   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

   Groovy

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

   Kotlin

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

3. หากใช้ Android Studio ให้ ซิงค์โปรเจ็กต์กับ Gradle
4. เปิดไฟล์ local.properties ในไดเรกทอรีระดับโปรเจ็กต์ แล้วเพิ่ม โค้ดต่อไปนี้ แทนที่ YOUR_API_KEY ด้วยคีย์ API ของคุณ

   MAPS_API_KEY=YOUR_API_KEY

5. ในไฟล์ AndroidManifest.xml ให้ไปที่ com.google.android.geo.API_KEY แล้วอัปเดตแอตทริบิวต์ android:value ดังนี้

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />
       

   หมายเหตุ: com.google.android.geo.API_KEY เป็นชื่อข้อมูลเมตาที่แนะนำ สำหรับคีย์ API คีย์ที่มีชื่อนี้สามารถใช้เพื่อตรวจสอบสิทธิ์กับ Google Maps-based API หลายรายการในแพลตฟอร์ม Android รวมถึง Maps SDK สำหรับ Android API ยังรองรับชื่อ com.google.android.maps.v2.API_KEY เพื่อความเข้ากันได้แบบย้อนหลัง ชื่อเดิมนี้ อนุญาตให้ตรวจสอบสิทธิ์กับ Android Maps API v2 เท่านั้น แอปพลิเคชันระบุชื่อข้อมูลเมตาของคีย์ API ได้เพียงชื่อเดียว หากระบุทั้ง 2 ชื่อ API จะแสดงข้อยกเว้น

ดูโค้ด

ตรวจสอบโค้ดที่เทมเพลตให้มา โดยเฉพาะอย่างยิ่ง ให้ดูไฟล์ต่อไปนี้ในโปรเจ็กต์ Android Studio

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

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

องค์ประกอบหลักของกิจกรรมใน Maps

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

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

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

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

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

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

dependencies {

    // Maps SDK for Android
    implementation(libs.play.services.maps)
}

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

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

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

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

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