旧版 ARCore Cloud Anchor API 云端端点已弃用，2023 年 8 月 31 日之后将不再受支持。如果您的应用正在使用此 API，您必须尽快更新它，以使用新的 ARCore API 云端端点。

此页面由 Cloud Translation API 翻译。

Unity（AR 基础）云锚点开发者指南

了解如何在您自己的应用中使用云锚点。

前提条件

确保您了解 AR 基础概念以及如何在继续之前配置 ARCore 现场录像。

如果您刚开始接触云锚点，请务必了解锚点和云锚点的工作原理。

在您的应用中使用云锚点之前，您必须先在应用中启用 ARCore API。

在您的应用中启用云锚点功能后，在应用的 AR 会话配置中启用云锚点功能，以便它可以与 ARCore API 通信：

Hosting 始于对 ARAnchorManager.HostCloudAnchorAsync() 的调用。ARCore 会将视觉数据、设备位置方向和锚点位置方向上传到 ARCore API。然后，API 会处理此信息以构建 3D 特征图，最终向设备返回锚点的唯一云锚点 ID。

您还可以使用 ARCore Cloud Anchor Management API 延长托管锚点的生命周期。

您的应用应按照以下步骤完成云锚点的托管：

调用 ARAnchorManager.HostCloudAnchorAsync()。
启动协程以等待 Promise 生成结果。如需了解详情，请参阅 Unity 中的协程。
检查结果状态以确定操作是否成功，或者在操作失败时解释错误代码。
与其他客户端共享结果云锚点 ID，并使用该 ID 通过 ARAnchorManagerExtensions.ResolveCloudAnchorAsync()。

ARCoreExtensions.FeatureMapQuality 表示 ARCore 在前几秒内从给定相机位置方向观察到的特征点的质量。使用更高质量的功能托管的云锚点通常可以更准确地解析。使用 ARAnchorManagerExtensions.EstimateFeatureMapQualityForHosting() 获取给定相机位置方向的特征图质量估算值。

值	说明
`Insufficient`	前几秒内根据姿势识别的特征点质量较差。此状态表示 ARCore 可能更难解析云锚点。鼓励用户移动设备，以便从不同的角度查看他们希望托管的云锚点的所需位置。
`Sufficient`	虽然已解析的姿势的准确性可能会降低，但前几秒内从位置方向识别到的特征点的质量或许足以让 ARCore 成功解析云锚点。鼓励用户移动设备，以便从不同的角度查看他们希望托管的云锚点的所需位置。
`Good`	之前几秒内根据姿势识别的特征点的质量可能足以让 ARCore 以高准确度成功解析云锚点。

调用 ARAnchorManagerExtensions.ResolveCloudAnchorAsync() 以解析托管的云锚点。ARCore API 会定期将场景中的视觉特征与锚点的 3D 特征图进行比较，以精确定位用户相对于锚点的位置和方向。找到匹配项后，API 会返回托管云锚点的姿态。

您可以按顺序启动多个云锚点的解析。一次最多可以有 40 个并发云锚点操作。

当从包含 ARCloudAnchor 组件的游戏对象中移除该组件时，系统会自动调用 ARCloudAnchor.OnDestroy()。这将分离并释放底层原生云锚点对象。

使用 CloudAnchorState 检查托管或解析操作的结果状态，包括错误。

值	说明
`ErrorResolvingCloudIdNotFound`	解析失败，因为 ARCore API 找不到提供的云锚点 ID。
`ErrorHostingDatasetProcessingFailed`	由于服务器无法成功处理给定锚点的数据集，托管失败。请在设备从环境中收集更多数据后重试。
`ErrorHostingServiceUnavailable`	无法访问 ARCore API。可能造成这种情况的原因有很多。设备可能处于飞行模式或未连接到互联网。发送到服务器的请求可能已超时，且无响应。可能是网络连接状况不佳、DNS 不可用、防火墙问题，或有其他可能影响设备连接 ARCore API 的因素。
`ErrorInternal`	此锚点的托管或解析任务已完成，但发生了内部错误。应用不应尝试从此错误中恢复。
`ErrorNotAuthorized`	由于无效授权，应用无法与 ARCore API 通信。检查项目设置 >XR >ARCore 扩展以获取有效的授权策略。
`ErrorResolvingPackageTooNew`	无法解析云锚点，因为用于解析云锚点的 ARCore 扩展软件包比用于托管云锚点的版本更新且不兼容。
`ErrorResolvingPackageTooOld`	无法解析云锚点，因为用于解析云锚点的 ARCore 扩展软件包比用于托管云锚点的版本更低且不兼容。
`ErrorResourceExhausted`	应用已用尽分配给指定 Google Cloud 项目的请求配额。您应该从 Google Developers Console 为您的项目申请更多 ARCore API 配额。
`Success`	已成功完成此锚点的托管或解析任务。

ARCore API 以下请求带宽配额：

请指导用户执行以下操作，以确保应用提供良好的用户体验：

在会话开始后等待几秒钟，然后再尝试托管锚点（通过放置对象等）。这可让跟踪有一段时间稳定下来。
选择托管锚点的位置时，请尝试查找具有视觉特征且彼此易于区分的区域。为了获得最佳效果，请避免使用反光表面或没有视觉特征的表面，如空白的白色墙壁。
让相机始终对准感兴趣的中心，并四处移动设备以便从不同的角度绘制环境地图，同时保持大致相同的物理距离。这将有助于捕获更多可视化数据，使解析更加可靠。

注意：围绕关注点移动与原地站立并旋转不同，就像其他人在拍摄全景照片时可能会做的那样。用户应在环境中的实际移动。
托管和解析云锚点时，请确保现实环境中有足够的光照。