Google is committed to advancing racial equity for Black communities. See how.

Cloud Anchors developer guide for Android

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.

Enable Cloud Anchors in your app

Before enabling Cloud Anchors in your app, you must enable the ARCore Cloud Anchor API in a new or existing Google Cloud Platform project. To learn more, review the Cloud Anchors sample quickstart (Android, iOS).

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 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 hostCloudAnchorWithTtl() 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.

 /**
  * Uses the pose and other data from {@code anchor} to create a new anchor with a
  * given lifetime in days that will be hosted. The returned {@code anchor} will
  * have the Cloud Anchor state {@link Anchor.CloudAnchorState#TASK_IN_PROGRESS}.
  *
  * @param anchor The anchor whose pose is to be hosted.
  * @param ttlDays 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.
  * @return The new anchor with the same pose as {@code anchor} which will be
  *     hosted.
  */
 public Anchor hostCloudAnchorWithTtl(Anchor anchor, int ttlDays);

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

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 = session.estimateFeatureMapQualityForHosting(frame.getCamera().getPose());

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 they wish to host
    // can be 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.

Next steps