เปิดใช้ Geospatial API สำหรับแอป Android (Kotlin/Java)

กำหนดการตั้งค่าของแอปเพื่อให้ใช้ Geospatial API ได้

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

โปรดทำความเข้าใจแนวคิด AR พื้นฐานและวิธีกำหนดค่าเซสชัน ARCore ก่อนดำเนินการต่อ

ตัวอย่างแอปและ Codelab

วิดีโอนี้อธิบายขั้นตอนการสร้างแอปที่แสดงข้อมูลเชิงพื้นที่และวางเนื้อหาในสถานที่ตั้งจริงโดยใช้ Geospatial API

หรือจะทำตามขั้นตอนเดียวกันจากเอกสารประกอบ Geospatial Codelab ก็ได้ หากต้องการเรียกใช้แอปตัวอย่างที่สร้างขึ้นในวิดีโอ โปรดดู ARCore Geospatial Quickstart

โปรดดูข้อมูลเบื้องต้นเกี่ยวกับ Geospatial API สำหรับข้อมูลเพิ่มเติมเกี่ยวกับ Geospatial API

หากคุณเพิ่งเริ่มพัฒนาด้วย ARCore โปรดดูข้อมูลเกี่ยวกับข้อกำหนดของซอฟต์แวร์และฮาร์ดแวร์ ข้อกําหนดเบื้องต้น และข้อมูลอื่นๆ ที่เฉพาะเจาะจงสําหรับแพลตฟอร์มที่คุณใช้ในส่วนเริ่มต้นใช้งาน

ตรวจสอบว่าสภาพแวดล้อมการพัฒนาเป็นไปตามข้อกำหนดของ ARCore SDK ตามที่อธิบายไว้ในเริ่มต้นใช้งานอย่างรวดเร็ว

เปิดใช้ ARCore API

ก่อนใช้ระบบการระบุตำแหน่งด้วยภาพ (VPS) ในแอป คุณต้องเปิดใช้ ARCore API ในโปรเจ็กต์ Google Cloud ใหม่หรือที่มีอยู่ก่อน บริการนี้มีหน้าที่รับผิดชอบในการโฮสต์ จัดเก็บ และแก้ไขหมุดยึดเชิงพื้นที่

เราขอแนะนำให้ใช้การให้สิทธิ์แบบไม่ใช้คีย์ แต่ก็รองรับการให้สิทธิ์คีย์ API ด้วย

เพิ่มไลบรารีที่จําเป็นลงในแอป

หลังจากให้สิทธิ์แอปเรียกใช้ ARCore API แล้ว คุณต้องเพิ่มไลบรารีเพื่อเปิดใช้ฟีเจอร์ภูมิสารสนเทศในแอป

ในไฟล์ build.gradle ของแอป ให้ตั้งค่าบริการ Google Play ให้รวมไลบรารีตำแหน่งของ Play Services

dependencies {
  // Apps must declare play-services-location version >= 16.
  // In the following line, substitute `16 (or later)` with the latest version.
  implementation 'com.google.android.gms:play-services-location:16 (or later)'
}

เปิดใช้ความสามารถเชิงพื้นที่ในการกําหนดค่าเซสชัน

ก่อนสร้างเซสชัน ให้เปลี่ยน GeospatialMode ในการกำหนดค่าเซสชันเป็น ENABLED โดยทำดังนี้

Java

Config config = session.getConfig();
config.setGeospatialMode(Config.GeospatialMode.ENABLED);
session.configure(config);

Kotlin

// Enable the Geospatial API.
session.configure(session.config.apply { geospatialMode = Config.GeospatialMode.ENABLED })

เมื่อตั้งค่าโหมดภูมิสารสนเทศเชิงพื้นที่เป็น ENABLED แอปพลิเคชันจะได้รับอนุญาตให้รับข้อมูลทางภูมิศาสตร์จากระบบการระบุตำแหน่งด้วยภาพ (VPS)

แจ้งให้ผู้ใช้อนุญาตการใช้ข้อมูลอุปกรณ์

แอปที่ใช้ ARCore Geospatial API ต้องแสดงข้อความแจ้งให้ผู้ใช้รับทราบและอนุญาตให้ใช้ข้อมูลจากอุปกรณ์ ดูข้อมูลเพิ่มเติมได้ในข้อกำหนดด้านความเป็นส่วนตัวของผู้ใช้

ตรวจสอบความเข้ากันได้ของอุปกรณ์

อุปกรณ์ที่รองรับ ARCore บางรุ่นอาจไม่รองรับ Geospatial API ด้วย ตามที่อธิบายไว้ในคู่มือเริ่มต้นใช้งาน

หากต้องการตรวจสอบความเข้ากันได้ของอุปกรณ์ของผู้ใช้ ให้โทรไปที่ Session.checkGeospatialModeSupported() หากค่านี้แสดงผลเป็นเท็จ อย่าพยายามกําหนดค่าเซสชัน (ด้านล่าง) เนื่องจากการดำเนินการดังกล่าวจะทำให้เกิดUnsupportedConfigurationException

ขอสิทธิ์เข้าถึงตําแหน่งจากผู้ใช้ขณะรันไทม์

แอปของคุณต้องขอสิทธิ์เข้าถึงตำแหน่งเมื่อรันไทม์

หากต้องการใช้ ARCore Geospatial API แอปของคุณต้องลงทะเบียนสิทธิ์เพิ่มเติมต่อไปนี้

  • ACCESS_FINE_LOCATION เพื่อระบุตําแหน่งของผู้ใช้อย่างถูกต้อง

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

  • ACCESS_INTERNET เพื่อติดต่อบริการ ARCore Geospatial API

<manifest ... >
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.INTERNET" />
</manifest>

ในอุปกรณ์ที่ใช้ Android เวอร์ชัน 12 ขึ้นไป ผู้ใช้จะขอให้แอปของคุณเข้าถึงได้เฉพาะข้อมูลตำแหน่งโดยประมาณเท่านั้น หากต้องการรองรับคําขอนี้ แอปของคุณต้องมีการกําหนดค่าสิทธิ์ ACCESS_COARSE_LOCATION พร้อมกับ ACCESS_FINE_LOCATION ตามที่แสดงด้านบน คุณต้องกำหนดค่าสิทธิ์เข้าถึงตำแหน่งทั้ง 2 รายการ

อย่างไรก็ตาม เมื่อผู้ใช้ระบุตำแหน่งคร่าวๆ การดำเนินการดังกล่าวจะป้องกันไม่ให้ Geospatial API รับตำแหน่งที่แน่นอนที่ต้องการ บริการเชิงพื้นที่จะไม่อนุญาตให้กําหนดค่าหากแอปของคุณระบุตําแหน่งคร่าวๆ เท่านั้น แอปของคุณใช้ Geospatial API กับตำแหน่งแบบหยาบไม่ได้

ตรวจสอบความพร้อมให้บริการของข้อมูลเชิงพื้นที่ ณ ตำแหน่งปัจจุบันของอุปกรณ์

เนื่องจาก Geospatial API ใช้ VPS และ GPS ร่วมกันในการกำหนดตำแหน่งของภูมิสารสนเทศ จึงสามารถใช้ API ดังกล่าวได้ตราบเท่าที่อุปกรณ์สามารถระบุตำแหน่งของตนได้ ในพื้นที่ที่มีความแม่นยำของ GPS ต่ำ เช่น พื้นที่ในอาคารและสภาพแวดล้อมในเมืองที่หนาแน่น API จะอาศัยความครอบคลุมของ VPS เพื่อสร้างท่าทางที่มีความแม่นยำสูง ภายใต้สภาพทั่วไป VPS จะมีความแม่นยำของตำแหน่งประมาณ 5 เมตรและความแม่นยำของการหมุนประมาณ 5 องศา ใช้ Session.checkVpsAvailabilityAsync() เพื่อดูว่าตำแหน่งหนึ่งๆ มีบริการ VPS หรือไม่

นอกจากนี้ คุณยังใช้ Geospatial API ในพื้นที่ที่ไม่มี VPS ครอบคลุมได้ด้วย ในสภาพแวดล้อมกลางแจ้งที่มีสิ่งกีดขวางเหนือศีรษะเพียงเล็กน้อยหรือไม่มีเลย GPS อาจเพียงพอที่จะสร้างท่าทางที่มีความแม่นยำสูง

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