ตั้งค่าโปรเจ็กต์ 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 ลงในแอป ให้ทำดังนี้

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

    Kotlin

    dependencies {

    // Maps SDK for Android
    implementation(libs.play.services.maps)
}

    Groovy

    dependencies {

    // Maps SDK for Android
    implementation "com.google.android.gms:play-services-maps:20.0.0"
}
  4. ในไฟล์ build.gradle.kts หรือ build.gradle ระดับโมดูล ให้ตั้งค่า compileSdk และ minSdk เป็นค่าต่อไปนี้:

    Kotlin

    android {
    compileSdk = 34

    defaultConfig {
        minSdk = 23
        // ...
    }
}

    Groovy

    android {
    compileSdk 34

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

    Kotlin

    android {
  // ...
  buildFeatures {
    buildConfig = true
    // ...
  }
}

    Groovy

    android {
  // ...
  buildFeatures {
    buildConfig true
    // ...
  }
}
  6. ในไฟล์ libs.versions.toml ให้เพิ่มโค้ดต่อไปนี้ 
    [versions]
play-services-maps = "20.0.0"

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

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

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

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

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

  1. ใน Android Studio ให้เปิดไฟล์ build.gradle ระดับราก แล้วเพิ่มโค้ดต่อไปนี้ลงในองค์ประกอบ dependencies ใน buildscript

    Groovy

    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

    Groovy

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

    Kotlin

    plugins {
    id("com.android.application")
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. หากใช้ Android Studio ให้ ซิงค์โปรเจ็กต์กับ Gradle
  4. เปิดไฟล์ local.properties ในไดเรกทอรีระดับโปรเจ็กต์ แล้วเพิ่ม โค้ดต่อไปนี้ แทนที่ YOUR_API_KEY ด้วยคีย์ API ของคุณ 
    MAPS_API_KEY=YOUR_API_KEY
  5. ในไฟล์ 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 จะแสดงข้อยกเว้น

ขั้นตอนที่ 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"/>

สิทธิ์พื้นที่จัดเก็บข้อมูลภายนอก

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

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

ไลบรารี Apache HTTP Legacy

หากคุณใช้ 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 API

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

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

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

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

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