ตั้งค่าโปรเจ็กต์ 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 ระดับบนสุด ให้ใส่พอร์ทัลปลั๊กอิน 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 {

    // Maps SDK for Android
    implementation 'com.google.android.gms:play-services-maps:18.2.0'
}

    Kotlin

    dependencies {

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

    ดึงดูด

    android {
    compileSdk 34

    defaultConfig {
        minSdk 19
        // ...
    }
}

    Kotlin

    android {
    compileSdk = 34

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

    ดึงดูด

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

    Kotlin

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

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

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

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

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

  1. ใน Android Studio ให้เปิดไฟล์ build.gradle หรือ build.gradle.kts ระดับบนสุด แล้วเพิ่มโค้ดต่อไปนี้ลงในองค์ประกอบ 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.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}

    Kotlin

    plugins {
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. ในไฟล์ 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 or build.gradle.kts 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.

    Groovy

    secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    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.*"
}

    Kotlin

    secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    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 4.0 ขึ้นไปและมี Google APIs

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

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

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

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

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