ตั้งค่าโปรเจ็กต์ 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.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

วิธีติดตั้งปลั๊กอิน Secrets 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}" />

    หมายเหตุ 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 เพียงชื่อเดียว หากระบุไว้ทั้งคู่ API มีข้อยกเว้น

  10. ใน Android Studio ให้เปิด build.gradle.kts ระดับโมดูลหรือ build.gradle แล้วแก้ไขพร็อพเพอร์ตี้ secrets หาก ไม่มีพร็อพเพอร์ตี้ secrets โปรดเพิ่ม

    แก้ไขคุณสมบัติของปลั๊กอินเพื่อตั้งค่า propertiesFileName เป็น secrets.properties ตั้งค่า defaultPropertiesFileName เป็น local.defaults.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 คุณสามารถสร้างอุปกรณ์เสมือนและติดตั้งโปรแกรมจำลองโดยใช้ โปรแกรมจัดการอุปกรณ์เสมือน (AVD) สำหรับ Android ที่มาพร้อมกับ Android Studio

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

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

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

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