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

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

เทมเพลต Google แผนที่จะกำหนดค่าและเพิ่มแผนที่พื้นฐานลงใน โปรเจ็กต์ 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 ระดับโมดูล ให้เพิ่ม การพึ่งพาบริการ Google Play สำหรับ Maps SDK สำหรับ Android

    ดึงดูด

    dependencies {

    // Maps SDK for Android
    implementation 'com.google.android.gms:play-services-maps:19.0.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 21
        // ...
    }
}

    Kotlin

    android {
    compileSdk = 34

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

    ดึงดูด

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

    Kotlin

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

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

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

เราขอแนะนำให้คุณใช้ ปลั๊กอินข้อมูลลับ 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 5.0 ขึ้นไปและมี Google API

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

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

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

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

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