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

สร้างแอป Android ที่แสดงแผนที่โดยใช้เทมเพลตมุมมอง Google Maps สำหรับ 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 แล้วคลิกโปรเจ็กต์ใหม่ ในหน้าต่าง 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 โดยทำดังนี้

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

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

วิธีติดตั้งปลั๊กอิน Secrets 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
}

    Groovy

    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")
}

    Groovy

    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 คีย์ที่มีชื่อนี้สามารถใช้เพื่อตรวจสอบสิทธิ์กับ Google Maps-based APIs หลายรายการในแพลตฟอร์ม 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"
}

    Groovy

    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)
}

Groovy

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