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

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

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

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

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

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

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

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

สร้างโปรเจ็กต์ 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 เวอร์ชัน 20.0.x กำหนด ซึ่งคือ Android API ระดับ 23 ("Marshmallow"; Android 6.0) ขึ้นไป ดูข้อมูลล่าสุดเกี่ยวกับข้อกำหนดของ SDK เวอร์ชันได้ที่บันทึกประจำรุ่น

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

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

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

  5. เพิ่มกิจกรรมการดูใน Google Maps โดยทำดังนี้

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

    2. เลือกใหม่ > Google > กิจกรรมในมุมมองของ Google Maps

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

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

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

      ดูข้อมูลเพิ่มเติมได้ที่ เพิ่มโค้ดจากเทมเพลต

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

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

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

ขั้นตอนที่ 1

คอนโซล

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

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

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

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

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"

อ่านเพิ่มเติมเกี่ยวกับ Google Cloud SDK , การติดตั้ง 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 services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

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

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

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

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

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

  1. ใน Android Studio ให้เปิดไฟล์ build.gradle ระดับรูท แล้วเพิ่มโค้ดต่อไปนี้ลงในองค์ประกอบ 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.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 คีย์ที่มีชื่อนี้ใช้เพื่อตรวจสอบสิทธิ์ใน API หลายรายการที่อิงตาม Google Maps บนแพลตฟอร์ม 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 ที่ใช้ในไฟล์กิจกรรมแผนที่

ไฟล์เลย์เอาต์ 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 ได้