ตั้งค่าโปรเจ็กต์ Android Studio

หน้านี้จะอธิบายวิธีกำหนดค่าโปรเจ็กต์ Android Studio ให้ใช้ Maps SDK สำหรับ Android โดยไม่ต้องใช้เทมเพลต Google Maps ซึ่งมีรายละเอียดอยู่ในคู่มือเริ่มต้นฉบับย่อ

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

ขั้นตอนที่ 1: ตั้งค่า Android Studio

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

ขั้นตอนที่ 2 ตั้งค่า SDK

ไลบรารี Maps SDK สำหรับ Android พร้อมให้ใช้งานผ่าน ที่เก็บ Maven ของ Google หากต้องการเพิ่ม SDK ลงในแอป ให้ทำดังนี้

  1. ในไฟล์ settings.gradle ระดับบนสุด ให้ใส่พอร์ทัลปลั๊กอิน Gradle, ที่เก็บ Google Maven และที่เก็บส่วนกลาง Maven ไว้ในบล็อก pluginManagement บล็อก pluginManagement ต้องปรากฏก่อนคำสั่งอื่นๆ ในสคริปต์ 
    pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
  2. ในไฟล์ settings.gradle ระดับบนสุด ให้ใส่ที่เก็บ Maven ของ Google และที่เก็บส่วนกลาง Maven ไว้ในบล็อก dependencyResolutionManagement 
    dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
  3. ในไฟล์ build.gradle ระดับโมดูล ให้เพิ่มทรัพยากร Dependency บริการ Google Play ของ Maps SDK สำหรับ Android 
    dependencies {
    implementation 'com.google.android.gms:play-services-maps:18.1.0'
    // ...
}
  4. ในไฟล์ build.gradle ระดับโมดูล ให้ตั้งค่า compileSdk และ minSdk เป็นค่าต่อไปนี้ 
    android {
    compileSdk 31

    defaultConfig {
        minSdk 19
        // ...
    }

ขั้นตอนที่ 3: เพิ่มคีย์ 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 จะแสดงข้อยกเว้น

ขั้นตอนที่ 4: อัปเดตไฟล์ Manifest ของแอป

ส่วนนี้จะอธิบายการตั้งค่าที่จะเพิ่มในไฟล์ AndroidManifest.xml

หมายเลขเวอร์ชันของบริการ Google Play

เพิ่มการประกาศต่อไปนี้ในองค์ประกอบ application ซึ่งจะฝังเวอร์ชันของบริการ Google Play ที่แอปคอมไพล์ขึ้น

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />

สิทธิ์เข้าถึงตำแหน่ง

หากแอปจำเป็นต้องเข้าถึงตำแหน่งของผู้ใช้ คุณต้องขอสิทธิ์เข้าถึงตำแหน่งในไฟล์ AndroidManifest.xml ตัวเลือกต่างๆ ได้แก่ ACCESS_FINE_LOCATION ซึ่งระบุตำแหน่งที่แน่นอนของอุปกรณ์ และ ACCESS_COARSE_LOCATION ซึ่งมีความแม่นยำน้อยกว่า โปรดดูรายละเอียดในคำแนะนำเกี่ยวกับข้อมูลตำแหน่ง

หากต้องการขอสิทธิ์ ACCESS_FINE_LOCATION ให้เพิ่มโค้ดนี้ลงในองค์ประกอบ manifest:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

สิทธิ์เข้าถึงพื้นที่เก็บข้อมูลภายนอก

หากคุณกำหนดเป้าหมายของ SDK บริการ Google Play เวอร์ชัน 8.3 ขึ้นไป คุณไม่จำเป็นต้องมีสิทธิ์ WRITE_EXTERNAL_STORAGE หากคุณกำหนดเป้าหมาย SDK บริการ Google Play เวอร์ชันก่อนหน้า คุณต้องขอสิทธิ์ WRITE_EXTERNAL_STORAGE ในองค์ประกอบ manifest

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

ไลบรารีเดิมของ Apache HTTP

หากคุณใช้ com.google.android.gms:play-services-maps:16.0.0 หรือต่ำกว่าและแอปของคุณกําหนดเป้าหมายเป็น API ระดับ 28 (Android 9.0) ขึ้นไป คุณต้องรวมการประกาศต่อไปนี้ไว้ในองค์ประกอบ <application> ของ AndroidManifest.xml มิฉะนั้น ให้ข้ามการประกาศนี้

<uses-library
    android:name="org.apache.http.legacy"
    android:required="false" />

ขั้นตอนที่ 5: ตั้งค่าอุปกรณ์ Android

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

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

ขั้นตอนถัดไป

เมื่อกําหนดค่าโปรเจ็กต์แล้ว คุณจะเพิ่มแผนที่ได้