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

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

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

ตั้งค่าสภาพแวดล้อมในการพัฒนาซอฟต์แวร์

  1. คุณต้องใช้ Android Studio Arctic Fox ขึ้นไป หากยังไม่ได้ดำเนินการ ให้ดาวน์โหลดและติดตั้ง
  2. ตรวจสอบว่าคุณใช้ปลั๊กอิน Android Gradle เวอร์ชัน 7.0 ขึ้นไปใน Android Studio อยู่

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

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

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

มีการเปลี่ยนแปลงขั้นตอนการสร้างโปรเจ็กต์ Google Maps ใน Android Studio ใน Flamingo และ Android Studio รุ่นต่อๆ ไป ตรวจสอบว่าคุณทำตามขั้นตอนด้านล่างสำหรับ Android Studio เวอร์ชันที่คุณต้องการ

  1. เปิด Android Studio แล้วคลิกสร้างโปรเจ็กต์ใหม่ในหน้าต่างยินดีต้อนรับสู่ Android Studio

  2. ในหน้าต่างโปรเจ็กต์ใหม่ ในหมวดหมู่โทรศัพท์และแท็บเล็ต ให้เลือกกิจกรรมว่าง แล้วคลิกถัดไป

  3. กรอกแบบฟอร์มกิจกรรมใน Google Maps ให้ครบถ้วน

    • ตั้งค่าภาษาเป็น Java หรือ Kotlin ทั้ง 2 ภาษาได้รับการรองรับ อย่างเต็มรูปแบบจาก Maps SDK สำหรับ Android ดูข้อมูลเพิ่มเติมเกี่ยวกับ Kotlin ได้ที่พัฒนาแอป Android ด้วย Kotlin

    • ตั้งค่า SDK ขั้นต่ำเป็นเวอร์ชัน SDK ที่เข้ากันได้กับอุปกรณ์ทดสอบของคุณ คุณต้องเลือกเวอร์ชันที่สูงกว่าเวอร์ชันขั้นต่ำที่ Maps SDK สำหรับ Android เวอร์ชัน 18.0.x ซึ่งเป็น Android API ระดับ 19 (Android 4.4 KitKat) ขึ้นไป ดูข้อมูลล่าสุดเกี่ยวกับข้อกำหนดเวอร์ชัน SDK ได้ที่บันทึกประจำรุ่น

  4. คลิกเสร็จ

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

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

  6. เพิ่มกิจกรรม Google Maps View:

    1. คลิกขวาบนแพ็กเกจที่คุณต้องการเพิ่มกิจกรรม Google Maps Views
    2. เลือกใหม่ > Google > กิจกรรม Google Maps View

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

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

  7. ไฟล์ AndroidManifest.xml ประกอบด้วยวิธีการรับคีย์ API ของ Google Maps แล้วเพิ่มลงในไฟล์ local.properties อย่าเพิ่มคีย์ API ลงในไฟล์ AndroidManifest.xml การดำเนินการดังกล่าวจะทำให้คีย์ API ปลอดภัยน้อยลง โปรดทำตามวิธีการในส่วนถัดไปเพื่อสร้างโปรเจ็กต์ Cloud และกำหนดค่าคีย์ API แทน

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

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

ขั้นตอนที่ 1

คอนโซล

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

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

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

    Google Cloud มอบข้อเสนอในการทดลองใช้แบบเรียกเก็บเงิน $0.00 ช่วงทดลองใช้จะสิ้นสุดเมื่อครบ 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"

อ่านเพิ่มเติมเกี่ยวกับ 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

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

วิธีติดตั้งปลั๊กอิน Secrets Gradle สำหรับ Android ในโปรเจ็กต์ Google Maps มีดังนี้

  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.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}

    Kotlin

    plugins {
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. บันทึกไฟล์และซิงค์โปรเจ็กต์กับ Gradle
  4. เปิด secrets.properties ในไดเรกทอรีระดับโปรเจ็กต์ แล้วเพิ่มโค้ดต่อไปนี้ แทนที่ YOUR_API_KEY ด้วยคีย์ API 
    MAPS_API_KEY=YOUR_API_KEY
  5. บันทึกไฟล์
  6. ในไฟล์ AndroidManifest.xml ให้ไปที่ com.google.android.geo.API_KEY และอัปเดต android:value attribute ดังนี้ 
    <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

  7. (ไม่บังคับ) แก้ไขคุณสมบัติของปลั๊กอินเพื่อระบุไฟล์ข้อมูลลับอื่นหรือคุณสมบัติอื่นๆ ใน Android Studio ให้เปิดไฟล์ build.gradle ระดับโปรเจ็กต์และแก้ไขพร็อพเพอร์ตี้ secrets โดยทำดังนี้

    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.*"
}

หมายเหตุ: ดังที่แสดงด้านบน 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

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

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

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

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

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

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

ไฟล์กิจกรรมแผนที่มีรหัสต่อไปนี้

Kotlin



import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle

import com.google.android.gms.maps.CameraUpdateFactory
import com.google.android.gms.maps.GoogleMap
import com.google.android.gms.maps.OnMapReadyCallback
import com.google.android.gms.maps.SupportMapFragment
import com.google.android.gms.maps.model.LatLng
import com.google.android.gms.maps.model.MarkerOptions

internal class MapsActivity : AppCompatActivity(), OnMapReadyCallback {

    private lateinit var mMap: GoogleMap

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_maps)
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        val mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync(this)
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    override fun onMapReady(googleMap: GoogleMap) {
        mMap = googleMap

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

Java


import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.OnMapReadyCallback;
import com.google.android.gms.maps.SupportMapFragment;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.MarkerOptions;

public class MapsActivity extends AppCompatActivity implements OnMapReadyCallback {

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_maps);
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     *
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    @Override
    public void onMapReady(GoogleMap googleMap) {
        mMap = googleMap;

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

ไฟล์ Module Gradle

ไฟล์โมดูล build.gradle ประกอบด้วยการอ้างอิงแผนที่ต่อไปนี้ ซึ่ง 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 ตั้งชื่อคลาสของ Fragment เป็น SupportMapFragment ซึ่งเป็นประเภท Fragment ที่ใช้ในไฟล์กิจกรรมแผนที่

ไฟล์รูปแบบ XML มีรหัสต่อไปนี้:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:id="@+id/map"
    tools:context=".MapsActivity"
    android:name="com.google.android.gms.maps.SupportMapFragment" />

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

ภาพหน้าจอแสดงแผนที่และเครื่องหมายซึ่งมีศูนย์กลางอยู่ที่ซิดนีย์ออสเตรเลีย

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

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

  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