The older ARCore Cloud Anchor API cloud endpoint has been deprecated and will not be supported after August 31, 2023. If your app is using this API, you must update it to use the new ARCore API cloud endpoint as soon as possible.

Cloud Anchors developer guide for Android (Kotlin/Java)

Learn how to use Cloud Anchors in your own apps.

Prerequisites

Make sure that you understand fundamental AR concepts and how to configure an ARCore session before proceeding.

If you are new to Cloud Anchors:

Make sure that you understand how anchors and Cloud Anchors work.
Read through the Cloud Anchors quickstart for system requirements, setup, and installation instructions.

Enable the ARCore API

Before using Cloud Anchors in your app, you must first enable the ARCore API in your application.

Enable Cloud Anchor capabilities in the session configuration

Once Cloud Anchors functionality has been enabled in your app, enable Cloud Anchors capabilities in your app’s AR session configuration so that it can communicate with the ARCore API:

Java

Config config = new Config(session);
config.setCloudAnchorMode(Config.CloudAnchorMode.ENABLED);
session.configure(config);

Kotlin

val config = Config(session)
config.cloudAnchorMode = Config.CloudAnchorMode.ENABLED
session.configure(config)

Host a Cloud Anchor

Hosting starts with a call to hostCloudAnchorAsync(). ARCore will upload visual data, device poses, and the anchor pose to the ARCore API. The API then processes this information to construct a 3D feature map, ultimately returning a unique Cloud Anchor ID for the anchor to the device.

You can also extend the lifetime of a hosted anchor using the ARCore Cloud Anchor Management API.

Your app should follow these steps to complete hosting of a Cloud Anchor:

Call hostCloudAnchorAsync().
Wait for the callback, or continually check the Future state until it is done.
Check the result state to determine if the operation succeeded, or interpret the error code if it failed.
Share the result Cloud Anchor ID with other clients, and use it to resolve the Cloud Anchor with resolveCloudAnchorAsync().

Check the mapping quality of feature points

Session.FeatureMapQuality indicates the quality of feature points seen by ARCore in the preceding few seconds from a given camera pose. Cloud Anchors hosted using higher quality features are generally more accurately resolved. Use Session.estimateFeatureMapQualityForHosting() to obtain an estimation for the feature map quality for a given camera pose.

Value	Description
`INSUFFICIENT`	The quality of feature points identified from the pose in the preceding few seconds is low. This state indicates that ARCore will likely have more difficulty resolving the Cloud Anchor. Encourage the user to move the device so that the desired position of the Cloud Anchor that they wish to host can be viewed from different angles.
`SUFFICIENT`	The quality of feature points identified from the pose in the preceding few seconds is likely sufficient for ARCore to successfully resolve a Cloud Anchor, although the accuracy of the resolved pose will likely be reduced. Encourage the user to move the device so that the desired position of the Cloud Anchor that they wish to host can be viewed from different angles.
`GOOD`	The quality of feature points identified from the pose in the preceding few seconds is likely sufficient for ARCore to successfully resolve a Cloud Anchor with a high degree of accuracy.

Resolve a previously hosted anchor

Call resolveCloudAnchorAsync() to resolve a hosted Cloud Anchor. The ARCore API periodically compares visual features from the scene against the anchor’s 3D feature map to pinpoint the user's position and orientation relative to the anchor. When it finds a match, the API returns the pose of the hosted Cloud Anchor.

You can initiate resolves for multiple Cloud Anchors in sequence. Up to 40 concurrent Cloud Anchor operations can exist at a time.

Cancel an operation or remove a Cloud Anchor

Call cancel() to cancel a pending Cloud Anchor operation. Call detach() to remove an already-resolved Cloud Anchor from the app.

Check the result state of a Cloud Anchor operation

Use Anchor.CloudAnchorState to check the result status of the hosting or resolving operation, including errors.

Value	Description
`ERROR_CLOUD_ID_NOT_FOUND`	Resolving failed because the ARCore API could not find the provided Cloud Anchor ID.
`ERROR_HOSTING_DATASET_PROCESSING_FAILED`	Hosting failed because the server could not successfully process the dataset for the given anchor. Try again after the device has gathered more data from the environment.
`ERROR_HOSTING_SERVICE_UNAVAILABLE`	The ARCore API was unreachable. This can happen for a number of reasons. The device might be in airplane mode or may not have a working Internet connection. The request sent to the server might have timed out with no response. There might be a bad network connection, DNS unavailability, firewall issues, or anything else that might affect the device's ability to connect to the ARCore API.
`ERROR_INTERNAL`	A hosting or resolving task for this anchor finished with an internal error. The app should not attempt to recover from this error.
`ERROR_NOT_AUTHORIZED`	The authorization provided by the application is not valid. See Troubleshooting problems with ARCore API authorization.
`ERROR_RESOLVING_SDK_VERSION_TOO_NEW`	The Cloud Anchor could not be resolved because the SDK version used to resolve the anchor is newer than, and incompatible with, the version used to host it.
`ERROR_RESOLVING_SDK_VERSION_TOO_OLD`	The Cloud Anchor could not be resolved because the SDK version used to resolve the anchor is older than, and incompatible with, the version used to host it.
`ERROR_RESOURCE_EXHAUSTED`	The application has exhausted the request quota allotted to the given Google Cloud project. You should request additional quota for the ARCore API for your project from the Google Developers Console.
`SUCCESS`	A hosting or resolving task for this anchor completed successfully.

API quotas for host and resolve requests

The ARCore API has the following quotas for request bandwidth:

Quota type	Maximum	Duration	Applies to
Number of anchors	unlimited	N/A	project
Anchor host requests	30	minute	IP address and project
Anchor resolve requests	300	minute	IP address and project

Best practices for a good user experience

Instruct users to do the following to ensure a good user experience on your app:

Wait a few seconds after the session starts before attempting to host an anchor (by placing an object, etc.). This gives the tracking some time to stabilize.
When selecting a location to host the anchor, try to find an area with visual features that are easily distinguishable from one another. For best results, avoid reflective surfaces or surfaces that lack visual features, such as blank white walls.
Keep the camera trained on the center of interest and move the device around the center of interest to map the environment from different angles, maintaining roughly the same physical distance as you do so. This will help capture more visual data and make resolving more robust.

Note: Moving around the center of interest is not the same as standing in one place and rotating, as someone might do when taking a panorama shot. Users should physically move around the environment.
Make sure that there is sufficient lighting in the real-life environment while hosting and resolving Cloud Anchors.

Deprecation policy

Apps built with ARCore SDK 1.12.0 or higher are covered by the Cloud Anchor API deprecation policy.
Apps built with ARCore SDK 1.11.0 or lower are unable to host or resolve Cloud Anchors due to the SDK's use of an older, deprecated ARCore API.

What’s next

Create a Cloud Anchors app with the ARCore Cloud Anchors with persistent Cloud Anchors codelab.
Walk through hosting and resolving Cloud Anchors through two sample apps in the Cloud Anchors quickstart.
Manage Cloud Anchors outside of your ARCore app using the Cloud Anchors Management API.
Check out the Android reference documentation for more ways to use ARCore in your app.