คู่มือเริ่มใช้งาน 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 API

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

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

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

  3. กรอกแบบฟอร์มกิจกรรม Google Maps ให้สมบูรณ์

    • ตั้งค่าภาษาเป็น Java หรือ Kotlin Maps SDK สําหรับ Android รองรับทั้ง 2 ภาษา ดูข้อมูลเพิ่มเติมเกี่ยวกับ 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. ไฟล์ AndroidManifest.xml มีวิธีการรับคีย์ API ของ Google Maps จากนั้นเพิ่มคีย์ดังกล่าวลงในไฟล์ local.properities อย่าเพิ่มคีย์ API ลงในไฟล์ AndroidManifest.xml วิธีนี้จะจัดเก็บคีย์ API ของคุณไว้อย่างปลอดภัยน้อยลง ทําตามวิธีการในส่วนถัดไปเพื่อสร้างโปรเจ็กต์ที่อยู่ในระบบคลาวด์และกําหนดค่าคีย์ API แทน

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

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

ขั้นตอนที่ 1

คอนโซล

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

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

  2. ตรวจสอบว่าเปิดใช้การเรียกเก็บเงินสําหรับโปรเจ็กต์ Cloud แล้ว ตรวจสอบว่าเปิดใช้การเรียกเก็บเงินสําหรับโปรเจ็กต์แล้ว

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

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

  1. ใน Android Studio ให้เปิดไฟล์ build.gradle ระดับโปรเจ็กต์ แล้วเพิ่มโค้ดต่อไปนี้ลงในองค์ประกอบ dependencies ในส่วน buildscript 
    plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
}
  2. จากนั้นเปิดไฟล์ build.gradle ระดับโมดูล แล้วเพิ่มโค้ดต่อไปนี้ลงในองค์ประกอบ plugins 
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
  3. บันทึกไฟล์และซิงค์โปรเจ็กต์กับ Gradle
  4. เปิด local.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}" />

หมายเหตุ: ดังที่แสดงด้านบน 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 ดูรายละเอียดเพิ่มเติมในออบเจ็กต์ Map Objects ของออบเจ็กต์ SupportMapFragment และ GoogleMap

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

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

ไฟล์กิจกรรมแผนที่มีโค้ดต่อไปนี้

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

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

ไฟล์ Gradle โมดูล

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

dependencies {
    implementation 'com.google.android.gms:play-services-maps:18.1.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: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

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