คู่มือนักพัฒนาซอฟต์แวร์ Cloud Anchor สำหรับ Unity (AR Foundation)

ดูวิธีใช้ Cloud Anchor ในแอปของคุณเอง

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

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

หากคุณเพิ่งเริ่มใช้ Cloud Anchor ให้ทำความเข้าใจว่า Anchor และ Cloud Anchor ทำงานอย่างไร

เปิดใช้ ARCore API

ก่อนที่จะใช้ Cloud Anchor ในแอป คุณต้องเปิดใช้ ARCore API ในแอปพลิเคชันก่อน

เปิดใช้ความสามารถของ Cloud Anchor ในการกำหนดค่าเซสชัน

เมื่อเปิดใช้ฟังก์ชันการทำงานของ Cloud Anchor ในแอป ให้เปิดใช้ความสามารถของ Cloud Anchor ในการกำหนดค่าเซสชัน AR ของแอปเพื่อให้สื่อสารกับ ARCore API ได้ ดังนี้

โฮสต์ Cloud Anchor

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

นอกจากนี้คุณยังยืดอายุการใช้งานของ Anchor ที่โฮสต์ได้โดยใช้ ARCore Cloud Anchor Management API

แอปของคุณควรทำตามขั้นตอนเหล่านี้เพื่อโฮสต์ Cloud Anchor ให้เสร็จสมบูรณ์

  1. โทร ARAnchorManager.HostCloudAnchorAsync()
  2. เริ่มต้น Coroutine เพื่อรอจนกว่า Promise จะได้ผลลัพธ์ ดูข้อมูลเพิ่มเติมที่คอลัมน์ใน Unity
  3. ตรวจสอบสถานะผลลัพธ์เพื่อดูว่าการดำเนินการสำเร็จหรือไม่ หรือตีความรหัสข้อผิดพลาดเมื่อล้มเหลว
  4. แชร์รหัส Cloud Anchor ที่มีกับไคลเอ็นต์อื่นๆ และใช้เพื่อแก้ไข Cloud Anchor ด้วย ARAnchorManagerExtensions.ResolveCloudAnchorAsync()

ตรวจสอบคุณภาพการแมปของจุดฟีเจอร์

ARCoreExtensions.FeatureMapQuality ระบุคุณภาพของจุดฟีเจอร์ที่ ARCore เห็นในช่วง 2-3 วินาทีก่อนหน้านี้จากท่าทางของกล้องที่ระบุ โดยทั่วไปแล้ว Cloud Anchor ที่โฮสต์โดยใช้ฟีเจอร์ที่มีคุณภาพสูงกว่าจะได้รับการแก้ไขอย่างถูกต้องกว่า ใช้ ARAnchorManagerExtensions.EstimateFeatureMapQualityForHosting() เพื่อรับค่าประมาณสำหรับคุณภาพของแผนที่ฟีเจอร์สำหรับท่ากล้องที่ระบุ

ค่า คำอธิบาย
Insufficient คุณภาพของจุดฟีเจอร์ที่ระบุจากท่าทางในช่วง 2-3 วินาทีก่อนหน้านี้อยู่ในระดับต่ำ สถานะนี้บ่งบอกว่า ARCore น่าจะแก้ปัญหา Cloud Anchor ได้ยาก กระตุ้นให้ผู้ใช้ย้ายอุปกรณ์เพื่อให้ดูตำแหน่งที่ต้องการของ Cloud Anchor ที่ต้องการโฮสต์ได้จากมุมต่างๆ
Sufficient คุณภาพของจุดฟีเจอร์ที่ระบุจากท่าทางในช่วง 2-3 วินาทีก่อนหน้านี้น่าจะเพียงพอให้ ARCore แก้ไข Anchor ของ Cloud ได้สำเร็จ แม้ว่าความแม่นยำของท่าทางที่แก้ไขแล้วจะลดลง กระตุ้นให้ผู้ใช้ย้ายอุปกรณ์เพื่อให้ดูตำแหน่งที่ต้องการของ Cloud Anchor ที่ต้องการโฮสต์ได้จากมุมต่างๆ
Good คุณภาพของจุดฟีเจอร์ที่ระบุจากท่าทางในช่วง 2-3 วินาทีก่อนหน้านี้น่าจะเพียงพอให้ ARCore แก้ไข Cloud Anchor ได้สำเร็จด้วยความแม่นยำสูง

แก้ปัญหาโฆษณา Anchor ที่โฮสต์ก่อนหน้านี้

เรียกใช้ ARAnchorManagerExtensions.ResolveCloudAnchorAsync() เพื่อแก้ไข Cloud Anchor ที่โฮสต์ ARCore API จะเปรียบเทียบฟีเจอร์ภาพจากฉากกับแผนที่ฟีเจอร์ 3 มิติของ Anchor เป็นระยะๆ เพื่อระบุตำแหน่งและการวางแนวของผู้ใช้เทียบกับแท็ก Anchor เมื่อพบข้อมูลที่ตรงกัน API จะแสดงท่าทางของ Cloud Anchor ที่โฮสต์

คุณเริ่มการแก้ไขสำหรับ Cloud Anchor หลายรายการตามลำดับได้ มีการดำเนินการ Cloud Anchor พร้อมกันได้สูงสุด 40 รายการพร้อมกัน

ยกเลิกการดำเนินการหรือนำ Cloud Anchor ออก

ระบบจะเรียก ARCloudAnchor.OnDestroy() โดยอัตโนมัติเมื่อมีการนำคอมโพเนนต์ ARCloudAnchor ออกจากออบเจ็กต์เกมที่มีคอมโพเนนต์ดังกล่าว การดำเนินการนี้จะปลดออกและปล่อยออบเจ็กต์ Cloud Anchor พื้นฐานที่อยู่เบื้องหลัง

ตรวจสอบสถานะผลลัพธ์ของการดำเนินการ Cloud Anchor

ใช้ CloudAnchorState เพื่อตรวจสอบสถานะผลลัพธ์ของโฮสติ้งหรือการดำเนินการแก้ไข รวมถึงข้อผิดพลาด

ค่า คำอธิบาย
ErrorResolvingCloudIdNotFound แก้ไขไม่สำเร็จเนื่องจาก ARCore API ไม่พบรหัส Cloud Anchor ที่ระบุ
ErrorHostingDatasetProcessingFailed การโฮสต์ล้มเหลวเนื่องจากเซิร์ฟเวอร์ประมวลผลชุดข้อมูลสำหรับ Anchor ที่ระบุไม่สำเร็จ โปรดลองอีกครั้งหลังจากที่อุปกรณ์รวบรวมข้อมูลเพิ่มเติมจากสภาพแวดล้อมแล้ว
ErrorHostingServiceUnavailable เข้าถึง ARCore API ไม่ได้ ซึ่งอาจเกิดขึ้นได้จากสาเหตุหลายประการ อุปกรณ์อาจอยู่ในโหมดบนเครื่องบินหรืออาจไม่มีการเชื่อมต่ออินเทอร์เน็ตที่ใช้งานได้ คำขอที่ส่งไปยังเซิร์ฟเวอร์อาจหมดเวลาโดยไม่มีการตอบกลับ การเชื่อมต่อเครือข่ายอาจมีปัญหา, DNS ไม่พร้อมใช้งาน, ปัญหาเกี่ยวกับไฟร์วอลล์ หรือปัญหาอื่นที่ส่งผลต่อความสามารถของอุปกรณ์ในการเชื่อมต่อกับ ARCore API
ErrorInternal งานโฮสติ้งหรือแก้ปัญหาสำหรับแท็ก Anchor นี้ดำเนินการเสร็จแล้วและมีข้อผิดพลาดภายใน แอปไม่ควรพยายามกู้คืนจากข้อผิดพลาดนี้
ErrorNotAuthorized แอปสื่อสารกับ ARCore API ไม่ได้เนื่องจากการให้สิทธิ์ไม่ถูกต้อง ตรวจสอบการตั้งค่าโปรเจ็กต์ > XR > ส่วนขยาย ARCore เพื่อดูกลยุทธ์การให้สิทธิ์ที่ถูกต้อง
ErrorResolvingPackageTooNew แก้ไข Cloud Anchor ไม่ได้เนื่องจากแพ็กเกจ ARCore Extensions ที่ใช้เพื่อแก้ไข Cloud Anchor ใหม่กว่าและเข้ากันไม่ได้กับเวอร์ชันที่ใช้โฮสต์
ErrorResolvingPackageTooOld แก้ไข Cloud Anchor ไม่ได้เนื่องจากแพ็กเกจ ARCore Extensions ที่ใช้แก้ไข Cloud Anchor นั้นเก่ากว่าเวอร์ชันที่ใช้โฮสต์และใช้งานร่วมกันไม่ได้
ErrorResourceExhausted แอปพลิเคชันใช้โควต้าคำขอที่จัดสรรให้กับโปรเจ็กต์ Google Cloud ที่ระบุหมดแล้ว คุณควรขอโควต้าเพิ่ม ARCore API สำหรับโปรเจ็กต์จาก Google Developers Console
Success งานโฮสติ้งหรือแก้ปัญหาสำหรับแท็ก Anchor นี้เสร็จสมบูรณ์แล้ว

โควต้า API สำหรับคำขอโฮสต์และคำขอแก้ไขปัญหา

ARCore API มีโควต้าต่อไปนี้สำหรับแบนด์วิดท์คำขอ

ประเภทโควต้า สูงสุด ระยะเวลา ใช้กับ
จำนวนหมุด ไม่จำกัด ไม่มีข้อมูล โปรเจ็กต์
คำขอโฮสต์ Anchor 30 นาที ที่อยู่ IP และโปรเจ็กต์
คำขอ Anchor resolve 300 นาที ที่อยู่ IP และโปรเจ็กต์

แนวทางปฏิบัติแนะนำเพื่อให้ผู้ใช้ได้รับประสบการณ์ที่ดี

แจ้งให้ผู้ใช้ทำตามขั้นตอนต่อไปนี้เพื่อให้ผู้ใช้ได้รับประสบการณ์การใช้งานที่ดีในแอป

  • รอ 2-3 วินาทีหลังจากที่เซสชันเริ่มต้นก่อนที่จะพยายามโฮสต์ Anchor (ด้วยการวางออบเจ็กต์ เป็นต้น) การดำเนินการนี้ให้เวลาการติดตามเสถียรสักระยะ
  • เมื่อเลือกสถานที่ที่จะโฮสต์แท็ก Anchor ให้พยายามหาพื้นที่ที่มีคุณลักษณะทางภาพซึ่งแยกความแตกต่างจากกันได้โดยง่าย เพื่อผลลัพธ์ที่ดีที่สุด โปรดหลีกเลี่ยงพื้นผิวสะท้อนแสงหรือพื้นผิวที่ขาดคุณสมบัติที่มองเห็นได้ เช่น ผนังสีขาวว่างเปล่า

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

  • โปรดตรวจสอบว่ามีแสงสว่างเพียงพอในสภาพแวดล้อมจริงขณะโฮสต์และแก้ไข Cloud Anchor

นโยบายการเลิกใช้งาน

  • แอปที่สร้างด้วย ARCore SDK 1.12.0 ขึ้นไปจะอยู่ภายใต้นโยบายการเลิกใช้งาน Cloud Anchor API
  • แอปที่สร้างด้วย ARCore SDK 1.11.0 หรือต่ำกว่าจะไม่สามารถโฮสต์หรือแก้ปัญหา Cloud Anchor ได้เนื่องจาก SDK ใช้ ARCore API เวอร์ชันเก่าที่เลิกใช้งานแล้ว

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