ตั้งค่า

หน้านี้อธิบายสิ่งที่คุณต้องทำเพื่อตั้งค่าเพื่อเริ่มสร้างด้วย Maps 3D SDK สำหรับ Android ขั้นตอนการตั้งค่าประกอบด้วยการกำหนดค่าโปรเจ็กต์ Google Cloud และ API เพื่อใช้กับ SDK จากนั้นจึงตั้งค่าโปรเจ็กต์ Android Studio ทำตามขั้นตอนเหล่านี้ก่อนเพิ่มแผนที่ 3 มิติแรกลงในแอป

ข้อกำหนดเบื้องต้น

หากต้องการใช้ Maps 3D SDK สำหรับ Android โปรเจ็กต์และอุปกรณ์เป้าหมายของคุณต้องเป็นไปตามข้อกำหนดต่อไปนี้

• ระดับ API ขั้นต่ำ: Android API ระดับ 24 (Android 7.0) ขึ้นไป แอปของคุณต้องกำหนดเป้าหมายเป็น minSdk เวอร์ชัน 24 ขึ้นไป
• บริการ Google Play: Maps 3D SDK สำหรับ Android ต้องใช้บริการ Google Play อุปกรณ์เป้าหมาย (และโปรแกรมจำลองที่มี Google APIs) ต้องติดตั้งบริการ Google Play ไว้

ตั้งค่าโปรเจ็กต์ Google Cloud และคีย์ API

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

ขั้นตอนที่ 1

คอนโซล

1. ในคอนโซล Google Cloud บนหน้าตัวเลือกโปรเจ็กต์ ให้คลิกสร้างโปรเจ็กต์เพื่อเริ่มสร้างโปรเจ็กต์ Cloud ใหม่

   ไปที่หน้าตัวเลือกโปรเจ็กต์

2. ตรวจสอบว่าได้เปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์ที่อยู่ในระบบคลาวด์แล้ว ยืนยันว่าเปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์แล้ว

   Google Cloud มีช่วงทดลองใช้แบบไม่มีค่าใช้จ่าย ช่วงทดลองใช้จะหมดอายุเมื่อสิ้นสุด 90 วันหรือหลังจากที่บัญชีมีค่าใช้จ่ายสะสมถึง $300 แล้วแต่ว่ากรณีใดจะเกิดขึ้นก่อน ยกเลิกได้ทุกเมื่อ ดูข้อมูลเพิ่มเติมได้ที่เครดิตบัญชีสำหรับการเรียกเก็บเงินและการเรียกเก็บเงิน

Cloud SDK

gcloud projects create "PROJECT"

อ่านข้อมูลเพิ่มเติมเกี่ยวกับ Google Cloud SDK, การติดตั้ง Cloud SDK และคำสั่งต่อไปนี้

• gcloud projects create

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

ขั้นตอนที่ 2

หากต้องการใช้ Google Maps Platform คุณต้องเปิดใช้ API หรือ SDK ที่วางแผนจะใช้กับโปรเจ็กต์

โปรดทราบว่าการผสานรวมบางรายการกำหนดให้คุณต้องเปิดใช้ API/SDK หลายรายการ หากไม่แน่ใจว่าควรเปิดใช้ API หรือ SDK ใด ให้ลองใช้ Capabilities Explorer หรือดูเอกสารประกอบสำหรับ API/SDK ที่ต้องการใช้

วิธีเปิดใช้ API หรือ SDK อย่างน้อย 1 รายการ

คอนโซล

1. ดู API และ SDK ของ Google Maps Platform ที่คุณเปิดใช้ได้โดยไปที่หน้าคลัง Maps API ในคอนโซล Cloud ดังนี้

   ไปที่หน้าคลัง Maps API

2. คลิก API หรือ SDK ที่ต้องการเปิดใช้
   • หากปุ่มระบุว่าเปิดใช้ ให้คลิกปุ่มเพื่อเปิดใช้ API หรือ SDK
   • หากปุ่มระบุว่าจัดการ แสดงว่า API หรือ SDK เปิดใช้อยู่แล้ว และคุณไม่จำเป็นต้องดำเนินการใดๆ เพิ่มเติม
   • การคลิกปุ่มใดปุ่มหนึ่งจะแสดงแดชบอร์ดสำหรับ API หรือ SDK (คลิกปุ่มปิดใช้เพื่อนำ API หรือ SDK ออกจากโปรเจ็กต์นี้)

Cloud SDK

คำสั่งต่อไปนี้จะเปิดใช้ Maps, Routes และ Places API ทั้งหมด

gcloud services enable \
    --project "PROJECT" \
    "addressvalidation.googleapis.com" \
    "areainsights.googleapis.com" \
    "tile.googleapis.com" \
    "aerialview.googleapis.com" \
    "elevation-backend.googleapis.com" \
    "routes.googleapis.com" \
    "geocoding-backend.googleapis.com" \
    "geolocation.googleapis.com" \
    "maps-android-backend.googleapis.com" \
    "maps-backend.googleapis.com" \
    "maps-embed-backend.googleapis.com" \
    "maps-ios-backend.googleapis.com" \
    "mapsplatformdatasets.googleapis.com" \
    "places-backend.googleapis.com" \
    "roads.googleapis.com" \
    "routeoptimization.googleapis.com" \
    "static-maps-backend.googleapis.com" \
    "street-view-image-backend.googleapis.com" \
    "timezone-backend.googleapis.com"

อ่านข้อมูลเพิ่มเติมเกี่ยวกับ Google Cloud SDK, การติดตั้ง Cloud SDK และคำสั่งต่อไปนี้

• gcloud services enable
• gcloud services disable

ใช้คำสั่งนี้เพื่อเปิดใช้ Environment API

gcloud services enable \
    --project "PROJECT" \
    "airquality.googleapis.com" \
    "solar.googleapis.com" \
    "pollen.googleapis.com" \
    "weather.googleapis.com"

หมายเหตุ: การเปิดใช้ Places API จะเปิดใช้ Places Library, Maps JavaScript API, Places SDK สำหรับ Android และ Places SDK สำหรับ iOS ด้วย

ขั้นตอนที่ 3

ขั้นตอนนี้จะอธิบายเฉพาะกระบวนการสร้างคีย์ API เท่านั้น หากคุณใช้คีย์ API ในเวอร์ชันที่ใช้งานจริง เราขอแนะนำอย่างยิ่งให้จำกัดคีย์ API ดูข้อมูลเพิ่มเติมได้ในหน้าการใช้คีย์ API เฉพาะผลิตภัณฑ์

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

วิธีสร้างคีย์ API

คอนโซล

1. ไปที่หน้า Google Maps Platform > ข้อมูลเข้าสู่ระบบ

   ไปที่หน้าข้อมูลเข้าสู่ระบบ

2. ในหน้าข้อมูลเข้าสู่ระบบ ให้คลิกสร้างข้อมูลเข้าสู่ระบบ > คีย์ API
   กล่องโต้ตอบสร้างคีย์ API แล้วจะแสดงคีย์ API ที่สร้างขึ้นใหม่
3. คลิกปิด
   คีย์ API ใหม่จะแสดงในหน้าข้อมูลเข้าสู่ระบบในส่วนคีย์ API
   (อย่าลืมจำกัดคีย์ API ก่อนใช้ในเวอร์ชันที่ใช้งานจริง)

Cloud SDK

gcloud services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

อ่านข้อมูลเพิ่มเติมเกี่ยวกับ Google Cloud SDK, การติดตั้ง Cloud SDK และคำสั่งต่อไปนี้

• gcloud services api-keys create

หากต้องการเปิดใช้ SDK โปรดดูหน้า Maps 3D SDK สำหรับ Android ในคอนโซล Google Cloud ดูข้อมูลเพิ่มเติมเกี่ยวกับการทำตามขั้นตอนเหล่านี้ได้ที่การเริ่มต้นใช้งาน Google Maps Platform

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

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

ส่วนที่ 1: ตั้งค่าโปรเจ็กต์และการกำหนดค่า Gradle

1. สร้างโปรเจ็กต์ Android Studio ใหม่โดยใช้เทมเพลต Empty Views Activity ในการกำหนดค่าโปรเจ็กต์ ให้ตั้งค่า SDK ขั้นต่ำเป็น API 24 ขึ้นไป

2. หากคุณใช้ Git สำหรับการควบคุมแหล่งที่มา ให้แก้ไขไฟล์ .gitignore ของโปรเจ็กต์เพื่อป้องกันไม่ให้ระบบส่งไฟล์ข้อมูลลับไปยังการควบคุมเวอร์ชัน

   • เปิดไฟล์ .gitignore ในไดเรกทอรีรากของโปรเจ็กต์
   • เพิ่มบรรทัดต่อไปนี้

   secrets.properties
   

3. อัปเดตไฟล์ build.gradle.kts ระดับโปรเจ็กต์โดยทำดังนี้

   • เปิดไฟล์ build.gradle.kts ในไดเรกทอรีรากของโปรเจ็กต์
   • ในบล็อก plugins ให้เพิ่มปลั๊กอิน Secrets Gradle ดังนี้

   plugins {
     alias(libs.plugins.android.application) apply false
     alias(libs.plugins.kotlin.android) apply false
     alias(libs.plugins.secrets.gradle.plugin) apply false // Add this line
   }
   

4. อัปเดตไฟล์ gradle/libs.versions.toml โดยทำดังนี้

   • เปิดไฟล์ gradle/libs.versions.toml ซึ่งมักจะอยู่ในไดเรกทอรี gradle ภายในไดเรกทอรีรากของโปรเจ็กต์
   • ในส่วน [versions] ให้เพิ่มเวอร์ชันสำหรับ SDK และปลั๊กอิน Secrets Gradle ดังนี้

   # See https://developers.google.com/android/guides/setup?device=phone-tablet for available releases
   maps3dSdk = "16.0.1"
   # See https://github.com/google/secrets-gradle-plugin/releases for available releases
   secretsGradlePlugin = "2.0.1"
   

   • ในส่วน [library] ให้เพิ่มไลบรารี SDK ดังนี้

   play-services-maps3d = { module = "com.google.android.gms:play-services-maps3d", version.ref = "maps3dSdk" }
   

   • ในส่วน [plugins] ให้เพิ่มปลั๊กอิน Secrets Gradle ดังนี้

   secrets-gradle-plugin = { id = "com.google.android.libraries.mapsplatform.secrets-gradle-plugin", version.ref = "secretsGradlePlugin" }
   

5. อัปเดตไฟล์ app/build.gradle.kts ระดับโมดูลโดยทำดังนี้

   • เปิดไฟล์ build.gradle.kts ระดับโมดูล ซึ่งมักจะอยู่ในไดเรกทอรี app
   • ที่ด้านบนของไฟล์ ให้เพิ่มปลั๊กอิน Secrets Gradle ลงในบล็อก plugins ดังนี้

   plugins {
       alias(libs.plugins.android.application)
       alias(libs.plugins.kotlin.android)
       alias(libs.plugins.secrets.gradle.plugin) // Add this line
   }
   

   • ในบล็อก dependencies ให้เพิ่มทรัพยากร Dependency ของบริการ Google Play สำหรับ Maps 3D SDK สำหรับ Android ดังนี้

   dependencies {
       // ... other dependencies
       implementation(libs.play.services.maps3d) // Add this line
   }
   

   • ที่ส่วนท้ายของไฟล์ นอกบล็อก android และ dependencies ให้เพิ่มการกำหนดค่าข้อมูลลับดังนี้

   secrets {
       // Optionally specify a different filename 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"
   }
   

ส่วนที่ 2: เพิ่มคีย์ API ลงในโปรเจ็กต์

1. สร้างไฟล์ secrets.properties โดยทำดังนี้

   • ในไดเรกทอรีรากของโมดูลแอป (โดยปกติจะเป็นไดเรกทอรี app) ให้สร้างไฟล์ใหม่ชื่อ secrets.properties
   • เพิ่มคีย์ API ลงในไฟล์โดยทำดังนี้

   MAPS3D_API_KEY=YOUR_API_KEY_HERE
   

   หมายเหตุ: อย่าลืมแทนที่ YOUR_API_KEY_HERE ด้วยคีย์ API ที่คุณกำหนดค่าไว้เพื่อใช้กับ Maps 3D SDK สำหรับ Android

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

   MAPS3D_API_KEY=DEFAULT_API_KEY_OR_PLACEHOLDER
   

ส่วนที่ 3: อัปเดตไฟล์ AndroidManifest.xml

1. เปิดไฟล์ app/src/main/AndroidManifest.xml

2. ภายในแท็ก <application> ก่อนแท็ก <activity> ให้เพิ่มองค์ประกอบ <meta-data> ต่อไปนี้เพื่อประกาศคีย์ API

   <application
       ...>
   
       <meta-data
           android:name="com.google.android.geo.maps3d.API_KEY"
           android:value="${MAPS3D_API_KEY}" />
   
       <activity
           ...>
       </activity>
   </application>
   

   ในระหว่างกระบวนการบิลด์ ปลั๊กอิน Secrets Gradle จะแทนที่ตัวยึดตำแหน่ง ${MAPS3D_API_KEY} ด้วยคีย์จากไฟล์ secrets.properties

การเริ่มต้นมุมมองแบบเป็นโปรแกรม (ไม่บังคับ)

หากต้องการเริ่มต้นมุมมองแผนที่แบบเป็นโปรแกรมแทนที่จะใช้เลย์เอาต์ XML ให้ใช้ Map3DInitConfig

import com.google.android.gms.maps3d.Map3DInitConfig
import com.google.android.gms.maps3d.Map3DView
import com.google.android.gms.maps3d.model.Map3DMode

// Set configuration options using the factory method
val config = Map3DInitConfig.create(
    mapMode = Map3DMode.HYBRID,
    centerLat = 38.544012,
    centerLng = -107.670428
)

val map3DView = Map3DView(context, config)

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

เมื่อคุณมีโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google, คีย์ API และโปรเจ็กต์ Android Studio ที่ตั้งค่าไว้เพื่อใช้กับ Maps 3D SDK สำหรับ Android แล้ว คุณสามารถเพิ่มแผนที่ 3 มิติลงในแอปได้