คู่มือเริ่มใช้งาน 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 ให้ทําตามวิธีการที่ เรียกใช้แอปในอุปกรณ์ฮาร์ดแวร์
• หากต้องการใช้โปรแกรมจําลอง Android คุณจะสร้างอุปกรณ์เสมือนจริงและติดตั้งโปรแกรมจําลองได้โดยใช้ โปรแกรมจัดการอุปกรณ์เสมือน Android (AVD) ที่มาพร้อมกับ Android Studio

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

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

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

3. กรอกแบบฟอร์มกิจกรรมใน Google Maps ตามขั้นตอนต่อไปนี้

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

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

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

gcloud projects create "PROJECT"

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

gcloud alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

เพิ่มคีย์ 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 ได้เพียงชื่อเดียวเท่านั้น หากระบุทั้งคู่ API จะส่งข้อยกเว้น

ดูที่โค้ด

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

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

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

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

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

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

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

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

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

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

      

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 สําหรับแอนดรอยด์ต้องใช้

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

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