เปิดใช้ Geospatial API สำหรับแอป NDK ของ Android (C)

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

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

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

หากต้องการเรียกใช้ตัวอย่างแอปที่สาธิตฟังก์ชันการทำงานที่อธิบายไว้ที่นี่ โปรดดูการเริ่มต้นใช้งาน Geospatial ของ ARCore อย่างรวดเร็วสําหรับ Android สําหรับ Java แอปตัวอย่างในการเริ่มต้นใช้งานอย่างรวดเร็วเขียนด้วย Java ตัวอย่างโค้ดในเอกสารนี้มีไว้สำหรับฟังก์ชันการทำงานเดียวกันซึ่งเขียนด้วย C

ดูข้อมูลเพิ่มเติมเกี่ยวกับ Geospatial API ได้ที่ข้อมูลเบื้องต้นเกี่ยวกับ Geospatial API

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

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

เปิดใช้ 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

// Create a session config.
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);

// Enable the Geospatial API.
ArConfig_setGeospatialMode(ar_session, ar_config, AR_GEOSPATIAL_MODE_ENABLED);
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);

// Release config resources.
ArConfig_destroy(ar_config);

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

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

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

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

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

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

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

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

หากต้องการใช้ 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 องศา ใช้ ArSession_checkVpsAvailabilityAsync() เพื่อดูว่าตำแหน่งหนึ่งๆ มีบริการ VPS หรือไม่

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

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