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

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

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

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

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

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

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

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

    Kotlin

    dependencies {

    // Maps SDK for Android
    implementation("com.google.android.gms:play-services-maps:19.0.0")
}

    ดึงดูด

    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
    // ...
  }
}

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

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

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

วิธีติดตั้งปลั๊กอินข้อมูลลับ Gradle สําหรับ Android ในโปรเจ็กต์ Google Maps

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

    Kotlin

    buildscript {
    dependencies {
        classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
    }
}

    ดึงดูด

    buildscript {
    dependencies {
        classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
    }
}
  2. เปิดไฟล์ build.gradle.kts หรือ build.gradle ระดับโมดูล แล้วเพิ่มโค้ดต่อไปนี้ลงในองค์ประกอบ plugins

    Kotlin

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

    ดึงดูด

    plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}
  3. ในไฟล์ build.gradle.kts หรือ build.gradle ระดับโมดูล ให้ตรวจสอบว่าได้ตั้งค่า targetSdk และ compileSdk เป็น 34
  4. บันทึกไฟล์และซิงค์โปรเจ็กต์กับ Gradle
  5. เปิดไฟล์ secrets.properties ในไดเรกทอรีระดับบนสุด แล้วเพิ่ม โค้ดต่อไปนี้ แทนที่ YOUR_API_KEY ด้วยคีย์ API ของคุณ จัดเก็บคีย์ของคุณในไฟล์นี้ เนื่องจาก secrets.properties ถูกยกเว้นจากการเช็คอินในการควบคุมเวอร์ชัน ระบบ 
    MAPS_API_KEY=YOUR_API_KEY
  6. บันทึกไฟล์

  7. สร้างไฟล์ local.defaults.properties ในไดเรกทอรีระดับบนสุด เป็นไฟล์ secrets.properties แล้วเพิ่มโค้ดต่อไปนี้

    MAPS_API_KEY=DEFAULT_API_KEY

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

  8. บันทึกไฟล์
  9. ในไฟล์ AndroidManifest.xml ให้ไปที่ com.google.android.geo.API_KEY แล้วอัปเดต android:value attribute หากไม่มีแท็ก <meta-data> ให้สร้างเป็นแท็กย่อยของ <application> 
    <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

    Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

  10. In Android Studio, open your module-level build.gradle.kts or build.gradle file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other 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 same folder as the 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"

    // Configure which keys should be ignored by the plugin by providing regular expressions.
    // "sdk.dir" is ignored by default.
    ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
    ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
}

    ดึงดูด

    secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the same folder as the 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"

    // Configure which keys should be ignored by the plugin by providing regular expressions.
    // "sdk.dir" is ignored by default.
    ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
    ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
}

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

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

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

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

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

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