Learn how to use the Cloud Anchor API 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 the process used to host and resolve a Cloud Anchor.
- Read through the quickstart for system requirements, setup, and installation instructions.
- Check out the ARCore SDK for Unity sample app.
Enable Cloud Anchors in your app
Cloud Anchors are disabled by default in ARCore. The sample app ships with Cloud Anchors enabled for demo purposes only. You can enable Cloud Anchor capabilities in your session configuration, and enable the ARCore Cloud Anchor API for your Google Cloud Platform project.
Host a Cloud Anchor with persistence
Prior to ARCore v1.20, Cloud
Anchors could only be resolved for up to 24 hours after they were first hosted.
With persistent Cloud Anchors, you can now use XPSession.CreateCloudAnchor()
to create a Cloud Anchor with a time to live (TTL) between one and 365 days. You
can also extend the lifetime of the anchor after it is already hosted using the
Cloud Anchor Management API.
// ttlDays: The anchor’s lifetime in days. Must be a positive number. The maximum
// allowed value is 1 if you are using an API key to authenticate the Cloud Anchor.
// Otherwise, the maximum allowed value is 365.
AsyncTask<CloudAnchorResult> GoogleARCore.CrossPlatform.XPSession.CreateCloudAnchor(
UnityARUserAnchorComponent anchor, int ttlDays
)
Authentication
Your app needs a form of authentication to use Cloud Anchors. When targeting Android, Unity offers the Keyless and API Key options for authentication. Cloud Anchors with a TTL greater than one day must use Keyless authentication.
The default authentication strategy for new Unity projects built with ARCore
v1.24 or later is DoNotUse. This is to prevent apps from being built with
unnecessary libraries. If your app uses Cloud Anchors and is built using ARCore
v1.24 or later, you must manually enable authentication in the Unity project
settings.
Keyless authentication
The Keyless authentication option can host a Cloud Anchor for up to 365 days. Cloud Anchors with a TTL greater than one day must use this method.
Follow these steps to configure authentication without using an API key:
Select Keyless to clear any API key stored from the previous Cloud Anchors setting and to add necessary dependencies and Proguard exceptions. If you previously used an API key and no longer need it, we recommend deleting it in the Google Developers Console and removing it from your app after migrating users to the newest version.
Create an OAuth client for your Android app in the Google Developers Console, using the app’s Android package name and signing certificate fingerprint. This associates the Android package name with your GCP project.
API key authentication
The API key authentication option can host a Cloud Anchor for up to one day.
Follow these steps to obtain and add an API key to your project:
See the Google Cloud Platform Console Help Center to obtain an API key.
Add the new API key to your project:
- In Unity, go to Edit > Project Settings > ARCore Project Settings.
- Add your API key to the Cloud Anchor API Keys field.
Mapping quality
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 generally result in more accurately resolved poses. If feature
map quality cannot be estimated for a given pose, ARCore logs a warning message
and returns FeatureMapQuality.Insufficient. 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 to be
hosted is viewed from different angles.
FeatureMapQuality quality = GoogleARCore.CrossPlatform.XPSession.EstimateFeatureMapQualityForHosting(pose)
public enum FeatureMapQuality
{
/// 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 to be hosted is
/// viewed from different angles.
Insufficient = 0,
/// 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 they wish to host can be viewed from different angles.
Sufficient = 1,
/// 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.
Good = 2,
}
API quotas
The ARCore Cloud Anchor 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 |
Performance considerations
Memory usage increases when you enable the Cloud Anchor API. Expect the device’s battery usage to rise due to higher network usage and CPU utilization.