ตั้งค่าโปรเจ็กต์ 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 ไว้ในบล็อก pluginManagement pluginManagement บล็อก ต้องปรากฏก่อนคำสั่งอื่นๆ ในสคริปต์ 
    pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
  2. ในไฟล์ settings.gradle.kts ระดับบนสุด ให้ใส่ ที่เก็บ Maven ของ Google และที่เก็บ Maven Central ภายใต้บล็อก dependencyResolutionManagement ดังนี้ 
    dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
  3. ในไฟล์ build.gradle.kts หรือ build.gradle ระดับโมดูล ให้เพิ่มทรัพยากร Dependency ของ Google Play Services สำหรับ 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:19.0.0"
}
  4. ในไฟล์ build.gradle.kts หรือ build.gradle ระดับโมดูล ให้ ตั้งค่า compileSdk และ minSdk เป็นค่าต่อไปนี้

    Kotlin

    android {
    compileSdk = 34

    defaultConfig {
        minSdk = 21
        // ...
    }
}

    ดึงดูด

    android {
    compileSdk 34

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

    Kotlin

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

    ดึงดูด

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

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

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

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

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

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

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

    ดึงดูด

    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

    ดึงดูด

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

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

หากกำหนดเป้าหมายเป็น 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 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 5.0 ขึ้นไปและมี Google APIs

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

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

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

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

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