Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

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

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

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

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

เอกสารนี้อธิบายสภาพแวดล้อมในการพัฒนาซอฟต์แวร์โดยใช้ Android Studio Hedgehog และปลั๊กอิน Android Gradle เวอร์ชัน 8.2

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

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

ในไฟล์ settings.gradle.kts ระดับบนสุด ให้ใส่พอร์ทัลปลั๊กอิน Gradle, ที่เก็บ Maven ของ Google และที่เก็บส่วนกลางของ Maven ไว้ในบล็อก pluginManagement บล็อก pluginManagement ต้องปรากฏก่อนคำสั่งอื่นๆ ในสคริปต์
```
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
} 
```
ในไฟล์ settings.gradle.kts ระดับบนสุด ให้ใส่ที่เก็บ Maven ของ Google และที่เก็บส่วนกลางของ Maven ไว้ในบล็อก dependencyResolutionManagement ดังนี้
```
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        google()
        mavenCentral()
    }
} 
```
ในไฟล์ build.gradle.kts หรือ build.gradle ระดับโมดูล ให้เพิ่มทรัพยากร Dependency ของบริการ Google Play สำหรับ Maps SDK สำหรับ Android
Kotlin
```
dependencies {

    // Maps SDK for Android
    implementation(libs.play.services.maps)
}
```
ดึงดูด
```
dependencies {

    // Maps SDK for Android
    implementation "com.google.android.gms:play-services-maps:20.1.0"
}
```
ในไฟล์ build.gradle.kts หรือ build.gradle ระดับโมดูล ให้ตั้งค่า compileSdk และ minSdk เป็นค่าต่อไปนี้
หมายเหตุ: ตรวจสอบว่าได้ตั้งค่า compileSdk เป็น 34 ขึ้นไป และตั้งค่า minSdk เป็น 23 ขึ้นไป
Kotlin
```
android {
    compileSdk = 34

    defaultConfig {
        minSdk = 23
        // ...
    }
}
```
ดึงดูด
```
android {
    compileSdk 34

    defaultConfig {
        minSdk 23
        // ...
    }
}
```
ในส่วน buildFeatures ของไฟล์ build.gradle.kts หรือ build.gradle ระดับโมดูล ให้เพิ่มคลาส BuildConfig ซึ่งคุณสามารถใช้เพื่อเข้าถึงค่าข้อมูลเมตาที่กำหนดไว้ในภายหลังในขั้นตอนนี้
Kotlin
```
android {
  // ...
  buildFeatures {
    buildConfig = true
    // ...
  }
}
```
ดึงดูด
```
android {
  // ...
  buildFeatures {
    buildConfig true
    // ...
  }
}
```

เพิ่มโค้ดต่อไปนี้ในไฟล์ libs.versions.toml

[versions]
play-services-maps = "20.1.0"

[libraries]
play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }

ขั้นตอนที่ 3: เพิ่มคีย์ API ลงในโปรเจ็กต์

ส่วนนี้จะอธิบายวิธีจัดเก็บคีย์ API เพื่อให้แอปอ้างอิงได้อย่างปลอดภัย คุณไม่ควรตรวจสอบคีย์ API ในระบบควบคุมเวอร์ชัน เราจึงขอแนะนำให้จัดเก็บไว้ในไฟล์ secrets.properties ในไดเรกทอรีรากของโปรเจ็กต์และยกเว้นไฟล์นั้นจากการควบคุมเวอร์ชัน ดูข้อมูลเพิ่มเติมเกี่ยวกับไฟล์พร็อพเพอร์ตี้ Gradle ได้ที่ไฟล์พร็อพเพอร์ตี้ Gradle

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

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

ใน 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
}

ดึงดูด

plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
}

เปิดไฟล์ build.gradle.kts หรือ build.gradle ระดับโมดูล แล้วเพิ่มโค้ดต่อไปนี้ลงในองค์ประกอบ plugins

Kotlin

plugins {
    id("com.android.application")
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}

ดึงดูด

plugins {
    id 'com.android.application'
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}

หากใช้ Android Studio ให้ซิงค์โปรเจ็กต์กับ Gradle
เปิดไฟล์ secrets.properties ในไดเรกทอรีระดับบนสุด แล้วเพิ่มโค้ดต่อไปนี้ แทนที่ YOUR_API_KEY ด้วยคีย์ API ของคุณ อย่าลืมเพิ่ม secrets.properties ลงในไฟล์ .gitignore (หรือยกเว้นจากระบบควบคุมเวอร์ชัน) เพื่อไม่ให้คุณตรวจสอบคีย์ API ในการควบคุมเวอร์ชัน
หมายเหตุ: หากไม่มีไฟล์ secrets.properties ให้สร้างไฟล์ในโฟลเดอร์เดียวกับไฟล์ local.properties
```
MAPS_API_KEY=YOUR_API_KEY
```
สร้างไฟล์ local.defaults.properties ในไดเรกทอรีระดับบนสุด ซึ่งเป็นโฟลเดอร์เดียวกับไฟล์ secrets.properties แล้วเพิ่มโค้ดต่อไปนี้

หมายเหตุ: ป้อนรหัสตามที่แสดง อย่าแทนที่ DEFAULT_API_KEY ด้วยคีย์ API ของคุณ
```
MAPS_API_KEY=DEFAULT_API_KEY
```
วัตถุประสงค์ของไฟล์นี้คือการระบุตำแหน่งสำรองสำหรับคีย์ API หากไม่พบไฟล์ secrets.properties เพื่อไม่ให้บิลด์ล้มเหลว กรณีนี้อาจเกิดขึ้นหากคุณโคลนแอปจากระบบควบคุมเวอร์ชันที่ละเว้น secrets.properties และคุณยังไม่ได้สร้างไฟล์ secrets.properties ในเครื่องเพื่อระบุคีย์ API
ในไฟล์ 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 คีย์ที่มีชื่อนี้สามารถใช้เพื่อตรวจสอบสิทธิ์กับ API ที่ใช้ Google Maps หลายรายการในแพลตฟอร์ม Android รวมถึง Maps SDK สำหรับ Android นอกจากนี้ API ยังรองรับชื่อ com.google.android.maps.v2.API_KEY เพื่อให้เข้ากันได้แบบย้อนหลังด้วย ชื่อเดิมนี้อนุญาตให้ตรวจสอบสิทธิ์กับ Android Maps API v2 เท่านั้น แอปพลิเคชันสามารถระบุชื่อข้อมูลเมตาของคีย์ API ได้เพียงชื่อเดียวเท่านั้น หากระบุทั้ง 2 รายการ API จะแสดงข้อยกเว้น

ใน 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"
}

ดึงดูด

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

ขั้นตอนที่ 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 6.0 ขึ้นไปและมี Google APIs

หากต้องการใช้อุปกรณ์ Android ให้ทำตามวิธีการที่หัวข้อเรียกใช้แอปในอุปกรณ์ฮาร์ดแวร์
หากต้องการใช้โปรแกรมจำลองของ Android คุณสามารถสร้างอุปกรณ์เสมือนจริงและติดตั้งโปรแกรมจำลองโดยใช้โปรแกรมจัดการอุปกรณ์ที่มาพร้อมกับ Android Studio
หมายเหตุ: หากเลือกใช้โปรแกรมจำลองของ Android ให้ตรวจสอบว่าคุณเลือกโปรไฟล์อุปกรณ์ที่มีไอคอน Google Play แสดงอยู่ในคอลัมน์ Play ไอคอนนี้บ่งบอกว่าโปรไฟล์เหล่านี้เป็นไปตาม CTS อย่างสมบูรณ์และสามารถใช้อิมเมจระบบที่มีแอป Play Store ได้

กล่องโต้ตอบเพิ่มอุปกรณ์ในโปรแกรมจัดการอุปกรณ์ของ Android Studio แสดงโปรไฟล์อุปกรณ์เสมือนจริงที่มีไอคอน Google Play ในคอลัมน์ Play

ขั้นตอนที่ 6: ตรวจสอบการรองรับบริการ Google Play (ไม่บังคับ)

Maps SDK สำหรับ Android กำหนดให้อุปกรณ์ที่คุณติดตั้งใช้งานแอปต้องติดตั้งบริการ Google Play ไว้ Google มีเมธอดที่คุณสามารถเรียกใช้จากแอปเพื่อตรวจสอบได้ ดูข้อมูลเพิ่มเติมได้ที่ตรวจสอบว่ามีการติดตั้งบริการ Google Play หรือไม่

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

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