การเริ่มต้น 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 APIs รวมอยู่ด้วย

  • หากต้องการใช้อุปกรณ์ 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. เลือกใหม่ > Google > กิจกรรม Google Maps View

      เพิ่มกิจกรรมบนแผนที่

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

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

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

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

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

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

ขั้นตอนที่ 1

คอนโซล

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

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

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

    Google Cloud เสนอช่วงทดลองใช้โดยคิดค่าบริการ $0.00 ช่วงทดลองใช้จะสิ้นสุดเมื่อครบ 90 วันหรือหลังจากที่บัญชีมีค่าใช้จ่ายถึง 9, 000 บาท แล้วแต่ว่าอย่างใดจะถึงก่อน ยกเลิกได้ทุกเมื่อ 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"

อ่านเพิ่มเติมเกี่ยวกับ 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 alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

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

เพิ่มคีย์ 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 ของคุณ

ไฟล์กิจกรรมบนแผนที่

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

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

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

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

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

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

ไฟล์ 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 ตั้งชื่อคลาสของส่วนย่อยเป็น 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

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