Learn how to use the Cloud Anchor API in your own apps. 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 Android 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 the persistent cloud anchors, you can now use
ArSession_hostAndAcquireNewCloudAnchorWithTtl()
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.
/// This creates a new Cloud Anchor with a given lifetime in days, using the
/// pose of the provided @p anchor.
///
/// The cloud state of the returned anchor will be set to
/// #AR_CLOUD_ANCHOR_STATE_TASK_IN_PROGRESS. The initial pose
/// will be set to the pose of the provided @p anchor. However, the returned
/// anchor and the original @p anchor are completely independent of one another,
/// and the two poses may diverge over time.
///
/// Hosting requires a working internet connection and an active ARCore session for
/// which the ::ArTrackingState is #AR_TRACKING_STATE_TRACKING.
/// If ARCore is unable to establish a connection to the ARCore Cloud Anchor service,
/// it will continue to retry silently in the background.
///
/// @param[in] session The ARCore session.
/// @param[in] anchor The anchor with the desired pose. Will be used to create a
/// hosted Cloud Anchor.
/// @param[in] ttl_days The lifetime of the anchor in days. Must be positive.
/// The maximum allowed value is 1 if using an API Key to authenticate with
/// the ARCore Cloud Anchor service. Otherwise, the maximum allowed value is
/// 365.
/// @param[inout] out_cloud_anchor The new Cloud Anchor.
/// @return #AR_SUCCESS or any of:
/// - #AR_ERROR_INVALID_ARGUMENT
/// - #AR_ERROR_NOT_TRACKING
/// - #AR_ERROR_SESSION_PAUSED
/// - #AR_ERROR_CLOUD_ANCHORS_NOT_CONFIGURED
/// - #AR_ERROR_RESOURCE_EXHAUSTED
/// - #AR_ERROR_ANCHOR_NOT_SUPPORTED_FOR_HOSTING
ArStatus ArSession_hostAndAcquireNewCloudAnchorWithTtl(
ArSession* session, const ArAnchor* anchor, int32_t ttl_days,
ArAnchor** out_cloud_anchor);
Authentication
Your app needs a form of authentication to use Cloud Anchors. To create a Cloud Anchor with a TTL longer than twenty-four hours, the API will need to use keyless authentication.
Follow these steps to configure keyless API access:
If your app’s
AndroidManifest.xml
file contains an API key, remove it.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 project.
Include
com.google.android.gms:play-services-auth:16+
in your app’s dependencies.If you are using ProGuard, add it to your app’s
build.gradle file
withbuildTypes { release { ... proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro' } }
And add the following to your app’s
proguard-rules.pro
file:-keep class com.google.android.gms.common.** { *; } -keep class com.google.android.gms.auth.** { *; } -keep class com.google.android.gms.tasks.** { *; }
Mapping quality
The mapping quality API estimates the quality of the visual feature points that
ARCore sees from the provided 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 AR_FEATURE_MAP_QUALITY_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.
/// Estimates the quality of the visual feature points that ARCore sees from the
/// provided camera pose. Cloud Anchors hosted using higher quality features
/// generally result in easier and more accurately resolved Cloud Anchor poses.
///
/// @param[in] session The ARCore session.
/// @param[in] pose The camera pose to use in estimating the quality.
/// @param[out] out_feature_map_quality The estimated quality of the visual
/// feature points that ARCore sees from the provided camera pose.
/// @return #AR_SUCCESS or any of:
/// - #AR_ERROR_INVALID_ARGUMENT
/// - #AR_ERROR_NOT_TRACKING
/// - #AR_ERROR_SESSION_PAUSED
/// - #AR_ERROR_CLOUD_ANCHORS_NOT_CONFIGURED
ArStatus ArSession_estimateFeatureMapQualityForHosting(
const ArSession* session, const ArPose* pose,
ArFeatureMapQuality* out_feature_map_quality);
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.