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

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

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

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

เราขอแนะนำให้ใช้ Android Studio และปลั๊กอิน Android Gradle เวอร์ชันเสถียรล่าสุด

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

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

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

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

  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

      เมนูตามบริบทของ Android Studio สำหรับโฟลเดอร์แอปที่แสดงตัวเลือก New, Google และ Google Maps Views Activity
      การเพิ่มกิจกรรมมุมมอง Google Maps จากเมนูตามบริบท app ใน Android Studio

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

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

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

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

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

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

ขั้นตอนที่ 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 ในไดเรกทอรีรากของโปรเจ็กต์และยกเว้นไฟล์นั้นจากการควบคุมเวอร์ชัน ดูข้อมูลเพิ่มเติมเกี่ยวกับไฟล์พร็อพเพอร์ตี้ Gradle ได้ที่ไฟล์พร็อพเพอร์ตี้ Gradle

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

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

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

    Kotlin

    plugins {
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
}

    ดึงดูด

    plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
}
  2. เปิดไฟล์ build.gradle.kts หรือ build.gradle ระดับโมดูล แล้วเพิ่มโค้ดต่อไปนี้ลงในองค์ประกอบ plugins

    Kotlin

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

    ดึงดูด

    plugins {
    id 'com.android.application'
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}
  3. หากใช้ Android Studio ให้ซิงค์โปรเจ็กต์กับ Gradle
  4. เปิดไฟล์ secrets.properties ในไดเรกทอรีระดับบนสุด แล้วเพิ่มโค้ดต่อไปนี้ แทนที่ YOUR_API_KEY ด้วยคีย์ API ของคุณ อย่าลืมเพิ่ม secrets.properties ลงในไฟล์ .gitignore (หรือยกเว้นจากระบบควบคุมเวอร์ชัน) เพื่อไม่ให้คุณตรวจสอบคีย์ API ในการควบคุมเวอร์ชัน 
    MAPS_API_KEY=YOUR_API_KEY

  5. สร้างไฟล์ local.defaults.properties ในไดเรกทอรีระดับบนสุด ซึ่งเป็นโฟลเดอร์เดียวกับไฟล์ secrets.properties แล้วเพิ่มโค้ดต่อไปนี้

    MAPS_API_KEY=DEFAULT_API_KEY

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

  6. ในไฟล์ 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 จะแสดงข้อยกเว้น

  7. ใน 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 root directory (the same folder as the root 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"
}

    ดึงดูด

    secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root 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"
}

ดูโค้ด

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

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

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

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

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

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

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

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

Kotlin

// Add a marker in Sydney and move the camera
val sydney = LatLng(-34.0, 151.0)
map.addMarker(
    MarkerOptions()
        .position(sydney)
        .title("Marker in Sydney"),
)
map.moveCamera(CameraUpdateFactory.newLatLng(sydney))

Java

// Add a marker in Sydney and move the camera
LatLng sydney = new LatLng(-34, 151);
map.addMarker(new MarkerOptions().position(sydney).title("Marker in Sydney"));
map.moveCamera(CameraUpdateFactory.newLatLng(sydney));

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

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

Kotlin

dependencies {

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

ดึงดูด

dependencies {

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

หากโปรเจ็กต์ใช้แคตตาล็อกเวอร์ชัน Gradle (gradle/libs.versions.toml) ให้กำหนดทรัพยากร Dependency play-services-maps ใน libs.versions.toml ดังนี้

[versions]
play-services-maps = "20.0.0"

[libraries]
play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "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