适用于 Android 的云锚点快速入门
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
尝试在 cloud_anchor_java 和 persistent_cloud_anchor_java 示例应用中托管和解析云锚点。
您应使用哪个示例应用？
云锚点是指托管在 ARCore API 云端端点上的锚点。借助此 API，用户可以在同一应用中分享体验。永久性云锚点是指可以托管超过 24 小时的云锚点。
persistent_cloud_anchor_java 是协作项目用例的一种实现。它使用无密钥授权来授权 ARCore API 调用。由于它不使用 Firebase 后端在设备之间共享云锚点 ID，因此启动和运行起来要容易得多。cloud_anchor_java 是多人游戏用例的实现。它使用 API 密钥来授权 ARCore API 调用。
前提条件
要求
硬件
软件
- Android Studio 3.0 或更高版本，以及 Android SDK Platform 7.0（API 级别 24）或更高版本
- ARCore SDK for Android，您可以通过以下两种方式之一获得：
<ph type="x-smartling-placeholder">
</ph>
- 从 GitHub 下载该文件并将其解压缩到您的机器上
- 使用以下命令克隆代码库：
git clone https://github.com/google-ar/arcore-android-sdk.git
在 Android Studio 中打开示例应用
ARCore SDK 提供了 cloud_anchor_java 和 persistent_cloud_anchor_java 示例应用来演示云锚点功能。请按照以下步骤在 Android Studio 中打开应用。
持久云锚点
在 Android Studio 中，点击 Open。
前往计算机上 arcore-android-sdk 目录的存储位置。请勿打开整个 SDK 文件夹。请改为前往示例 >persistent_cloud_anchor_java，然后点击 Open。
云锚点
在 Android Studio 中，点击 Open。
前往计算机上 arcore-android-sdk 目录的存储位置。请勿打开整个 SDK 文件夹。请改为前往示例 >cloud_anchor_java 并点击打开。
设置云锚点 ID 共享
云锚点 ID 是用于标识托管的云锚点的字符串。它们用于解析或渲染连接到托管锚点的 3D 对象。
持久云锚点
云锚点 ID 共享是在应用中本地维护的。您在此处无需执行任何操作。
云锚点
cloud_anchor_java 示例应用使用 Firebase 的 Realtime Database 在设备之间共享云锚点 ID。您可以在自己的应用中使用不同的解决方案。
- 手动将 Firebase 添加到您的应用。
cloud_anchor_java 软件包名称为 com.google.ar.core.examples.java.cloudanchor。您可以在 main/AndroidManifest.xml 中找到它。
- 下载将 Firebase 添加到应用时生成的
google-services.json 文件。
- 使用 Firebase 创建 Realtime Database。
- 在 Android Studio 中，将
google-services.json 文件添加到项目的 app 目录中。
授权 ARCore API 调用
授权调用 ARCore API 来托管和解析您的
应用。按照在 Google 上使用 ARCore API 一文中的步骤操作
Cloud 和无密钥模式
授权，或使用 API 密钥授权
云锚点。
构建和运行示例应用
持久云锚点
运行应用
- 确保您的设备已启用开发者选项和 USB 调试。
- 通过 USB 将设备连接到开发机器。
- 在 Android Studio 中，选择您的设备作为部署目标，然后点击 Run。
persistent_cloud_anchor_java 应该会在您的设备上启动，提示 ARCore 检测设备摄像头前方的平面。
如果 Google Cloud 授权失败，请参阅问题排查步骤。
放置锚点
- 当应用开始检测平面后，点按屏幕即可在检测到的其中一个平面上放置锚点。
- 点按 HOST 按钮以托管已放置的锚点。这将向 ARCore API 发送一个托管请求，其中包含表示锚点相对于附近可视特征的位置的数据。
成功的托管请求将在所放置的位置创建一个锚点，并为其分配一个云锚点 ID。如果主机请求成功，应用应显示房间代码。您可以在任何设备上使用此代码访问此房间之前托管的锚点。
解析锚点
- 点按解析并输入之前返回的房间代码，即可访问此会议室中托管的锚点。这将向 ARCore API 发送一个解析请求，后者会返回房间中当前托管的所有锚点的 ID。
persistent_cloud_anchor_java 将使用这些 ID 渲染连接到托管锚点的 3D 对象。
云锚点
运行应用
- 确保您的设备已启用开发者选项和 USB 调试。
- 通过 USB 将设备连接到开发机器。
- 在 Android Studio 中，选择您的设备作为部署目标，然后点击 Run。
cloud_anchor_java 应该会在您的设备上启动，提示 ARCore 检测设备摄像头前方的平面。
错误：com.google.firebase.database.DatabaseException: Failed to get FirebaseDatabase instance: Specify DatabaseURL within FirebaseApp or from your getInstance
如果遇到此错误，请确保 google-services.json 中存在 firebase_url 属性。若要获得此属性的正确值，请确保已创建 Realtime Database 并下载 google-services.json。
放置锚点
- 当应用开始检测平面后，点按屏幕即可在检测到的其中一个平面上放置锚点。
- 点按 HOST 按钮以托管已放置的锚点。这将向 ARCore API 发送一个托管请求，其中包含表示锚点相对于附近可视特征的位置的数据。
成功的托管请求将在所放置的位置创建一个锚点，并为其分配一个云锚点 ID。如果主机请求成功，应用应显示房间代码。您可以在任何设备上使用此代码访问此房间之前托管的锚点。
解析锚点
- 点按解析并输入之前返回的房间代码，即可访问此会议室中托管的锚点。这将向 ARCore API 发送一个解析请求，后者会返回房间中当前托管的所有锚点的 ID。
cloud_anchor_java 将使用这些 ID 渲染连接到托管锚点的 3D 对象。
后续步骤
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-07-26。
[null,null,["最后更新时间 (UTC)：2025-07-26。"],[[["\u003cp\u003eExplore Cloud Anchors functionality using the \u003ccode\u003ecloud_anchor_java\u003c/code\u003e and \u003ccode\u003epersistent_cloud_anchor_java\u003c/code\u003e sample apps within the ARCore SDK.\u003c/p\u003e\n"],["\u003cp\u003ePersistent Cloud Anchors enable collaborative projects and persist for over 24 hours, while standard Cloud Anchors support multi-player use cases.\u003c/p\u003e\n"],["\u003cp\u003eBefore running the apps, ensure you have the necessary hardware and software, including an ARCore-supported device and Android Studio.\u003c/p\u003e\n"],["\u003cp\u003eAuthorize ARCore API calls using keyless authorization for Persistent Cloud Anchors and API key authorization for Cloud Anchors.\u003c/p\u003e\n"],["\u003cp\u003eHost and resolve anchors within the sample apps to experience Cloud Anchor functionality, placing and rendering 3D objects in shared AR experiences.\u003c/p\u003e\n"]]],["The content guides users to experiment with Cloud Anchors using two sample apps: `cloud_anchor_java` and `persistent_cloud_anchor_java`. These apps demonstrate hosting and resolving anchors via the ARCore API. Key actions include: installing prerequisites, opening the sample app in Android Studio, setting up Cloud Anchor ID sharing (using either keyless authorization or API key authorization), running the app, placing and hosting an anchor, and resolving an anchor using a room code. `Persistent_cloud_anchor_java` uses keyless authorization and local ID sharing. `cloud_anchor_java` uses API key authorization and Firebase for ID sharing.\n"],null,["# Cloud Anchors quickstart for Android\n\nTry out hosting and resolving [Cloud Anchors](/ar/develop/java/cloud-anchors/introduction) in the `cloud_anchor_java` and `persistent_cloud_anchor_java` sample apps.\n\nWhich sample app should you use?\n--------------------------------\n\nCloud Anchors are [anchors](/ar/develop/java/anchors) that are hosted on the [**ARCore API**](https://console.cloud.google.com/apis/library/arcore) cloud endpoint. This API enables users to share experiences in the same app. **Persistent Cloud Anchors** are Cloud Anchors that can be hosted for more than 24 hours.\n\n- `persistent_cloud_anchor_java` is an implementation of a collaborative project use case. It uses keyless authorization to authorize ARCore API calls. Because it doesn't use a Firebase backend to share Cloud Anchor IDs between devices, it is much easier to get up and running.\n- `cloud_anchor_java` is an implementation of a multi-player use case. It uses an API key to authorize ARCore API calls.\n\nPrerequisites\n-------------\n\n- Understand how [anchors](/ar/develop/java/anchors) and [Cloud Anchors](/ar/develop/java/cloud-anchors/introduction) work.\n- [Install and configure](/ar/develop/java/quickstart) the ARCore SDK for Android.\n\nRequirements\n------------\n\n### Hardware\n\n- An [ARCore supported device](/ar/devices) with the latest version of [Google Play Services for AR](https://play.google.com/store/apps/details?id=com.google.ar.core) installed\n- A USB cable to connect the device to your development machine\n\n### Software\n\n- [Android Studio](https://developer.android.com/studio) version 3.0 or later with Android SDK Platform version 7.0 (API level 24) or higher\n- The ARCore SDK for Android, which you can get in one of two ways:\n - Download it from [GitHub](https://github.com/google-ar/arcore-android-sdk) and extract it on your machine\n - Clone the repository with the following command: \n\n ```\n git clone https://github.com/google-ar/arcore-android-sdk.git\n ```\n\nOpen the sample app in Android Studio\n-------------------------------------\n\nThe ARCore SDK provides the `cloud_anchor_java` and `persistent_cloud_anchor_java` sample apps to demonstrate Cloud Anchors functionality. Follow these steps to open the apps in Android Studio. \n\n### Persistent Cloud Anchors\n\n1. In Android Studio, click **Open**.\n\n2. Navigate to the place where the **arcore-android-sdk** directory is stored on your machine. Do not open the entire SDK folder. Instead, go to **samples** \\\u003e **persistent_cloud_anchor_java** and click **Open**.\n\n### Cloud Anchors\n\n1. In Android Studio, click **Open**.\n\n2. Navigate to the place where the **arcore-android-sdk** directory is stored on your machine. Do not open the entire SDK folder. Instead, go to **samples** \\\u003e **cloud_anchor_java** and click **Open**.\n\nSet up Cloud Anchor ID sharing\n------------------------------\n\n**Cloud Anchor IDs** are strings that identify hosted Cloud Anchors. They are used to resolve, or render the 3D objects attached to, the hosted anchors. \n\n### Persistent Cloud Anchors\n\nCloud Anchor ID sharing is maintained locally in the app. You won't need to do anything here.\n\n### Cloud Anchors\n\nThe `cloud_anchor_java` sample app uses Firebase's Realtime Databases to share Cloud Anchor IDs between devices. You can use a different solution in your own apps.\n\n1. [Manually add Firebase to your app.](https://firebase.google.com/docs/android/setup#manually_add_firebase) The `cloud_anchor_java` package name is `com.google.ar.core.examples.java.cloudanchor`. You can find it in `main/AndroidManifest.xml`.\n2. Download the `google-services.json` file that you generated when you added Firebase to your app.\n3. [Create a Realtime Database with Firebase.](https://firebase.google.com/docs/database/android/start#create_a_database)\n4. In Android Studio, add the `google-services.json` file to your project's `app` directory.\n\nAuthorize ARCore API calls\n--------------------------\n\nAuthorize calls to the ARCore API to host and resolve Cloud Anchors for your\napp. Follow steps for on [Use the ARCore API on Google\nCloud](/ar/develop/authorization?platform=android) and use **Keyless\nauthorization** for Persistent Cloud Anchors or **API Key authorization** for\nCloud Anchors.\n\nBuild and run the sample app\n----------------------------\n\n### Persistent Cloud Anchors\n\n### Run the app\n\n1. Make sure that your device has enabled [developer options and USB debugging](https://developer.android.com/studio/debug/dev-options).\n2. Connect your device via USB to your development machine.\n3. In Android Studio, select your device as the deployment target and click **Run**.\n\n`persistent_cloud_anchor_java` should launch on your device, prompting ARCore to detect the planes in front of the device's camera.\n\nIf Google Cloud authorization fails, see [Troubleshooting steps](/ar/develop/authorization/troubleshooting?platform=android).\n\n### Place an anchor\n\n1. Once the app begins to detect planes, tap your screen to place an anchor on one of the detected planes.\n2. Tap the **HOST** button to host the placed anchor. This sends a host request to the ARCore API, which includes data representing the anchor's position relative to the visual features near it.\n\nA successful host request establishes an anchor at the placed location and assigns it a Cloud Anchor ID. If the host request is successful, the app should display a room code. You can use this code to access previously hosted anchors for this room on any device.\n\n### Resolve an anchor\n\n1. Tap **RESOLVE** and enter a previously returned room code to access the anchors hosted in this room. This sends a resolve request to the ARCore API, which returns the IDs of all anchors currently hosted in the room. `persistent_cloud_anchor_java` will use these IDs to render 3D objects attached to the hosted anchors.\n\n### Cloud Anchors\n\n### Run the app\n\n1. Make sure that your device has enabled [developer options and USB debugging](https://developer.android.com/studio/debug/dev-options).\n2. Connect your device via USB to your development machine.\n3. In Android Studio, select your device as the deployment target and click **Run**.\n\n`cloud_anchor_java` should launch on your device, prompting ARCore to detect the planes in front of the device's camera. \n\n#### Error: `com.google.firebase.database.DatabaseException: Failed to get FirebaseDatabase instance: Specify DatabaseURL within FirebaseApp or from your getInstance`\n\nIf you encounter this error, ensure that the `firebase_url` property is present in `google-services.json`. You can obtain the correct value for this property by ensuring that the Realtime Database has been created and downloading `google-services.json`.\n\n*** ** * ** ***\n\n### Place an anchor\n\n1. Once the app begins to detect planes, tap your screen to place an anchor on one of the detected planes.\n2. Tap the **HOST** button to host the placed anchor. This sends a host request to the ARCore API, which includes data representing the anchor's position relative to the visual features near it.\n\nA successful host request establishes an anchor at the placed location and assigns it a Cloud Anchors ID. If the host request is successful, the app should display a room code. You can use this code to access previously hosted anchors for this room on any device.\n\n### Resolve an anchor\n\n1. Tap **RESOLVE** and enter a previously returned room code to access the anchors hosted in this room. This sends a resolve request to the ARCore API, which returns the IDs of all anchors currently hosted in the room. `cloud_anchor_java` will use these IDs to render 3D objects attached to the hosted anchors.\n\nWhat's next\n-----------\n\n- Create a Cloud Anchors app with the [ARCore Cloud Anchors with persistent Cloud Anchors codelab](https://codelabs.developers.google.com/codelabs/arcore-cloud-anchors#0).\n- Learn how to incorporate Cloud Anchors in your app with the [Cloud Anchors developer guide](/ar/develop/java/cloud-anchors/developer-guide).\n- Manage Cloud Anchors outside of your ARCore app using the [Cloud Anchors Management API](/ar/develop/java/cloud-anchors/management-api)."]]
