Hướng dẫn cho nhà phát triển Cloud Anchors cho Unity (Nền tảng AR)

Tìm hiểu cách sử dụng Mốc trên đám mây trong ứng dụng của riêng bạn.

Điều kiện tiên quyết

Hãy đảm bảo rằng bạn hiểu các khái niệm cơ bản về AR và cách định cấu hình phiên ARCore trước khi tiếp tục.

Nếu bạn mới sử dụng Cloud Anchors, hãy đảm bảo rằng bạn hiểu rõ cách hoạt động của neo và Cloud Anchors.

Bật API ARCore

Trước khi sử dụng Cloud Anchors trong ứng dụng, trước tiên bạn phải bật ARCore API trong ứng dụng của mình.

Bật các chức năng Cloud Anchor định cấu hình phiên

Sau khi bật chức năng Điểm neo trên đám mây trong ứng dụng, hãy bật các chức năng Điểm neo trên đám mây trong cấu hình phiên AR của ứng dụng để ứng dụng có thể giao tiếp với API ARCore:

Lưu trữ neo trên đám mây

Quá trình lưu trữ bắt đầu bằng lệnh gọi đến ARAnchorManager.HostCloudAnchorAsync(). ARCore sẽ tải dữ liệu hình ảnh, tư thế thiết bị và tư thế neo lên API ARCore. Sau đó, API sẽ xử lý thông tin này để tạo bản đồ đặc điểm 3D, cuối cùng trả về một mã nhận dạng duy nhất của neo trên đám mây cho neo đến thiết bị.

Bạn cũng có thể kéo dài thời gian hoạt động của một neo được lưu trữ bằng cách sử dụng ARCore Cloud Anchor Management API.

Ứng dụng của bạn phải làm theo các bước sau để hoàn tất việc lưu trữ Cloud Anchor:

  1. Gọi ARAnchorManager.HostCloudAnchorAsync().
  2. Bắt đầu một coroutine để chờ cho đến khi Promise trả về kết quả. Hãy xem bài viết Coroutine trong Unity để biết thêm thông tin.
  3. Kiểm tra trạng thái kết quả để xác định xem thao tác có thành công hay không hoặc diễn giải mã lỗi nếu thao tác không thành công.
  4. Chia sẻ mã Cloud Anchor kết quả với các ứng dụng khác và dùng mã đó để phân giải Cloud Anchor bằng ARAnchorManagerExtensions.ResolveCloudAnchorAsync().

Kiểm tra chất lượng lập bản đồ của các điểm đối tượng

ARCoreExtensions.FeatureMapQuality cho biết chất lượng của các điểm đặc trưng mà ARCore nhìn thấy trong vài giây trước đó từ một tư thế máy ảnh nhất định. Các Điểm neo trên đám mây được lưu trữ bằng các tính năng chất lượng cao hơn thường được phân giải chính xác hơn. Sử dụng ARAnchorManagerExtensions.EstimateFeatureMapQualityForHosting() để ước tính chất lượng bản đồ của tính năng cho một tư thế camera nhất định.

Giá trị Mô tả
Insufficient Chất lượng của các điểm đặc trưng được xác định từ tư thế trong vài giây trước đó là thấp. Trạng thái này cho biết rằng ARCore có thể sẽ gặp khó khăn hơn khi phân giải Cloud Anchor. Khuyến khích người dùng di chuyển thiết bị để có thể xem vị trí mong muốn của Điểm neo trên đám mây mà họ muốn lưu trữ từ nhiều góc độ.
Sufficient Chất lượng của các điểm đặc trưng được xác định từ tư thế trong vài giây trước đó có thể đủ để ARCore phân giải thành công một Điểm neo trên đám mây, mặc dù độ chính xác của tư thế được phân giải có thể giảm. Khuyến khích người dùng di chuyển thiết bị để có thể xem vị trí mong muốn của Điểm neo trên đám mây mà họ muốn lưu trữ từ nhiều góc độ.
Good Chất lượng của các điểm đặc trưng được xác định từ tư thế trong vài giây trước đó có thể đủ để ARCore phân giải thành công một Điểm neo trên đám mây với độ chính xác cao.

Giải quyết một liên kết được lưu trữ trước đó

Gọi ARAnchorManagerExtensions.ResolveCloudAnchorAsync() để phân giải một Điểm neo trên đám mây được lưu trữ. API ARCore định kỳ so sánh các đặc điểm hình ảnh từ cảnh với bản đồ đặc điểm 3D của điểm neo để xác định chính xác vị trí và hướng của người dùng so với điểm neo. Khi tìm thấy kết quả trùng khớp, API sẽ trả về tư thế của Điểm neo trên đám mây được lưu trữ.

Bạn có thể bắt đầu phân giải cho nhiều Điểm neo trên đám mây theo trình tự. Có thể tồn tại tối đa 40 hoạt động Cloud Anchor đồng thời cùng một lúc.

Huỷ thao tác hoặc xoá một Điểm neo trên đám mây

ARCloudAnchor.OnDestroy() được tự động gọi khi thành phần ARCloudAnchor bị xoá khỏi đối tượng trò chơi chứa thành phần đó. Thao tác này sẽ tách và giải phóng đối tượng Cloud Anchor gốc cơ bản.

Kiểm tra trạng thái kết quả của thao tác liên kết trên đám mây

Sử dụng CloudAnchorState để kiểm tra trạng thái kết quả của thao tác lưu trữ hoặc phân giải, bao gồm cả lỗi.

Giá trị Mô tả
ErrorResolvingCloudIdNotFound Không thể phân giải vì API ARCore không tìm thấy mã neo trên đám mây đã cung cấp.
ErrorHostingDatasetProcessingFailed Không lưu trữ được do máy chủ không thể xử lý thành công tập dữ liệu cho neo đã cho. Hãy thử lại sau khi thiết bị thu thập thêm dữ liệu từ môi trường.
ErrorHostingServiceUnavailable Không thể truy cập API ARCore. Lỗi này có thể xảy ra do một số lý do. Thiết bị có thể đang ở chế độ trên máy bay hoặc không có kết nối Internet. Yêu cầu được gửi đến máy chủ có thể đã hết thời gian chờ mà không có phản hồi. Có thể có kết nối mạng kém, DNS không hoạt động, sự cố tường lửa hoặc bất kỳ vấn đề nào khác có thể ảnh hưởng đến khả năng kết nối của thiết bị với API ARCore.
ErrorInternal Một tác vụ lưu trữ hoặc phân giải cho liên kết này đã hoàn tất với lỗi nội bộ. Ứng dụng không được tìm cách khôi phục lỗi này.
ErrorNotAuthorized Ứng dụng không thể giao tiếp với API ARCore do không được cấp quyền hợp lệ. Hãy kiểm tra phần Cài đặt dự án > XR > Tiện ích ARCore để biết chiến lược uỷ quyền hợp lệ.
ErrorResolvingPackageTooNew Không thể phân giải Cloud Anchor vì gói Tiện ích ARCore dùng để phân giải Cloud Anchor này là phiên bản mới hơn và không tương thích với phiên bản đang dùng để lưu trữ.
ErrorResolvingPackageTooOld Không thể phân giải Cloud Anchor vì gói Tiện ích ARCore dùng để phân giải Cloud Anchor cũ hơn và không tương thích với phiên bản đang dùng để lưu trữ Cloud Anchor.
ErrorResourceExhausted Ứng dụng đã dùng hết hạn mức yêu cầu được phân bổ cho dự án Google Cloud cụ thể. Bạn nên yêu cầu thêm hạn mức cho API ARCore cho dự án của mình trong Google Developers Console.
Success Đã hoàn tất thành công một tác vụ lưu trữ hoặc giải quyết cho quảng cáo cố định này.

Hạn mức API đối với các yêu cầu lưu trữ và giải quyết

API ARCore có các hạn mức sau đây đối với băng thông yêu cầu:

Loại hạn mức Tối đa Thời lượng Áp dụng cho
Số lượng neo không giới hạn Không áp dụng dự án
Yêu cầu máy chủ cố định 30 phút Địa chỉ IP và dự án
Yêu cầu giải quyết liên kết cố định 300 phút Địa chỉ IP và dự án

Các phương pháp hay nhất để mang lại trải nghiệm tốt cho người dùng

Hướng dẫn người dùng thực hiện những việc sau để đảm bảo trải nghiệm người dùng tốt trên ứng dụng của bạn:

  • Chờ vài giây sau khi phiên bắt đầu trước khi cố gắng lưu trữ một neo (bằng cách đặt một đối tượng, v.v.). Điều này giúp quá trình theo dõi có thời gian ổn định.
  • Khi chọn vị trí để lưu trữ điểm neo, hãy cố gắng tìm một khu vực có các đặc điểm hình ảnh dễ phân biệt với nhau. Để có kết quả tốt nhất, hãy tránh những bề mặt phản chiếu hoặc bề mặt thiếu đặc điểm hình ảnh, chẳng hạn như tường trắng trống.

  • Giữ cho máy ảnh ở giữa tâm điểm quan tâm và di chuyển thiết bị xung quanh trung tâm quan tâm để ánh xạ môi trường từ nhiều góc độ, duy trì khoảng cách vật lý gần như tương tự như khi bạn làm vậy. Điều này sẽ giúp thu thập nhiều dữ liệu hình ảnh hơn và giúp quá trình phân giải trở nên hiệu quả hơn.

  • Đảm bảo có đủ ánh sáng trong môi trường thực tế trong khi lưu trữ và phân giải Điểm neo trên đám mây.

Chính sách về việc ngừng cung cấp

  • Các ứng dụng được xây dựng bằng ARCore SDK 1.12.0 trở lên phải tuân thủ Chính sách về việc ngừng sử dụng Cloud Anchor API.
  • Các ứng dụng được xây dựng bằng ARCore SDK 1.11.0 trở xuống không thể lưu trữ hoặc phân giải Cloud Anchors do SDK sử dụng một API ARCore cũ hơn và không còn dùng nữa.

Bước tiếp theo