瞭解如何在自己的應用程式中使用 Cloud Anchor。
必要條件
請務必先瞭解基本 AR 概念，以及如何設定 ARCore 工作階段，然後再繼續操作。
如果您是第一次使用 Cloud Anchor，請務必瞭解錨點和 Cloud Anchors 的運作方式。
啟用 ARCore API
您必須先在新的或現有的 Google Cloud Platform 專案中啟用 ARCore API，才能在應用程式中使用 Cloud Anchor。這項服務會負責託管、儲存及解析 Cloud Anchor。
授權應用程式呼叫 ARCore API
您必須授權應用程式呼叫 ARCore API，以代管並解析 Cloud Anchor。如果應用程式代管及解析 Cloud 錨定時間超過 1 天的期限，則必須使用權杖 (已簽署的 JWT) 授權。
權杖 (已簽署 JWT) 授權
使用權杖 (已簽署 JWT) 授權來託管及解析具有存留時間 (1 至 365 天) 的 Cloud 錨點。目前，系統僅支援已簽署的 JSON Web Token (JWT)。這個權杖必須由 Google 服務帳戶簽署。
依序前往「編輯」 >「專案設定」 >「XR 外掛程式管理」 >「ARCore 擴充功能」，然後勾選「已啟用 iOS 支援」。
從「iOS 驗證策略」下拉式選單中，選取「驗證權杖」選項。
伺服器端點需求
如要產生 iOS 權杖，您的伺服器上必須有符合下列條件的端點：
- 您自己的授權機制可以保護端點。
- 端點每次都必須產生新的權杖，讓每位使用者都能取得專屬權杖，且權杖不會立即過期。
建立服務帳戶和簽署金鑰
請按照下列步驟建立 Google 服務帳戶和簽署金鑰。
- 在 Google Cloud Platform Console 的導覽選單中，依序前往「APIs & Services」(API 和服務) >「Credentials」(憑證)。
- 選取所需專案，然後依序點選「建立憑證」 >「服務帳戶」。
- 在「服務帳戶詳細資料」下方輸入新帳戶的名稱，然後按一下「建立」。
- 在「服務帳戶權限」頁面中，前往「請選擇角色」下拉式選單。依序選取「服務帳戶」 >「服務帳戶憑證建立者」，然後按一下「繼續」。
- 在「將這個服務帳戶的存取權授予使用者」頁面中，點選「完成」。系統會將您導向「API 和服務」>「憑證」。
- 在「憑證」頁面中，向下捲動至「服務帳戶」部分，然後按一下您剛建立的帳戶名稱。
- 在「服務帳戶詳細資料」頁面中，向下捲動至「金鑰」部分，然後選取「新增金鑰」 >「建立新的金鑰」。
- 選取「JSON」做為金鑰類型，然後按一下「建立」。即可將包含私密金鑰的 JSON 檔案下載至您的電腦。將下載的 JSON 金鑰檔案儲存在安全的位置。
JSON 檔案含有不得對外公開的私密金鑰。請勿將其提交至 GitHub 等原始碼存放區。
在伺服器上建立權杖
如要在伺服器上建立新的權杖 (JWT)，請使用標準 JWT 程式庫和透過新服務帳戶安全下載的 JSON 檔案。
在開發機器上建立權杖
如要在開發機器上產生 JWT，請使用下列 oauth2l 指令：
// "oauth2l" uses a lowercase L, not a 1, as the last character.
// Specifying an empty cache location using the --cache flag is necessary
// to ensure that a different token is produced each time.
oauth2l fetch --cache "" --jwt --json $KEYFILE --audience "https://arcore.googleapis.com/"
請務必修剪產生的字串。多餘的空格或換行字元會導致 API 拒絕符記。
簽署權杖
如要簽署 JWT，請使用 RS256 演算法和下列憑證附加資訊：
iss：服務帳戶電子郵件地址。sub：服務帳戶電子郵件地址。iat：產生權杖的 Unix 時間 (以秒為單位)。exp-iat+3600(1 小時)。權杖的 Unix 時間 (以秒為單位)。aud- 目標對象。必須設為https://arcore.googleapis.com/。
非標準憑證附加資訊不需要在 JWT 酬載中使用，不過您可能會發現 uid 憑證附加資訊有助於識別對應的使用者。
如果您使用其他方法產生 JWT，例如在 Google 管理的環境中使用 Google API，請務必使用本節中的憑證附加資訊簽署 JWT。最重要的是，請確認目標對象正確無誤。
將權杖傳遞至 ARCore 工作階段
取得權杖後，請使用 ARAnchorManager.SetAuthToken() 將權杖傳遞至 ARCore 工作階段：
// Designate the token to use when authorizing with the ARCore API
// on the iOS platform. The API should be called each time the application's token is refreshed.
ARAnchorManager.SetAuthToken(string authToken);
將權杖傳入工作階段時，請注意下列事項：
- 您必須傳入有效的授權權杖，才能代管或解析錨點。
- ARCore 會忽略含有空格或特殊字元的授權權杖。
- 如果工作階段是以有效的 API 金鑰建立，ARCore 會忽略提供的授權權杖。如果您先前已使用 API 金鑰，但不再需要該金鑰，建議您前往 Google Cloud Platform Console 刪除該金鑰，並在將使用者遷移至最新版本後從應用程式中移除。
- 權杖通常會在一小時後失效。如果權杖在使用時可能會過期，請取得新權杖並使用新的權杖呼叫
ARAnchorManager.SetAuthToken(string authToken)。
API 金鑰授權
使用 API 金鑰授權來託管及解析具有存留時間的 Cloud 錨點，上限為 24 小時 (1 天)。
使用 ARCore SDK 1.24.0 以上版本建構的新 Unity 專案預設授權策略為 DoNotUse。這是為了防止使用不必要的程式庫建構應用程式。如果您的應用程式使用 Cloud Anchor，且使用 ARCore SDK 1.24.0 以上版本建構，您必須依序前往「Project Settings」 >「XR Plug-in Management」 >「ARCore Extensions」手動啟用授權。
依序前往「編輯」 >「專案設定」 >「XR 外掛程式管理」 >「ARCore 擴充功能」，然後勾選「已啟用 iOS 支援」。
在「iOS 驗證策略」下拉式選單中，選取「API 金鑰」選項。
您可以透過 Google Cloud 控制台為這項專案取得 API 金鑰。
依序前往「Edit」 >「Project Settings」 >「XR Plug-in Management」 >「ARCore Extensions」，然後將 API 金鑰新增至「Cloud Anchor API Keys」欄位。
在應用程式中啟用 Cloud Anchors 功能
授權應用程式呼叫 ARCore API 後，您必須在應用程式中啟用 Cloud Anchors 功能。
- 依序前往 [Edit] (編輯) > [Project Settings] (專案設定) > [XR Plug-In Management] (XR 外掛程式管理) > [ARCore Extensions] (ARCore 擴充功能)。確認已選取「已啟用 iOS 支援」。
- 在「Optional Features」下方選取「Cloud Anchors」。
在工作階段設定中啟用 Cloud Anchor 功能
一旦在應用程式中啟用 Cloud Anchors 功能，請在應用程式的 AR 工作階段設定中啟用 Cloud Anchors 功能，讓應用程式與 ARCore API 通訊：
- 確認專案 Assets 資料夾中包含 ARCoreExtensionsConfig 可指令碼物件。如要建立版本，請在「Assets」窗格中按一下滑鼠右鍵，然後依序選取「Create」 >「XR」 >「ARCore Extensions Config」。
在「Assets」ARCoreExtensionsConfig資料夾中選取「ARCoreExtensionsConfig」ARCoreExtensionsConfig可指令碼物件，然後將「Cloud Anchor Mode」ARCoreExtensionsConfig設為「Enabled」ARCoreExtensionsConfig。
將 ARCore Extensions 遊戲物件設為使用 ARCoreExtensionsConfig 設定。在「Hierarchy」窗格中，找出您最初設定 ARCore Extensions 時建立的 ARCore Extensions 遊戲物件，然後將「ARCore Extensions Config」欄位連結到「Assets」資料夾中的「ARCoreExtensionsConfig」可編碼物件。
託管雲端錨點
「託管」程序首先會呼叫 ARAnchorManager.HostCloudAnchorAsync()。ARCore 會將視覺化資料、裝置姿勢和錨點姿勢上傳至 ARCore API，接著，API 會處理這些資訊來建構 3D 功能對應，最後將不重複的 Cloud Anchor ID 傳回至裝置。
您也可以使用 ARCore Cloud Anchor Management API 延長代管錨點的生命週期。
您的應用程式應執行下列步驟，完成 Cloud Anchor 的託管作業：
- 呼叫
ARAnchorManager.HostCloudAnchorAsync()。 - 啟動協同程式，直到 Promise 產生結果為止。詳情請參閱「Unity 中的協同程式」一文。
- 檢查結果狀態來判斷作業是否成功，失敗時則是解讀錯誤代碼。
- 與其他用戶端分享 Cloud Anchor ID 結果，並使用
ARAnchorManagerExtensions.ResolveCloudAnchorAsync()解析 Cloud Anchor。
確認地圖項目點的對應品質
ARCoreExtensions.FeatureMapQuality 表示 ARCore 在從特定相機姿勢中偵測到的特徵點品質。使用品質較高的功能託管的 Cloud Anchor 通常可更準確地解析。使用 ARAnchorManagerExtensions.EstimateFeatureMapQualityForHosting() 取得特定相機姿勢的地圖項目地圖品質預估值。
| 值 | 說明 |
|---|---|
Insufficient |
在過去幾秒內，根據姿勢發現的特徵點品質偏低。這個狀態表示 ARCore 可能較難解析 Cloud Anchor。建議使用者移動裝置，以便從不同角度查看想託管的 Cloud Anchor 位置。 |
Sufficient |
前幾秒的姿勢發現的特徵點品質足以讓 ARCore 成功解析 Cloud Anchor，不過解決姿勢的準確度可能會降低。建議使用者移動裝置，以便從不同角度查看想託管的 Cloud Anchor 位置。 |
Good |
前幾秒的姿勢發現的特徵點品質足以讓 ARCore 成功解析具有高準確度的 Cloud Anchor。 |
解析先前代管的錨定標記
呼叫 ARAnchorManagerExtensions.ResolveCloudAnchorAsync() 即可解析託管的 Cloud Anchor。ARCore API 會定期比較場景中的視覺地圖項目與錨點的 3D 功能地圖，以找出使用者相對於錨點的位置和方向。找到相符項目時，API 會傳回託管 Cloud Anchor 的姿勢。
您可以依序啟動多個 Cloud 錨點的解析作業。一次最多可同時存在 40 個 Cloud Anchor 作業。
取消作業或移除 Cloud Anchor
ARCloudAnchor.OnDestroy() 從包含此元件的遊戲物件中移除時，系統會自動呼叫 ARCloudAnchor 元件。這項操作會卸離並釋出基礎的原生 Cloud Anchor 物件。
檢查 Cloud Anchor 作業的結果狀態
使用 CloudAnchorState 查看託管或解析作業的結果狀態，包括錯誤。
主機和解析要求的 API 配額
ARCore API 要求頻寬的配額如下：
| 配額類型 | 上限 | 時間長度 | 套用對象 |
|---|---|---|---|
| 錨點數量 | 無限制 | 不適用 | 專案 |
| 錨定 host 要求 | 30 | 分鐘 | IP 位址和專案 |
| 錨定resolve要求 | 300 | 分鐘 | IP 位址和專案 |
確保良好使用者體驗的最佳做法
請引導使用者執行下列操作，確保應用程式提供良好的使用者體驗：
- 在工作階段開始後稍候幾秒鐘，再嘗試代管錨點 (透過放置物件等)。如此才有時間穩定追蹤。
- 選取代管錨點的位置時，請盡量找出視覺特徵之間容易區別的區域。為獲得最佳效果，請避免使用缺少視覺特徵的反光錶面或表面，例如白色牆壁。
將攝影機保持在所需中心點，然後移動裝置中心點，從不同角度繪製環境地圖，保持大致相同的實際距離。這有助於擷取更豐富的圖像資料，並更完善地解析。
託管並解決 Cloud Anchor 時，請確保在現實環境中有足夠的光線。
廢止政策
- 使用 ARCore SDK 1.12.0 以上版本建構的應用程式適用 Cloud Anchor API 淘汰政策。
- 使用 ARCore SDK 1.11.0 以下版本建構的應用程式無法代管或解析 Cloud Anchor，原因是 SDK 使用了已淘汰的舊版 ARCore API。
後續步驟
- 如要進一步瞭解如何在應用程式中使用 ARCore，請參閱 ARCore 擴充功能參考資料說明文件。