การเริ่มต้น 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 Maps SDK สำหรับ Android รองรับทั้ง 2 ภาษาอย่างเต็มรูปแบบ ดูข้อมูลเพิ่มเติมเกี่ยวกับ 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

      เพิ่มกิจกรรมใน Maps

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

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

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

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

ตั้งค่าโปรเจ็กต์ 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 และคําสั่งต่อไปนี้

ขั้นตอนที่ 2

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

คอนโซล

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

Cloud SDK

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

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

ขั้นตอนที่ 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"

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

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

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

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

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

  • ออบเจ็กต์ 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" />

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

ภาพหน้าจอแสดงแผนที่และเครื่องหมายอยู่ตรงกลางของย่าน Syndney Australia

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

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

  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