Cloud Anchors developer guide for Android NDK

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:

  • Read through the quickstart for system requirements, setup, and installation instructions.
  • Check out one of the Cloud Anchor samples

Enable ARCore Cloud Anchor API

Before using Cloud Anchors in your app, you must first enable the ARCore Cloud Anchor API in a new or existing Google Cloud Platform project.

Enable Cloud Anchors in your app

Cloud Anchors are disabled by default in the AR session config. To enable Cloud Anchor capabilities in your app:

  1. Enable Cloud Anchor capabilities in your AR session config.

  2. Resume the AR session.

Host a Cloud Anchor with persistence

Prior to ARCore SDK 1.20.0, 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 1 and 365 days.

You can also extend the lifetime of the anchor after it is 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:

  1. If your app’s AndroidManifest.xml file contains an API key, remove it.

  2. Create an OAuth client for your Android app in the Google Developers Console, using the app’s application ID and signing certificate fingerprint. This associates the Android application ID with your Google Cloud Platform project.

  3. Include com.google.android.gms:play-services-auth:16+ in your app’s dependencies.

  4. If you are using ProGuard, add it to your app’s build.gradle file with

    buildTypes {
  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 increase due to higher network usage and CPU utilization.

Next steps