瞭解如何在自己的應用程式中使用 Cloud Anchors。
必要條件
請務必先瞭解基本 AR 概念，以及如何設定 ARCore 工作階段，再繼續操作。
如果您是第一次使用 Cloud Anchors，請務必瞭解錨點和 Cloud Anchors 的運作方式。
啟用 ARCore API
在應用程式中使用 Cloud Anchors 前，您必須先在應用程式中啟用 ARCore API。
在工作階段設定中啟用 Cloud Anchor 功能
在應用程式中啟用 Cloud Anchors 功能後，請在應用程式的 AR 工作階段設定中啟用 Cloud Anchors 功能，以便與 ARCore API 通訊：
代管 Cloud Anchor
開始時，只要呼叫 ARAnchorManager.HostCloudAnchorAsync() 即可。ARCore 會將視覺資料、裝置姿勢和錨點姿勢上傳到 ARCore API。接著，API 會處理這項資訊來建構 3D 地圖，最後傳回錨點的專屬 Cloud Anchor ID 給裝置。
您也可以使用 ARCore Cloud Anchor Management API 延長代管錨點的生命週期。
應用程式應按照下列步驟完成 Cloud Anchor 的託管：
- 呼叫
ARAnchorManager.HostCloudAnchorAsync()。 - 啟動協同程式，等待 Promise 產生結果。詳情請參閱「Unity 中的協同程式」。
- 您可以查看結果狀態來判斷作業是否成功，若失敗則解釋錯誤代碼。
- 將結果 Cloud Anchor ID 提供給其他用戶端，並使用該 ID 透過
ARAnchorManagerExtensions.ResolveCloudAnchorAsync()解析 Cloud Anchor。
檢查地圖資料點的對應品質
ARCoreExtensions.FeatureMapQuality 代表 ARCore 在特定相機姿勢中，前幾秒內看到的特徵點品質。使用較高品質特徵託管的 Cloud Anchor 通常較能得到正確的解析。使用 ARAnchorManagerExtensions.EstimateFeatureMapQualityForHosting() 估算特定相機姿勢的特徵圖品質。
| 值 | 說明 |
|---|---|
Insufficient |
在前幾秒根據姿勢識別特徵點的品質偏低。這個狀態表示 ARCore 可能會更難解析 Cloud Anchor。鼓勵使用者移動裝置，以便從不同角度查看要放置的 Cloud Anchor 所需位置。 |
Sufficient |
在前幾秒內從姿勢辨識出來的特徵點品質，可能已足以讓 ARCore 成功解析雲端錨點，但解析姿勢的準確度可能會降低。鼓勵使用者移動裝置，以便從不同角度查看要放置的 Cloud Anchor 所需位置。 |
Good |
ARCore 能在前幾秒根據姿勢辨識出特徵點的品質，可能足以讓 ARCore 成功解析出高度準確度的 Cloud Anchor。 |
解析先前代管的錨點
呼叫 ARAnchorManagerExtensions.ResolveCloudAnchorAsync() 解析代管的 Cloud Anchor。ARCore API 會定期將場景中的視覺特徵與錨點的 3D 特徵地圖進行比對，以便精確定位使用者相對於錨點的位置和方向。如果找到相符項目，API 會傳回代管 Cloud Anchor 的姿勢。
您可以依序啟動多個 Cloud Anchor 的解析作業。最多可同時執行 40 個 Cloud Anchor 作業。
取消作業或移除 Cloud Anchor
從包含 ARCloudAnchor 的遊戲物件移除 ARCloudAnchor 元件時，系統會自動呼叫 ARCloudAnchor.OnDestroy()。這會卸離並釋放底層的原生 Cloud Anchor 物件。
查看 Cloud Anchor 作業的結果狀態
使用 CloudAnchorState 檢查代管或解析作業的結果狀態，包括錯誤。
| 值 | 說明 |
|---|---|
ErrorResolvingCloudIdNotFound |
ARCore API 找不到您提供的 Cloud Anchor ID，因此導致解決失敗。 |
ErrorHostingDatasetProcessingFailed |
主機服務失敗，因為伺服器無法成功處理指定錨點的資料集。等裝置從環境中收集到更多資料後，再試一次。 |
ErrorHostingServiceUnavailable |
無法存取 ARCore API。導致這個問題的原因可能不只一個。裝置可能處於飛航模式，或未連上網際網路。傳送至伺服器的要求可能已逾時，且未收到回應。可能有網路連線不良、DNS 無法使用、防火牆問題，或其他可能影響裝置連線至 ARCore API 的因素。 |
ErrorInternal |
這個錨點的代管或解析工作已完成，但發生內部錯誤。應用程式不應嘗試從此錯誤復原。 |
ErrorNotAuthorized |
由於授權無效，因此應用程式無法與 ARCore API 通訊。請依序前往「Project Settings」>「XR」XR >「ARCore Extensions」，查看是否有有效的授權策略。 |
ErrorResolvingPackageTooNew |
無法解析雲端錨點，因為用來解析雲端錨點的 ARCore 擴充功能套件版本較新，且與用來代管該錨點的版本不相容。 |
ErrorResolvingPackageTooOld |
無法解析 Cloud Anchor，因為用來解析 Cloud Anchor 的 ARCore 擴充功能套件的版本早於，與目前託管該映像檔的版本不相容。 |
ErrorResourceExhausted |
應用程式已用盡指定 Google Cloud 專案的請求配額。您應透過 Google Developers Console 為專案要求額外的 ARCore API 配額。 |
Success |
已成功完成這個錨點的代管或解析工作。 |
主機和解析要求的 API 配額
ARCore API 針對要求頻寬設有以下配額：
| 配額類型 | 上限 | 持續時間 | 套用對象 |
|---|---|---|---|
| 錨點數 | 無限制 | 不適用 | 專案 |
| 錨定主機要求 | 30 | 分鐘 | IP 位址與專案 |
| 錨定解析要求 | 300 | 分鐘 | IP 位址與專案 |
提供良好使用者體驗的最佳做法
請告知使用者如何在應用程式中獲得良好的使用者體驗：
- 工作階段開始後，請稍候幾秒鐘，然後再嘗試代管錨點 (例如放置物件等)。這可讓追蹤功能穩定下來。
- 選擇要放置錨點的位置時，請盡量選擇視覺特徵容易區分的區域。為獲得最佳成效，請避免使用會反光的表面，或沒有視覺特徵的表面，例如空白的白牆。
請讓相機對準感興趣的中心，並在該中心周圍移動裝置，以不同角度繪製環境地圖，並在移動時維持大致相同的實際距離。這麼做有助於擷取更多視覺資料，並強化解析能力。
請務必在主辦和解析雲端錨點時，確保實體環境有足夠的光線。
廢止政策
- 使用 ARCore SDK 1.12.0 以上版本建構的應用程式適用 Cloud Anchor API 廢止政策。
- 使用 ARCore SDK 1.11.0 以下版本建構的應用程式，由於 SDK 使用較舊的已淘汰 ARCore API，因此無法代管或解析 Cloud Anchor。
後續步驟
- 如要進一步瞭解如何在應用程式中使用 ARCore，請參閱 AR Foundation 參考資料的 ARCore 擴充功能。