ตั้งค่า Geospatial API ในแอป

อุปกรณ์ XR ที่รองรับ

คำแนะนำนี้จะช่วยคุณสร้างประสบการณ์การใช้งานสำหรับอุปกรณ์ XR ประเภทนี้

ดูข้อมูลเกี่ยวกับประเภทอุปกรณ์ XR →

ดูข้อมูลเกี่ยวกับประเภทอุปกรณ์ XR →

หากต้องการใช้ Geospatial API ในแอป คุณต้องตั้งค่าแอปให้เข้าถึง ARCore API ใน Google Cloud API นี้มีบริการระบุตำแหน่งด้วยภาพที่ให้การระบุตำแหน่งที่แม่นยำโดยใช้ข้อมูลจาก Google Street View

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

ตั้งค่าโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google หรือใช้โปรเจ็กต์ที่มีอยู่

หากมีโปรเจ็กต์ Google Cloud อยู่แล้ว ให้เลือกโปรเจ็กต์นั้น

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

หากยังไม่มีโปรเจ็กต์ ให้สร้างโปรเจ็กต์

สร้างโปรเจ็กต์ใหม่

เปิดใช้ ARCore API

หากต้องการใช้ ARCore API คุณต้องเปิดใช้ API ดังกล่าวในโปรเจ็กต์

เปิดใช้ ARCore API

ตั้งค่าการให้สิทธิ์สำหรับ Google Cloud

แอปพลิเคชัน Android สามารถสื่อสารกับ ARCore API ได้โดยใช้วิธีการให้สิทธิ์ 2 วิธีที่แตกต่างกัน ได้แก่ การให้สิทธิ์แบบไม่ใช้คีย์ (OAuth 2.0) ซึ่งเป็นวิธีที่แนะนำ และการให้สิทธิ์คีย์ API ดังนี้

• การให้สิทธิ์แบบไม่ใช้คีย์จะใช้ชื่อแพ็กเกจของแอปพลิเคชันและลายนิ้วมือของคีย์ Signing ร่วมกันเพื่อให้สิทธิ์แอปพลิเคชัน

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

<meta-data
  android:name="com.google.android.ar.API_KEY"
  android:value="API_KEY"/>

ขอสิทธิ์ที่จำเป็น

หากต้องการใช้ Geospatial API ใน ARCore กับ Jetpack XR แอปของคุณต้องขอสิทธิ์รันไทม์ต่อไปนี้

• ACCESS_FINE_LOCATION: ต้องใช้เพื่อระบุตำแหน่งที่แน่นอนของผู้ใช้

ในอุปกรณ์เคลื่อนที่ Geospatial API ยังต้องใช้สิทธิ์ต่อไปนี้ด้วย

• android.permission.CAMERA: ต้องใช้เพื่อเข้าถึงกล้องของอุปกรณ์
• android.permission.INTERNET: จำเป็นสำหรับการสื่อสารกับบริการ Google Cloud

เข้าถึงเซสชัน

เข้าถึงข้อมูลเชิงพื้นที่ผ่าน Jetpack XR Runtime Session ซึ่งแอปของคุณต้องสร้าง

กำหนดค่าเซสชัน

Geospatial API ไม่ได้เปิดใช้โดยค่าเริ่มต้นในเซสชัน XR แอปของคุณต้องเปิดใช้อย่างชัดแจ้งโดยกำหนดค่า GeospatialMode ใน Session โดยมีโหมดต่อไปนี้ให้เลือกใช้

• GeospatialMode.SPATIAL: Geospatial API เปิดใช้อยู่ Geospatial API ใช้ข้อมูลระบบกำหนดตำแหน่งด้วยภาพ (VPS), ระบบดาวเทียมนำร่อง (GPS) และเซ็นเซอร์ตรวจจับการเคลื่อนไหวของอุปกรณ์เพื่อระบุท่าทางเชิงพื้นที่ของอุปกรณ์ โหมดนี้ไม่พร้อมใช้งานในอุปกรณ์แว่นตาอัจฉริยะ
• GeospatialMode.INERTIAL: Geospatial API เปิดใช้ในโหมดใช้พลังงานต่ำ Geospatial API ใช้เฉพาะ GPS และเซ็นเซอร์ตรวจจับการเคลื่อนไหวของอุปกรณ์เพื่อระบุท่าทางเชิงพื้นที่ของอุปกรณ์ โหมดนี้ใช้ได้เฉพาะในอุปกรณ์แว่นตาอัจฉริยะเท่านั้น
• GeospatialMode.DISABLED: Geospatial API ปิดอยู่ เมื่อเปลี่ยนจากโหมดอื่นมาเป็นโหมดนี้ Geospatial API จะปล่อยทรัพยากรทั้งหมดที่ได้รับมาและหยุดการติดตาม

อุปกรณ์บางรุ่นไม่รองรับโหมดเชิงพื้นที่บางโหมด ดูข้อมูลเพิ่มเติมได้ที่ GeospatialMode ใช้ XrDevice.isGeospatialSupported เพื่อดูว่าระบบรองรับ GeospatialMode ที่ระบุหรือไม่

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีตั้งค่า GeospatialMode โดยใช้ Session.configure

// Define the configuration object to enable Geospatial features.
val newConfig = Config.Builder(session.config)
    .setGeospatial(GeospatialMode.SPATIAL)
    .build()
// Apply the configuration to the session.
try {
    when (val configResult = session.configure(newConfig)) {
        is SessionConfigureSuccess -> {
            // The session is now configured to use the Geospatial API.
        }

        else -> {
            // Handle other configuration errors (e.g., missing library dependencies).
        }
    }
} catch (e: UnsupportedOperationException) {
    // Handle configuration failure if the mode is not supported.
}
Setup.kt

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

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

ใช้ออบเจ็กต์ภูมิสารสนเทศ

เมื่อกำหนดค่าเซสชันแล้ว ให้รับออบเจ็กต์ Geospatial โดยใช้ Geospatial.getInstance ใช้ออบเจ็กต์ Geospatial เมื่อสถานะเป็น GeospatialTrackingState.RUNNING เท่านั้น

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีตรวจสอบสถานะเชิงพื้นที่โดยใช้ Geospatial.state

val geospatial = remember { Geospatial.getInstance(session) }
val geospatialState by geospatial.state.collectAsStateWithLifecycle()
if (geospatialState.geospatialTrackingState == Geospatial.GeospatialTrackingState.RUNNING) {
    // Queries to the Geospatial API are only valid when the state is RUNNING.
}
Setup.kt

val geospatial = Geospatial.getInstance(session)
lifecycleScope.launch {
    geospatial.state.collect { geospatialState ->
        if (geospatialState == Geospatial.GeospatialTrackingState.RUNNING) {
            // Queries to the Geospatial API are only valid when the state is RUNNING.
        }
    }
}
Setup.kt

ทำความเข้าใจค่าความแม่นยำ

ขณะที่เปิดใช้ Geospatial API ระบบจะแสดงค่าความแม่นยำ 3 ค่า ได้แก่ ความแม่นยำในแนวนอน แนวตั้ง และการวางแนว ค่าความแม่นยำเหล่านี้จะได้รับการอัปเดตเมื่อเวลาผ่านไป และจะแม่นยำยิ่งขึ้นเมื่อได้รับข้อมูลมากขึ้น ค่าที่สูงขึ้นแสดงถึงความแม่นยำที่ต่ำลง และกำหนดเป็นรัศมีของระดับความเชื่อมั่น 68% กล่าวคือ มีความเป็นไปได้ 68% ที่ค่าจริงจะอยู่ในรัศมีที่ระบุของค่าโดยประมาณ

ใช้ Geospatial.State.horizontalAccuracy, verticalAccuracy และ orientationYawAccuracy เพื่อรับค่าความแม่นยำปัจจุบัน

แอปของคุณอาจต้องใช้ความแม่นยำในระดับหนึ่งเพื่อให้ทำงานได้อย่างถูกต้อง ตัวอย่างเช่น แอปอาจต้องรอจนกว่าความแม่นยำในแนวนอนจะน้อยกว่า 5 เมตรก่อนที่จะแสดงผลเนื้อหาเสมือนจริง หากต้องการเพิ่มโอกาสในการได้รับข้อมูลที่มีความแม่นยำสูงขึ้น แอปควรแนะนำให้ผู้ใช้มองไปรอบๆ โดยเฉพาะอาคารหรือจุดสังเกตอื่นๆ ที่มีรายละเอียดภาพสูงซึ่งปรากฏใน Google Street View ใช้ Geospatial.checkVpsAvailability เพื่อระบุว่า VPS พร้อมใช้งานในตำแหน่งที่ระบุหรือไม่

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

เมื่อตั้งค่า Geospatial API ในแอปอย่างถูกต้องแล้ว แอปจะทำสิ่งต่อไปนี้ได้

• แปลงระหว่างท่าทางในอุปกรณ์และท่าทางเชิงพื้นที่
• แสดงผลเนื้อหาที่ท่าทางภูมิสารสนเทศ